omnideconv / spacedeconv

A unified interface to spatial transcriptomics deconvolution tools

🚀 spacedeconv

spacedeconv is a unified interface to 31 deconvolution tools with focus on spatial transcriptomics datasets. The package is able to directly estimate celltype proportions of immune cells and can deconvolute any celltype if an annotated single-cell reference dataset is available.

⬇️ Installation

spacedeconv is available from GitHub only. We recommend installing trough the pak package manager:

# install the pak package manager
install.packages("pak")

# recommended installation, deconvolution tools are installed on-demand
pak::pkg_install("omnideconv/spacedeconv")

# full installation including all deconvolution tools
pak::pkg_install("omnideconv/spacedeconv", dependencies=TRUE)

✨ Features

• unified access to 31 deconvolution tools
• direct deconvolution of immune cells
• compute custom reference signatures to deconvolute any celltype
• flexible visualization functions
• resource optimization
• Pathway and Transcription Factor analysis (decoupleR integration)
• Ligand-Receptor analysis
• easy integration into spatial transcriptomics workflows

💾 Data requirements

Spatial transcriptomics data: SpatialExperiment

Single-cell data with cell-type annotation: SingleCellExperiment (recommended), anndata or Seurat

🧑‍💻 Usage

The main workflow consists of:

1. Reference signature computation using annotated single-cell data
2. Deconvolution
3. Visualization

1. Build a Signature Matrix

Build a cell type specific signature matrix from annotated single-cell reference data.

signature <- spacedeconv::build_model(
  single_cell_object,
  cell_type_col = "celltype_major",
  method = "spotlight",
  assay_sc="cpm"
)

2. Deconvolution

While some methods are able to directly estimate immune cell abundances other tools require a custom reference signature computed in step 1).

result <- spacedeconv::deconvolute(
  spatial_object,
  signature,
  method = "spotlight"
)

3. Visualization

spacedeconv includes highly-flexible visualization functions. A full explanation of all visualization options can be found in the visualization vignette.

plot_celltype(spe, cell_type="spotlight_B.cells")

💡 Additional Requirements

Most methods do not require additional software/tokens, but there are a few exceptions:

• A working version of Docker is required for CIBERSORTx
• A token for CIBERSORTx is required from this website: https://cibersortx.stanford.edu/
• The CIBERSORT source code is required for BSeq-sc (see tutorial in ?omnideconv::bseqsc_config)
• SpatialExperiment requires magick to be installed: sudo apt-get install libmagick++-dev

Available methods, Licenses, Citations

Note that, while spacedeconv itself is free (GPL 3.0), you may need to obtain a license to use the individual methods. See the table below for more information. If you use this package in your work, please cite both our package and the method(s) you are using.

First-gen (immunedeconv)	First-gen mouse (immunedeconv)	Second-gen (omnideconv + spatial Methods)
MPCcounter EPIC quanTIseq xCell CIBERSORT CIBERSORT (abs.) TIMER ConsensusTME ABIS ESTIMATE	mMCPcounter seqImmuCC DCP BASE	RCTD SPOTlight CARD spatialDWLS Cell2location AutoGeneS BayesPrism Bisque Bisque Bseq-sc CIBERSORTx CDseq CPM DWLS MOMF MuSiC Scaden SCDC

References

Method	signature	licence	citation
omnideconv	✔️	GPL-3	Citation will follow
immunedeconv	❌	BSD	Sturm, G., Finotello, F., Petitprez, F., Zhang, J. D., Baumbach, J., Fridman, W. H., ..., List, M., Aneichyk, T. (2019). Comprehensive evaluation of transcriptome-based cell-type quantification methods for immuno-oncology. Bioinformatics, 35(14), i436-i445.
spatialDWLS	✔️	MIT	Dong R, Yuan GC. SpatialDWLS: accurate deconvolution of spatial transcriptomic data. Genome Biol. 2021 May 10;22(1):145. doi: 10.1186/s13059-021-02362-7
cell2location	✔️	Apache-2.0	Kleshchevnikov, V., Shmatko, A., Dann, E. et al. Cell2location maps fine-grained cell types in spatial transcriptomics. Nat Biotechnol (2022). https://doi.org/10.1038/s41587-021-01139-4
SPOTlight	✔️	GPL 3.0	Elosua-Bayes M, Nieto P, Mereu E, Gut I, Heyn H (2021): SPOTlight: seeded NMF regression to deconvolute spatial transcriptomics spots with single-cell transcriptomes. Nucleic Acids Res 49(9):e50. doi:10.1093/nar/gkab043.
RCTD	✔️	GPL 3.0	Cable, D.M., Murray, E., Zou, L.S. et al. Robust decomposition of cell type mixtures in spatial transcriptomics. Nat Biotechnol 40, 517–526 (2022). https://doi.org/10.1038/s41587-021-00830-w
CARD	✔️	GPL-3.0	Ying Ma, and Xiang Zhou (2022). Spatially informed cell type deconvolution for spatial transcriptomics. https://doi.org/10.1038/s41587-022-01273-7

spacedeconv's Issues

Spatial Image: Orientation Offset

The plotting function with hexagons works with a correctly rotated spatial image. Older SpaceRanger Versions (<V2.0) may have differently rotated images (+-90 degrees). Since the angle of the spots is rotated by 30 degrees then the hexagons appear to be rotated too and don't touch as intended.

Introduce a "offset_rotation" parameter to fix the hexagon rotation in this case. Default should be the standard case (spatial image has hourglass on top left)

Update Plotting Function

Update Plotting function to support fully custom plot titles, without adding _smoothed!

plot_most_abundant RColorBrewerPalettes, qualitative

Could you please add a qualitative palette to the plot_most_abundant function and maybe also RColorBrewerPalettes?
Thanks :)

Check Rownames - Gene ID

Introduce check to prevent SpaceDeconv from failing if rownames come in the wrong format.
(For Example: Inputting ENSEMBL IDs but running immunedeconv functions, it will start but fail directly)

After deconvolution info

Add a module to print stats and info/computation time after deconvolution.

Extract method from cell type name

Extraction of cell type name from mcp_counter_celltypes does not work as intendet. I tried to use plot_celltype_presence(spe, cell_type = "mcp_counter_B.cell") but it does not work. The problem should be the extraction of the method from the cell type name.

Example:
unlist(strsplit("mcp_counter_B.cell", "_"))[1]
[1] "mcp"

Spatial Image: Namespace Problem

There is a notification appearing all the time when loading a spatial dataset:

Found more than one class "SpatialImage" in cache; using the first, from namespace 'SpatialExperiment'
Also defined by ‘SeuratObject’

Probably SpatialExperiment related but kind of annoying, so either suppress the message or fix the namespace loading / manually unload the spatialImage from Seurat.

Update Clustering

• Add Clustering of deconvolution results
• Add more clustering methods
• if possible: progress indicator (clusteR??)
• Add clustering to vignette

Plot number of detected genes

I would like to have a function for plotting the number of detected genes as spatial plot and the density distribution beside.

Plotting Function: Remove Palette Type parameter

Right now users have to specify the type of data (discrete, etc.). We can probably extract this information from the colData Dataframe directly and remove the paramter.

Package Name

Just wondering, immunedeconv and omnideconv both have lower case names. Should we rename SpaceDeconv to spacedeconv?

CPM normalization unpacks sparse matrices

Reimplement cpm normalization to work on sparse matrices

Time expectations

Create Table with time and Memory / CPU / resource expectations for different methods

Omnideconv and Immunedeconv in SpaceDeconv

How should omnideconv and immunedeconv methods be named in SpaceDeconv?

I think it doesn't make much sense to use "omnideconv" as method and introduce a "submethod", so we have basically two options:

• Just use the methods name (dwls, scdc, quantiseq)
• With prefix (omn_dwls, imm_quantiseq) (prefix could be anything)

As the methods have different scopes (for example first / second generation differences) a prefix could be a useful solution or we just introduce all methods in the spaceDeconv documentation

Zero Variable Genes

Check for zero variable genes and remove them

Iniche correlation

The localization_heatmap function does not consider iniches for the correlation. The iniches could be computet with the get_inichefunction, then the scores within the iniche might be averaged to enable for cell pair wise correlation analysis.

Plotting Function: Disable Density Plot for Discrete Color Scales

Remove the Density plot for discrete color scales as this does not make any sense there

Embedded methods

SpaceDeconv will provide a unified interface to methods for deconvolution spatial transcriptomics (ST) data:

1. 1st-generation method (human and mouse) available through immunedeconv;
2. 2nd-generation methods available through omnideconv;
3. Ad hoc ST methods (only for Visium?).

For point 3, a literature review is needed, but this could be a starting point:

• SpatialDWLS
• Cell2location
• Spotlight
• RCTD
• DestVI
• CARD
• SpatialDecon
• STdeconvolve (?) Reference-free/complete deconvolution, check how final cell identities are assigned
• Giotto enrichment methods (?)

Fixing color-mapped density plots

The color-mapped density distribution from SpaceDeconv::plot_celltype() continues to have some problems so i removed the color mapping. As this was a nice feature i would like to reintroduce this in the future but the whole "aes / variable not found" game should be fixed.

the function call contained a fill = after_stat(x) argument which caused a lot of trouble while rendering markdowns. I also tried wrapping it in aes_ or aes_string but this did not solve the issue.

https://github.com/omnideconv/SpaceDeconv/blob/ca463e7c0d9cc4a7aab6b8cbf8fc9f74b95d585f/R/visualization.R#L29-L35

Statistics

We should output some dataset statistics before starting a deconvolution/siganture building.

Useful information:

• umi count range (density???)
• number of spots with umi count < 500
• shared genes between signature and spatial dataset
• total genes
• range of detected genes per spot
• total cells
• total spots

Potentially:

• umi cutoff parameter: minimum umi to keep the spot

Should format this as a nice console output

Custom metacell size

Add parameter for custom metacell size (metacell has this parameter, stating the UMI count).

Fix normalization function

The normalization function saves the normalization in a different assay, but SpaceDeconv is currently only loading from counts assay.

Update all functions accordingly, this includes a call of SingleCellExperiment::assays(object, assayname) instead of SingleCellExperiment::counts()

cell2location version conflict

When installing with pak::pkg_install("omnideconv/spacedeconv", dependencies = T) ，the installation of cell2location is canceled because of conflicting dependencies. When I installed cell2location manually,the proper environment of cell2location installation can not match the spacedeconv environment.

Brief description of the problem

ERROR: Cannot install cell2location because these package versions have conflicting dependencies.

The conflict is caused by:
scvi-tools 0.20.3 depends on jaxlib>=0.4.3
scvi-tools 0.20.2 depends on jaxlib>=0.4.3
scvi-tools 0.20.1 depends on jaxlib>=0.4.3
scvi-tools 0.20.0 depends on jaxlib
scvi-tools 0.19.0 depends on jaxlib
scvi-tools 0.18.0 depends on jaxlib
scvi-tools 0.17.4 depends on jaxlib
scvi-tools 0.17.3 depends on jaxlib
scvi-tools 0.17.2 depends on jaxlib
scvi-tools 0.17.1 depends on jaxlib
scvi-tools 0.17.0 depends on jaxlib

To fix this you could try to:

1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

SpaceDeconv Methods

This is a collection of SpaceDeconv deconvolution tools. Feel free to edit or comment. @omnideconv/core-team

Implemented (or not yet )

• Omnideconv
• Immunedeconv
• RCTD
• SPOTlight
• CARD
• spatialDWLS
• cell2location

Will not be used:

• [ ]

Plots dark background

Add option for black background

Improve Tests

To improve the deployment time we should introduce a small test dataset with only a few spots for fast deconvolution

Update aggregation function

Update Aggregation function to support a list of multiple cell types to aggregate, not just two

error on UBUNTU 22.04

Please briefly describe your problem and what output you expect. If you have a question, please don't use this form.
Instead, ask on our Community Forum

Please include a minimal reproducible example (AKA a reprex). If you've never heard of a reprex before, start by reading https://www.tidyverse.org/help/#reprex.

---

Brief description of the problem

I have installed all the dependencies, i receive this error when I install it from pak, i think it doesnt support UBUNTU OS?

# insert reprex here
```pak::pkg_install("omnideconv/spacedeconv", dependencies=TRUE)
! Using bundled GitHub PAT. Please add your own PAT using `gitcreds::gitcreds_set()`.
✔ Loading metadata database ... done

→ Will install 18 packages.
→ All 18 packages (9.65 MB) are cached.
+ CARD            1.1        [bld][cmp] (GitHub: 2d64b91)
+ ComICS          1.0.4      [bld]
+ concaveman      1.1.0      [bld] + ✔ libgdal-dev, ✔ gdal-bin, ✔ libgeos-dev, ✔ libproj-dev
+ ConsensusTME    0.0.1.9000 [bld][cmp] (GitHub: b3c8d3a)
+ Giotto          4.0.2      [bld][cmp] (GitHub: 7b8ad7b)
+ GiottoClass     0.1.3      [bld][cmp] (GitHub: fca6eb3)
+ GiottoVisuals   0.1.4      [bld][cmp] (GitHub: e3feee4)
+ glmnet          4.1-8      [bld][cmp]
+ immunedeconv    2.1.0      [bld][cmp] (GitHub: 12196fb)
+ MCMCpack        1.7-0      [bld][cmp]
+ metafor         4.4-0      [bld]
+ MuSiC           0.3.0      [bld][cmp] (GitHub: 7b18b03)
+ omnideconv      0.0.0.9000 [bld][cmp] (GitHub: 29322c9)
+ RcppML          0.3.7      [bld][cmp]
+ singscore       1.14.0     [bld]
+ spacedeconv     0.0.1.0000 [bld][cmp] (GitHub: cd33d4e)
+ spacexr         2.2.1      [bld][cmp] (GitHub: 90cc7dc)
+ V8              4.4.1      [bld][cmp] + ✔ libnode-dev
✔ All system requirements are already installed.

ℹ No downloads are needed, 18 pkgs (9.65 MB) are cached
ℹ Building spacedeconv 0.0.1.0000
ℹ Building omnideconv 0.0.0.9000
ℹ Building metafor 4.4-0
ℹ Building MCMCpack 1.7-0
ℹ Building RcppML 0.3.7
ℹ Building V8 4.4.1
ℹ Building glmnet 4.1-8
ℹ Building GiottoClass 0.1.3
ℹ Building singscore 1.14.0
✖ Failed to build spacedeconv 0.0.1.0000
Error:
! error in pak subprocess
Caused by error in `stop_task_build(state, worker)`:
! Failed to build source package spacedeconv.
Type .Last.error to see the more details.
> .Last.error
<callr_error/rlib_error_3_0/rlib_error/error>
Error:
! error in pak subprocess
Caused by error in `stop_task_build(state, worker)`:
! Failed to build source package spacedeconv.
---
Backtrace:
1. pak::pkg_install("omnideconv/spacedeconv", dependencies = TRUE)
2. pak:::remote(function(...) get("pkg_install_do_plan", asNamespace("pak"))(...), …
3. err$throw(res$error)
---
Subprocess backtrace:
 1. base::withCallingHandlers(cli_message = function(msg) { …
 2. get("pkg_install_do_plan", asNamespace("pak"))(...)
 3. proposal$install()
 4. pkgdepends::install_package_plan(plan, lib = private$library, num_workers = nw, …
 5. base::withCallingHandlers({ …
 6. pkgdepends:::handle_events(state, events)
 7. pkgdepends:::handle_event(state, i)
 8. pkgdepends:::stop_task(state, worker)
 9. pkgdepends:::stop_task_build(state, worker)
10. base::throw(pkg_error("Failed to build source package {.pkg {pkg}}.", …
11. | base::signalCondition(cond)
12. global (function (e) …


#### Versions

<details>

[Paste the output of `sessionInfo()` leaving a blank line after the details tag]

</details>

Signature Corr Plot

Add a correlation plot to access signature quality

Could also copy from DeconvExplorer and add signature clustering

Plotting function

Add alpha/transparency option to plotting function. Goal: Plot one celltype and instead of black (zero expression/abundance) the plot is transparent.

--> Expression overlaying the tissue.

Maybe also a new plotting function.

Dependencies

Move as many dependencies as possible to "suggests"

Method Token

In some cases we extract the deconvolution method from the method_celltype token. This fails for methods containing an "_". We should introduce a utility function "extract_method" which handles all those cases and returns correct method names.

Create Minimal Package Version

We should bring SpaceDeconv to a minimal "package ready" form.

• Finish GitHub Markdown
• Create Documentation Website (Pkgdown)
• Create "Getting Started" Vignette
• Create "Input Data" Vignette
• Create "Visualization" Vignette
• Create "Walk Trough Example with Sample Data"
• Sample Datasets delivered with the package?
• #17
• Check All Variable/Parameter names: be consistent!
• improve roxygen comments, add samples
• Finish Omnideconv Assay Selection Feature
• List of First-Second Generation Tools in the Documentation
• Fix Visualization Functions, Legend issue!
• Add parameter to make spatial image optional
• Add deconvolution result token to identify method
• Add tests! (Current cov ca. 25%)

Type checks TODO:

• visualization function: does sample name exist in the data?
• Add check to make sure RCTD only uses unnormalized data
• Add "spatial_obj" typecheck for SPOTlight
• "batch_ids" for CARD

Please add/comment any additional tasks @FFinotello @FranziChiara @mzopog
Additional Features and Methods can still be added but we want to focus on the overall pacakge here

Fix addResultsToObject

The function adding deconvolution results to objects seems to be buggy if the dimensions of the data don't match.
The solution to fill the empty slots with NAs is okay but the data is not in the right order after this

Rename normalization function

Our normalization function is called "normalize" which introduces problems because many packages have a function named like this. Any ideas for a new name?

Choose License

What would be a reasonable License? Omnideconv uses GPL-3.0 and Immunedeconv has a custom one. @FFinotello @mlist @grst

Assay selection

Remove every usage of counts() or other related assay selection functions. Use assay() instead that the assay can be selected with a parameter

RCTD and Metacell combination

Metacell exports three different assays. The first one is named "metacell_counts"

Our RCTD wrapper does check for an assay named "counts" as the software requires unnormalized counts.

Change the implementation to support any assay and perform integer checking in another way.

HGNC Symbols

Immunedeconv requires HGNC symbols. The spatial datasets i worked with typically contained ENSEMBL / some form of gene symbol but not all HGNC.

Is this something we should require the user to manage or would it be benefical to implement something to convert the gene names? Often a simpel toupper() is kind of fixing the issue.

Trying to cut down on dependencies here :)

The toupper() solution fixes the HGNCs that are present in lowercase. All other genes are "filtered" by the intersect step between signature and sample as performed in omnideconv. This could remove genes which are otherwise "usable".

How to handle incomplete deconvolution results

Concerning the discussion about (pre)processing steps earlier today: i am working with a deconvolution method wich does not produce estimations for all spots, only those who match internal criteria. The returned result table contains information for less spots than originally intended. This is not very beneficial for adding the deconvolution results back to the input object.

Does it make sense to just set all the estimations for missing spots to zero? Na or NULL is quite unhandy when working on the visulization afterwards. The thing is the deconvolution did not estimate zero, there is just no estimation for the spot.

One can bypass this problem by manually resetting and lowering the methods QC parameters but then it is not running as recommended.

Spot Distances / Iniche

In several places we access surrounding spots, usually by measuring the distance between all spots to the center and using a limit / circle radius parameter. This approach comes with several downsides:

• The distance between spots is not exactly the same all the time
• The circular approach has limitations due to the hex arrangement of the spots. Therefore it is possible to miss some spots in the iniche

We should find a way to compute robust iniches. ideally in a recursive manner, without loosing spots due to parameter settings.

Subsetting shows wrong Cell Number

Subsetting shows an inaccurate cell number as output. The subset is fine, just the printed number is wrong!

Add Spot Clustering

Add clustering for spots (and potentially for genes) and add this as an annotation to the spatial object. Related to #41

All Zero spot removal

Since deconvolution tools typically crash when spots contain all zero values we remove those before we start the deconvolution. However, it might make sense to parameterize this with true as default, this way the users can still decide...

Benefits of decoupling signature building and deconvolution

Hello,

I was reasoning on the fact that only a few omnideconv-supported methods use somehow the input bulk RNA-seq data in the process of signature building (@LorenzoMerotto do you remember which ones?). All the others only use single-cell data.

In SpaceDeconv, wherever possible, it would be make sure we decouple the steps of signature building (run only once using the single-cell data) from actual deconvolution (run for all spots) to speed up the analysis.

This would be also reasonable for omnideconv, although the samples to be deconvoluted are << the spots in spatial transcritomics.
Are we already analyzing the data in this way with all methods, or do we build N times the signature matrix?

Curious to know your thoughts @mlist @LorenzoMerotto @grst @alex-d13 @constantin-zackl @federicomarini

Ciao,
Francesca

Plot UMI count - density

The density distribution of the plot_umi_count function results in just a red line without the density distribution graph in the case of very unequal distributions.

Vignette: Add manual annotation

In the vignette show how to add manual annotation/ground truth to a spatial object.

Potentially add a nice utility function for this

DWLS installation

When installing with pak::pkg_install("omnideconv/spacedeconv", dependencies = T) the wrong DWLS version is installed

Create RMD with example plots for the paper

For reproducibility

Number of cells per spot

After the deconvolution, the cell types are set to present or absent based on a threshold value. Density plots for the number of present cells per spot based on a specific threshold would be nice for each cell type.
Furthermore, the representation of the score distributions for all cell types together using violine plots could be implemented as well.