Need help with SingleR?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

150 Stars 65 Forks GNU General Public License v3.0 132 Commits 96 Opened issues


SingleR: Single-cell RNA-seq cell types Recognition (legacy version)

Services available


Need anything else?

Contributors list

SingleR is now on Bioconductor

Update: September 2019

A new and improved version of SingleR is on Bioconductor - The version of SingleR in this repository will not be maintained further.

Legacy version of SingleR

SingleR - Single-cell Recognition

Recent advances in single cell RNA-seq (scRNA-seq) have enabled an unprecedented level of granularity in characterizing gene expression changes in disease models. Multiple single cell analysis methodologies have been developed to detect gene expression changes and to cluster cells by similarity of gene expression. However, the classification of clusters by cell type relies heavily on known marker genes, and the annotation of clusters is performed manually. This strategy suffers from subjectivity and limits adequate differentiation of closely related cell subsets. Here, we present SingleR, a novel computational method for unbiased cell type recognition of scRNA-seq. SingleR leverages reference transcriptomic datasets of pure cell types to infer the cell of origin of each of the single cells independently. SingleR’s annotations combined with Seurat, a processing and analysis package designed for scRNA-seq, provide a powerful tool for the investigation of scRNA-seq data. We developed an R package to generate annotated scRNA-seq objects, that can then use the SingleR web tool for visualization and further analysis of the data –

For more informations please refer to the manuscript: Aran, Looney, Liu et al. Reference-based analysis of lung single-cell sequencing reveals a transitional profibrotic macrophage. Nature Immunology (2019)


# this might take long, though mostly because of the installation of Seurat.


12.18.2018: The SingleR browser has been upgraded allowing to use datasets with >100K single-cells. In addition, to make it more user friendly, the object used for SingleR has been upgraded as well to an S4 object. The web browser only accepts the new S4 objects.

However, the functions in the package (outside of the browser) have not been yet been modified to work with new object. Thus, to use the browser, please convert the SingleR object (the object created by the CreateSingleR functions) to the S4 object using the following code: = convertSingleR2Browser(singler)
saveRDS(,file=paste0([email protected],'.rds')

The new SingleR S4 object simlifies the access SingleR annotations and allows multipe identity columns (orig.ident) and clustering columns. See ?'SingleR-class' for more details.

11.6.2018: The Seurat team has roled out Seurat version 3.0 with many changes to the function names and variables. It is important to note that SingleR is independent of Seurat, and only requires xy representation of the single-cells, which can be obtained by any function. However, SingleR provides wrapper functions to streamline the analysis with Seuart which are affected by these changes. SingleR is now updated to run with Seurat 3.0, but it is still in beta mode.

Best practice is to create the single-cell object first. Then, create the SingleR object with the same cells used in the single-cell object (after filtering low quality cells). Finally, copy to relevant fields to the SingleR object. The new t-SNE representations are in

[email protected][email protected]



Simplest use is running the wrapper function that creates both a SingleR and Seurat object:

counts.file maybe a tab delimited text file, 10X directory or a matrix. annot is a tab delimited

text file or a data.frame with the original identities. normalize.gene.length should be true if

the data comes from a full-length platform. min.genes, min.cells, npca and regress.out are passed

to Seurat to create a Seurat object object:

singler = CreateSinglerSeuratObject(counts.file, annot,, min.genes = 500, technology, species = "Human" (or "Mouse"), citation, normalize.gene.length = F, min.cells = 2, npca = 10 regress.out = "nUMI", reduce.seurat.object = T)

The object can then be saved and uploaded to the SingleR web-app for further analysis and visualization or using functions available in the SingleR package (see vignette).


For more details on creating a SingleR object see SingleR - create object.

For more details about the SingleR method see SingleR Supplementary Information 1.

For examples of SingleR usage see SingleR Supplementary Information 2.

The fine-tuning process of SingleR may take very long, and in the current setting is not feasible for large datasets. Thus, for datasets with tens of thousands of cells it is recommended to run SingleR on subsets of the full data and then combine them together. See an example of analyzing 242,533 from the Microwell-Seq Mouse Cell Atlas.


SingleR was developed by Dvir Aran. Please contact Dvir Aran: dvir.aran at ucsf edu for any questions or suggestions.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.