To respect user privacy, we only collect basic usage statistics and do not store logs from user sessions of the app. We aim to clearly document the requirements for user-uploaded data, provide a detailed FAQ here, and display descriptive error messages in the app whenever possible.

If the app returns an error message, you can also perform the same identical analysis using Seurat v4 following mapping vignette and find support for any problems that arise during your use of the Seurat package here.

If you are receiving an error message or are unable generate output with the app, please read the FAQ below to ensure that your dataset meets our requirements. If this doesn’t resolve your issue, and you’d like to help us improve the app, please file a Github issue describing the issue here.

We accept the following file types as input:

• Seurat objects as RDS
• 10x Genomics H5
• H5AD
• H5Seurat
• Matrix/matrix/data.frame as RDS

If uploading a Seurat object, it must contain an assay named ‘RNA’ with raw data in the ‘counts’ slot. Note that Azimuth uses only the (unnormalized) counts matrix.

Uploads must be smaller than 1GB and contain less than 100,000 cells. If your dataset is larger than 100,000 cells, you can divide it into smaller chunks for mapping, or you can map your dataset locally using Seurat v4.

If you would like to upload an existing Seurat object, you can use DietSeurat to pare down the Seurat object before uploading it. This will preserve the RNA counts data and cell metadata, but discard everything else.

DefaultAssay(object) <- “RNA”
object <- DietSeurat(object = object, assays = “RNA”)

To optimize the web app time and resource consumption, we made several changes to the base Seurat mapping workflow.

• SCTransform
  • When fitting generalized linear models, we use a representative set of 2000 genes and 2000 cells
  • To further speed up GLM model fitting, we use the recently developed glmGamPoi package from Constantin Ahlmann-Eltze and Wolfgang Huber.
• Mapping
  • For many references, we leverage a downsampled reference. Downsampling is done to ensure good representation of all datasets and celltypes present in the full reference.
  • We leverage a previously computed and cached neighbor index and neighbor list for the reference. This speeds up the neighbor-finding steps in the mapping algorithm.
  • For the approximate nearest neighbor finding steps in the algorithm, we use n.trees = 20, which provides speedup compared to default n.trees = 50 with minimal impact on the quality of downstream results.
• Analysis
  • We leverage the presto package from Ilya Korsunsky and Soumya Rayachauduri, for differential expression

The top 10 biomarkers for predicted cell type clusters with at least 15 query cells are calculated using differential expression analysis, using the presto package. The columns of the table are:

• avgExpr: mean value of feature for cells in cluster
• auc: area under ROC
• padj: Benjamini-Hochberg adjusted p value
• pct_in: percent of cells in the cluster with nonzero feature value
• pct_out: percent of cells out of the cluster with nonzero feature value

Azimuth computes a series of metrics that relate to QC for the mapping procedure. We’ve found that a single metric is insufficient to describe the quality of mapping, and therefore compute each of the metrics below. We emphasize that users should not limit their evaluation of mapping to these QC metrics, and can should explore their results. In particular, we encourage users to explore whether the differentially expressed genes associated with each annotated biological population are consistent with their biological expectations. We intend to support these metrics and QC analyses with additional visualizations in future versions.

Dataset-level Metrics:

• % of query cells with anchors: The Azimuth reference-mapping procedure first identifies a set of ‘anchors’, or pairwise correspondences between cells predicted to be in a similar biological state, between query and reference datasets. Here we report the percentage of query cells participating in an anchor correspondence. Typically, we observe values >15% when mapping is successful. Processing mismatched biological datasets (i.e. mapping a query dataset of human brain cells onto a reference dataset of human blood cells) will return few anchors (<5%). However, in some cases, when there is a large batch effect between query and reference datasets from the same tissue, this metric can fall below 15% even when mapping is successful.
• Cluster preservation score: For each query dataset, we downsample to at most 5,000 cells, and perform an unsupervised clustering. This score reflects the preservation of the unsupervised cluster structure, and is based on the entropy of unsupervised cluster labels in each query cell’s local neighborhood after mapping. Scores are scaled from 0 (poor) to 5 (best). This metric relies on the unsupervised clustering representing corresponding to biologically distinct cell states. If the query dataset consists of a homogeneous group of cells, or if the query dataset contains cells from multiple batches (which would be corrected by Azimuth), this metric may return a low value even in cases where mapping is successful. The score is calculated using the ClusterPreservationScore function in Azimuth.
  
  

Cell-level Metrics:

• Prediction scores: Cell prediction scores range from 0 to 1 and reflect the confidence associated with each annotation. Cells with high-confidence annotations (for example, prediction scores > 0.75) reflect predictions that are supported by mulitple consistent anchors. Prediction scores can be visualized on the Feature Plots tab, or downloaded on the Download Results tab. The prediction depends on the specific annotation for each cell. Therefore, if you are mapping cells at multiple levels of resolution (for example level 1/2/3 annotations in the Human PBMC reference), each level will be associated with a different prediction score.
• Mapping scores: This value from 0 to 1 reflects confidence that this cell is well represented by the reference. The “mapping.score” column is available to plot in the Feature Plots tab, and is provided in the download TSV file. The mapping score is independent of a specific annotation, is calculated using the MappingScore function in Seurat, and reflects how well the unique structure of a cell’s local neighborhood is preserved during reference mapping.