Skip to content

Interpretation of T cell states using reference single-cell atlases

License

Notifications You must be signed in to change notification settings

jmodlis/ProjecTILs

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A framework for reference-based single-cell RNA-seq data analysis

ProjecTILs is a computational method to project scRNA-seq data into reference single-cell atlases, enabling their direct comparison in a stable, annotated system of coordinates.

In contrast to other methods, ProjecTILs allows not only accurately embedding new scRNA-seq data into a reference without altering its structure, but also characterizing previously unknown cell states that "deviate" from the reference. ProjecTILs accurately predicts the effects of cell perturbations and identifies gene programs that are altered in different conditions and tissues.

You can use ProjecTILs pre-defined cell type-specific reference maps or create your own (see Building a custom reference atlas for ProjecTILs) for any cell type[s] of interest.

For real-life applications, check out our list of ProjecTILs Case Studies

Find the installation instructions for the package below, and a vignette detailing its functions at Tutorial (html) and Tutorial (repository)

Package Installation

To install ProjecTILs directly from its Git repository, run the following code from within R or RStudio:

install.packages("remotes")
library(remotes)

remotes::install_github("carmonalab/STACAS")
remotes::install_github("carmonalab/ProjecTILs")

Test the package

Load sample data and test your installation:

library(ProjecTILs)
ref <- load.reference.map()
data(query_example_seurat)

query.projected <- Run.ProjecTILs(query_example_seurat, ref=ref)

By default, load.reference.map() downloads and loads a reference for mouse tumor-infiltrating T cells. Read below where to find other references or how to build your own reference map.

Data projection DEMO

Find a step-by-step tutorial for ProjecTILs at: ProjecTILs tutorial

Running ProjecTILs

You can use ProjecTILs in two modes:

Mode 1: just for label transfer, faster, doesn't alter your dimensionality reduction

ProjecTILs.classifier(query = query_object, ref = reference_map)

Mode 2: reference embedding, to explore your dataset in the context of a stable reference map

Run.ProjecTILs(query = query_object, ref = reference_map)

ProjecTILs CASE STUDIES

For real-life applications on public datasets, check out our list of ProjecTILs Case Studies

Documentation

See a description of the functions implemented in ProjecTILs at: ProjecTILs functions

Reference Maps

Reference atlases are generated by comprehensive scRNA-seq multi-study integration and curation, and describe reference cell subtypes in a specific biological context.

Currently available atlases:

Custom Reference Maps

If you wish to use your own custom reference atlas, we recommend to use STACAS for single-cell data integration. Here is an example: Building a custom reference atlas for ProjecTILs.

Updating of reference map to include new cell states

After projection, one may want to incorporate the projected data into an "updated" reference. To recalculate the embeddings of a reference to account for new, projected data, use:

new_reference <- recalculate.embeddings( ref = old_reference, projected = projected_object )

See an example in the following workflow section.

SPICA online portal

You can now explore our atlases interactively and project your data through the SPICA web portal. Find some tutorials for interacting with SPICA at https://spica.unil.ch/tutorials

Troubleshooting

  • If load.reference.map() fails with error "Reference object X is invalid" the first time you run it; it is likely that reference atlas download has failed due to Timeout. Try setting options(timeout = max(300, getOption("timeout"))) to increase download Timeout.

  • If a warning message prevented remotes from installing the package, try:

sys.setenv(r_remotes_no_errors_from_warnings="true")

  • For analyzing datasets composed of multiple batches (e.g. different subjects, technologies), we recommend projecting each batch separately, by providing ProjecTILs a list of Seurat objects as input, e.g.:
data.seurat.list <- SplitObject(data.seurat, split.by = "batch")
query.projected.list <- make.projection(data.seurat.list)

Citation

Interpretation of T cell states from single-cell transcriptomics data using reference atlases Massimo Andreatta, Jesus Corria-Osorio, Soren Muller, Rafael Cubas, George Coukos, Santiago J Carmona. Nature Communications 12 Article number: 2965 (2021) - https://www.nature.com/articles/s41467-021-23324-4

About

Interpretation of T cell states using reference single-cell atlases

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • R 100.0%