CELLxGENE Annotate
Necessary Disclaimers and Legal
The user is responsible for reviewing and complying with the license requirements of the software, and data referenced in this documentation.
Users are responsible for the costs associated with analyzing data, software and its storage in their project spaces.
Instance type availability and pricing are subject to the contract between the user or the user’s organization and DNAnexus.
Citations for CELLxGENE Annotate
CELLxGENE Annotate is a cell annotation tool developed by the Chan Zuckerberg Initiative (CZI) in collaboration with the open-source community. Detailed documentation of the CELLxGENE Annotate application can be found here.
Overview of the CELLxGENE Annotate
The CELLxGENE Annotate interface is divided into 3 sections
The left-hand sidebar contains categorical metadata and fields curated for each dataset.
The Center panel contains an embedding plot where each dot represents a cell.
The right-hand sidebar contains information about genes and gene sets.
Data Requirements: H5AD File Format
The input data must be provided as an H5AD file (.h5ad). Please refer to this document for input requirements.
CELLxGENE Annotation Applet can be the final step in a three-stage single-cell RNA-seq analysis pipeline.
Raw sequencing data is first processed through nf-core/scrnaseq for quality control and alignment, then passed to nf-core/scdownstream for integration, clustering, and automated cell type annotation.
The resulting .h5ad file is then loaded into the CELLxGENE Annotation Applet for interactive exploration and manual refinement of cell metadata.
Using CELLxGENE Annotate Applet on DNAnexus
Copying the applet and example dataset into a project
To explore the demo analyses, copy the applet and example dataset from the public project into your own project space:
Create a project for your cellxgene annotation analyses, billed to your own organization. Tutorials on project setup can be found here.
Navigate to the Resources tab, locate the project titled "Public Datasets AWS US (East)," and select the "cellxgene-annotation" folder.
Select the applet: cellxgene_v1.0.3 and example datasets (.h5ad).
Click "Copy" in the top-right menu and select the project created in Step 1.
Return to your project space to begin exploring the applet.
Example dataset for testing
We provided three examples for testing this applet (examples folder) and one gene set example (GENE_SET_FATTY_ACID_OXIDATION.tsv)
pbmc3k.h5ad: a small PBMC dataset from CELLxGENE Github: https://github.com/chanzuckerberg/cellxgene/blob/main/example-dataset/pbmc3k.h5ad
A-multi-tissue-single-cell-tumor-microenvironment-atlas.h5ad
391,963 cells across multiple tissue types
GSE174609_scdownstream_output.h5ad
an .h5ad file generated from the nf-core/scdownstream pipeline
Recommended Instance Types for Testing
Dataset
Instance
pbmc3k.h5ad (suggested test dataset)
mem1_ssd1_v2_x8 (default)
A-multi-tissue-single-cell-tumor-microenvironment-atlas.h5ad
mem2_ssd1_v2_x16
GSE174609_scdownstream_output.h5ad
mem2_ssd1_v2_x16
Quick start
Click the applet to run the analysis.
In the input box, choose the .h5ad file. For the demo, we used the pbmc3k.h5ad (2638 cells).
Choose an instance type. The default instance is mem1_ssd1_v2_x8.
Click Start to launch the analysis, then Open URL to access the interface.
Name your user-generated data directory.
Note: This name will be used to save your outputs (gene sets and annotations) to the destination selected when launching the job. Only alphanumeric characters and underscores are accepted
Figure 2: CELLxGENE Annotate interface of example data.
Example use cases
For additional analyses, refer to the: CELLxGENE Annotate Document
There are seven examples for testing applets.
Explore cell type composition of a dataset
In the left panel, locate the louvain metadata field
Click the droplet icon next to louvain to color the embedding by cell type
Click the > arrow to expand louvain and view the cell count for each population
Click the Toggle color legend on the top to show name of cell type
Click on individual cell type values (e.g. CD4 T cells) to highlight that population on the embedding
6. Color by numerical metadata fields (n_genes, n_counts, percent_mito) to explore data quality
Finding Cells Where a Gene Is Expressed
The right panel provides gene search functionality to visualize expression levels across the embedding. The applet supports gene search by Ensembl ID or gene symbol depending on .h5ad input file
In the Quick Gene Search box, type CD19 and press Enter to add the gene.
Click the droplet icon next to CD19 to color the embedding by its expression.
Identifying marker genes between two cell populations
In the left panel, expand louvain and select CD4 T cells
Click the "1" button in the toolbar to assign this population as group 1. Then, the toolbar shows "1: 1144 cells"
In the left panel, deselect CD4 T cells and select CD8 T cells
Click the "2" button in the toolbar to assign this population as group 2. Then, the toolbar shows "2: 316 cells"
Click the venn diagram icon in the toolbar to run Find Marker Genes
In the right panel, expand the results for group 1 and group 2
Then, you can rename the Pop1 and Pop2
Expand the CD4 T high to view the ranked marker gene list for CD4 T cells
Import gene set
In the right panel, click "Create new" next to Gene Sets
Paste a comma-separated list of pathway genes
ACADM,ACADS,ACADVL,ADIPOR1,ADIPOR2,ALOX12,BDH2,CPT1A,CPT1B,ECH1,ECHS1,HACL1,HADHB,HAO1,HAO2,PPARA,PPARD,PPARGC1A
Name the gene set (e.g. fatty_acid_oxidation)
Click Create a gene set
The dataset will show only genes available in the data
Click the droplet icon next to the gene set name to color the UMAP
Selecting and Subsetting Cells
Cells can be selected using the lasso tool, categorical filters, or gene expression thresholds. Selections can be combined for more precise subsetting.
Example using categorical filters and lasso selection:
In the left panel, expand louvain and select CD8 T cells
In the right panel, search and add gene NKG7
Click the droplet icon next to NKG7 to color the embedding by expression
For lasso selection:
Click the lasso tool icon in the toolbar to activate it
Click and drag to draw a freehand region around the target cluster on the UMAP
Click to subset icon to subset your selected cells
Click deselect to undo
Manually annotate a cell cluster using lasso
In the left panel, click the droplet icon next to louvain to color the embedding by existing cell type labels
Click "Create new category" at the top of the left panel
Enter the category name
In the dropdown, select louvain to duplicate existing labels as a starting point
Click "Create new category"
Activate the lasso tool in the toolbar
Draw a lasso region around a cluster of interest on the UMAP
Click the + button next to the test category in the left panel
Enter add labels to the selected cell. For example, name lasso
Technical Consideration
Each Job Runs One Dataset
Each job on DNAnexus launches a single instance associated with one dataset. Users provide a single .h5ad file as input, and only that dataset is available throughout the session.
To analyze or explore a different dataset, a new job must be created with a different input file.
A running job can be accessed simultaneously by multiple users via a shared URL. However, all users connected to the same job will interact with the same fixed dataset for the duration of that session.
Terminate instance
After finishing your session, close the browser tab and terminate the run in the Monitor panel to avoid unnecessary compute costs
Feature Name Column (feature_name_col)
By default, CELLxGENE Annotate uses the existing index of the var table for gene searches in the right panel. If the dataset is indexed by Ensembl IDs (e.g. ENSG00000141510) (for example: A-multi-tissue-single-cell-tumor-microenvironment-atlas.h5ad) but you prefer to search by gene symbols (e.g. TP53), use the optional feature_name_col input to specify the column containing gene symbols. The script will reindex the dataset accordingly before launching CELLxGENE Annotate.
Note: Check the AnnData object to confirm which column contains gene symbols before specifying this parameter.
Output File Management on DNAnexus
Generated File Types
Each working session produces two output files:
{name}-cell-labels-{########}.csv — cell annotation labels
{name}-gene-sets-{########}.csv — gene sets and DEG results
Why Multiple Files Appear: CELLxGENE Annotate checks for file changes every minute using MD5 hash comparison. If the content has changed, it uploads a new copy to DNAnexus. Since DNAnexus allows multiple files with the same name, each upload is saved as a separate version — resulting in multiple files per session.
File content grows incrementally:
cell-labels gains a new column each time a new annotation category is added
gene-sets gains a new row each time a gene set is added or DEG is run
Session ID
Each session is assigned a unique 8-character suffix (########). Restarting CELLxGENE Annotate starts a new session with a new suffix and a fresh set of files.
Which File to Use: use the file with the latest timestamp within a session. It is the most complete and should be treated as the final output.
Limitations
Large File Handling
Large .h5ad files require an appropriate instance type to avoid out-of-memory errors. This is especially relevant when subsetting large cell populations or running DEG analysis. Finding a suitable configuration may require multiple attempts.
Output Synchronization
The applet uploads output to the project every 60 seconds. This may result in duplicate file names in the output folder. Therefore, always use the file with the most recent timestamp as the final output. Please see “Output File Management on DNAnexus” for explanation.
Last updated