Interpretation of T cell states using reference single-cell atlases

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.

ProjecTILs_pipeline

ProjecTILs comes with ready-to-use reference T cell atlases for cancer and viral infection (see Reference Atlases), and can be also used with custom, user-generated references (see Building a custom reference atlas for ProjecTILs)

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)

If you prefer to avoid installing R packages, you can run ProjecTILs in Docker. A ready-to-use Docker image with usage instructions is available on DockerHub

Package Installation

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

if (!requireNamespace("remotes")) install.packages("remotes")
library(remotes)

if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

if (!requireNamespace("Seurat", quietly = TRUE)) {
   install.packages("Seurat")
}

if (!requireNamespace("TILPRED", quietly = TRUE)) {
  install.packages(c("doParallel","doRNG"))
  BiocManager::install(c("AUCell","SingleCellExperiment"))
  remotes::install_github("carmonalab/TILPRED")
}

remotes::install_github("carmonalab/ProjecTILs")

Test the package

Load sample data and test your installation:

library(ProjecTILs)
data(query_example_seurat)

make.projection(query_example_seurat)

On your first run, the make.projection call will download the reference TIL atlas used as default map. This may take some time depending on your connection, but it is only necessary on the first run.

Data projection TUTORIAL

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

To run the code of the tutorial on your machine, download the demo repository: ProjecTILs tutorial repo or obtain a Docker image with all dependencies pre-installed.

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

Documentation

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

Reference Atlases

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:

  • tumor-infiltrating T lymphocytes (TIL) atlas: consists of 16,803 high-quality single-cell transcriptomes from 25 samples (B16 melanoma and MC38 colon adenocarcinoma tumors) from six different studies. Available at: https://doi.org/10.6084/m9.figshare.12478571 and interactive iSEE web app http://TILatlas.unil.ch

  • acute and chronic viral infection CD8 T cell atlas: consists of 7,000 virus-specific CD8 T cells from 12 samples (spleen) from different timepoints (day 4.5, day 7/8 and day 30) from mice infected with lymphocytic choriomeningitis virus (LCMV) Arm (acute infection) or cl13 (chronic infection) strains. Available at: https://doi.org/10.6084/m9.figshare.12489518 and web app http://virustcellatlas.unil.ch/

If you wish to use your own custom reference atlas, follow this vignette to prepare it in a format that can be understood by ProjecTILs: Building a custom reference atlas for ProjecTILs

Troubleshooting

  • 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)
  • When using multi-core projection (ncores>1), you may have to increase the maximum allowed object size by setting the parameter future.maxSize, e.g. to allocate 5GB:
make.projection(query, ref, ncores=4, future.maxSize=5000)

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

GitHub

https://github.com/carmonalab/ProjecTILs