<!-- README.md is generated from README.Rmd. Please edit that file -->

spacexr (Spatial-eXpression-R): Robust Cell Type Decomposition (RCTD) and Cell type-Specific Inference of Differential Expression (C-SIDE)

<!-- badges: start --> <!-- badges: end -->

Note: The spacexr package is now available on Bioconductor. Instructions for using the Bioconductor package can be found here. At the time of writing, the Bioconductor version only implements RCTD, so CSIDE users should continue to use this GitHub repo and follow the installation instructions below.

Welcome to spacexr, an R package for learning cell types and cell type-specific differential expression in spatial transcriptomics data.

Robust Cell Type Decomposition (RCTD) inputs a spatial transcriptomics dataset, which consists of a set of pixels, which are spatial locations that measure RNA counts across many genes. RCTD additionally uses a single cell RNA-seq (scRNA-seq) dataset, which is labeled for cell types. RCTD learns cell type profiles from the scRNA-seq dataset, and uses these to label the spatial transcriptomics pixels as cell types. RCTD has been tested across a variety of spatial transcriptomics technologies including imaging-based (e.g. MERFISH) and sequencing-based (e.g. Slide-seq, Visium). Notably, RCTD allows for individual pixels to be cell type mixtures; that is, they can potentially source RNA from multiple cell types. That said, RCTD can still handle the case where there is only one cell per pixel. RCTD identifies the cell types on each pixel, and estimates the proportion of each of these cell types. Additionally, RCTD has a platform effect normalization step, which normalizes the scRNA-seq cell type profiles to match the platform effects of the spatial transcriptomics dataset. A platform effect is the tendency of a sequencing technology to capture individual genes at different rates than another sequencing technology.

Cell type-Specific Inference of Differential Expression (C-SIDE) learns cell type-specific differential expression on spatial transcriptomics dataset. C-SIDE inputs one or more user-defined covariates, which are biologically-relevant axes along which differential expression is hypothesized. These variables can be generally defined, but some choices for covariates include spatial position, cellular microenvironment, or cell-to-cell interactions. C-SIDE then identifies, for each cell type, genes that are significantly differentially expressed as a function of the covariates. Similar to RCTD, C-SIDE can operate on spatial data containing single cells or cell type mixtures. Differential expression can be learned at the population level across one or multiple biological replicates or samples.

Code for generating the figures of our RCTD paper, Robust decomposition of cell type mixtures in spatial transcriptomics, is located here. Our Nature Biotechnology paper can be found here.

Code for generating the figures of our C-SIDE paper, Cell type-specific differential expression inference in spatial transcriptomics, is located here. Our C-SIDE paper is available in Nature Methods here.

News and Updates

February 1st, 2023: Version 2.2.0 released. This is a significant expansion of the functionality of C-SIDE. For multi-sample analysis, using meta-regression, we have added the ability to add in covariates, such as time, age, case vs. control, etc, and to test along these covariates. An example can be found in Population-level RCTD and C-SIDE Vignette under the “Population inference: meta regression” subheader.

Additionally, linear interpolation for the log-likelihood has been replaced with cubic spline interpolation. The result is increased numerical stability, convergence, and speed, especially for C-SIDE.

December 13th, 2022: Version 2.1.0 released. This is a substantial update to the behind-the-scenes implementation. Linear interpolation for the log-likelihood has been replaced with cubic spline interpolation. The result is increased numerical stability, convergence, and speed, especially for C-SIDE.

September 1st, 2022: Our C-SIDE paper has been published in Nature Methods here. We have also written a research briefing about this article in Nature Methods here.

December 22nd, 2021: We are renaming this package (formerly RCTD) as spacexr (Spatial eXpression R package). We are also releasing spacexr 2.0, now featuring cell type-specific differential expression. The new algorithm, called C-SIDE, is introduced in our new paper which will be available soon. <!--[here](BIORXIV LINK). --> We are also introducing a feature where RCTD and C-SIDE can be run in batch across multiple experimental replicates.

March 18th, 2021: Our RCTD paper has been published in Nature Biotechnology here. Also, we have just released a new version of RCTD (version 1.2.0) with a different method to input data (please see SpatialRNA and Reference constructor functions). Please report any bugs associated with this new update.

Installation

You can install the current version of spacexr from GitHub with:

# install.packages("devtools")
options(timeout = 600000000) ### set this to avoid timeout error
devtools::install_github("dmcable/spacexr", build_vignettes = FALSE)

If you would like to build vignettes (it will take some time), modify the above by setting build_vignettes = TRUE.

Vignettes and Documentation

A complete guide to spacexr vignettes can be found here, which includes diverse applications of RCTD and C-SIDE on Slide-seq, MERFISH, and Visium datasets. These vignettes also include multiple applications of C-SIDE to differential expression problems including spatial position, cell-to-cell interactions, and joint analysis of multiple experimental samples/replicates.

The spacexr manual can be found here.

Additional detailed recommended reading (documentation, tutorials, and tips) can be found here.

Quick Guide to Getting Started with RCTD

In this section, we aim to explain how to use RCTD as quickly as possible on your data:

1. Open the ‘spatial-transcriptomics.Rmd’ vignette for a complete explanation of the RCTD workflow. Expected output of the vignette is provided here. If you have any questions about how to run RCTD, please first make sure you run this Vignette on your computer and make sure you understand how it works. For other modes of RCTD, be sure to check out the rest of our vignettes.

2. As described in the ‘Data Preprocessing’ step of the vignette, convert your spatial transcriptomics data to a SpatialRNA object (called puck here) and your scRNA-seq reference to a Reference object (called reference here). In order to create these objects, you need to load your coordinate matrices, counts matrices, etc into R. Type ?Reference or ?SpatialRNA into R to learn more about these constructor functions.

3. Run RCTD. You can optionally set test_mode to TRUE in create.RCTD to quickly test RCTD, but you should set it to FALSE for the official run.

myRCTD <- create.RCTD(puck, reference, max_cores = 8, test_mode = FALSE) # here puck is the SpatialRNA object, and reference is the Reference object.
myRCTD <- run.RCTD(myRCTD, doublet_mode = 'doublet')

4. Observe RCTD results. RCTD results are stored in the @results field. Of particular interest is @results$weights, a data frame of cell type weights for each pixel (for full mode [i.e. doublet_mode = ‘full’]). Alternatively This section will generate various plots which can be found in resultsdir. The results of ‘doublet_mode=“doublet”’ are stored in @results$results_df and @results$weights_doublet, the weights of each cell type. More specifically, the results_df object contains one column per pixel (barcodes as rownames). Important columns are:

• spot_class, a factor variable representing RCTD’s classification in doublet mode: “singlet” (1 cell type on pixel), “doublet_certain” (2 cell types on pixel), “doublet_uncertain” (2 cell types on pixel, but only confident of 1), “reject” (no prediction given for pixel).
• Next, the first_type column gives the first cell type predicted on the bead (for all spot_class conditions except “reject”).
• The second_type column gives the second cell type predicted on the bead for doublet spot_class conditions (not a confident prediction for “doublet_uncertain”).

For some example of summary plots, follow the ‘RCTD results’ section of the ‘spatial-transcriptomics’ vignette.

Quick Guide to Getting Started with C-SIDE

Here, we discuss how to run C-SIDE on your data and detect cell type-specific differential expression:

1. Open the ‘differential-expression.Rmd’ vignette for a complete explanation of the C-SIDE workflow. Expected output of the vignette is provided here. If you h