When you enable cell type annotation, your data is securely transmitted to 10x Genomics Cloud Analysis. Since your data is leaving your local environment and entering the 10x Genomics domain, it becomes subject to the terms outlined in the 10x Genomics End User License Agreement (EULA). Please review the EULA carefully to understand how your data will be handled and the associated usage terms. Additionally, please only use this feature if there are no restrictions that preclude your data being sent outside your local environment.
The availability of automated cell annotation is subject to restrictions based on U.S. or local laws and regulations. See regional restrictions for the list of impacted regions.
Cell annotations refer to the process of categorizing and assigning cell types to individual cells based on their gene expression profiles. These annotations are needed for understanding the cellular composition and diversity within a sample.
Cell Ranger ARC v2.1 introduces support for automated cell type annotation as part of the cellranger-arc count command.
To generate automated cell type annotations, ensure the following requirements are met:
- Your analysis includes a Gene Expression library.
- The total number of cells in your analysis range from 100 to 800,000.
- You have a 10x Genomics Cloud Analysis account.
To run automated cell type annotations with the cellranger-arc count command, you will need to access the 10x Genomics Cloud CLI Access Token.
There are two ways of accessing the token:
- Run
cellranger-arc cloud auth setup(recommended):
Cell Ranger ARC v2.1 introduces a new command, cellranger-arc cloud auth setup, to simplify the process of authenticating with 10x Genomics Cloud Analysis. This command provides an interactive walkthrough that guides you step-by-step through the setup.
When you run the command:
- You will be prompted to visit the 10x Genomics Cloud Analysis site, where you can generate an access token.
- After copying the token, paste it back into the command prompt, allowing Cell Ranger ARC to save the token locally.
Once saved, the token is automatically reused for future requests, making it easier to access Cloud Analysis services without needing to repeatedly enter credentials.
- Manually create a token file
The token is located on the security page of your Cloud Analysis account: https://cloud.10xgenomics.com/account/security.
You have the option to either generate a new token or copy an existing one.
To create a new token, click "Generate New Access Token."
Once the token is generated, use the copy button to copy the entire token and save it as a plain text file in a secure location that others cannot access. This token controls access to data stored in your 10x Cloud Account.
This token file is required as an input with a local installation (i.e., not running in 10x Cloud) to run cellranger-arc count with cell annotation. You will provide a path to the token file via the --tenx-cloud-token-path argument.
Visit the command line arguments page for a full list of accepted arguments.
An example to run cellranger-arc count with cell annotation looks like this:
cellranger-arc count --id=sample123 \
--reference=/opt/refdata-cellranger-arc-GRCh38-2024-A \
--libraries=libraries=/home/jdoe/runs/libraries.csv \
--create-bam=true \
--matrix=filtered_feature_bc_matrix.h5 \
--cell-annotation-model=auto \
--tenx-cloud-token-path=/path/to/10xcloud_token.json \
In this example:
--cell-annotation-modeldetermines the model used for cell type annotation. When set toauto, the pipeline automatically selects the default model.--tenx-cloud-token-pathis the path to the 10x Genomics Cloud Access Token, which is necessary for communication with the cloud-based cell annotation model. If not supplied, will default to the location stored through cellranger-arc cloud auth setup. If the token file does not exist, there is an error.
Cell type annotation generates the same output files, whether run as a standalone command or integrated into the count pipeline. All outputs are saved in the outs/ directory.
outs/
├── cell_types
│ ├── cell_annotation_differential_expression.csv
│ ├── cell_annotation_results.json.gz
│ ├── cell_types.csv
│ └── web_summary_cell_types.html
├── web_summary_cell_types.html -> cell_types/web_summary_cell_types.html
| File Name | Description |
|---|---|
web_summary_cell_types.html | View high-level cell types, metrics, and distribution. |
cell_annotation_sample_cloupe.cloupe | The Loupe Browser file from the original analysis, annotated with high-level cell types. |
cell_annotation_results.json.gz | Detailed evidence of how each cell has been assigned a cell type by the algorithm, broken down by dataset IDs in the reference database and nearest-neighbors in each. |
cell_types.csv | A CSV file listing coarse and fine cell types for each cell. |
cell_annotation_differential_expression.csv | Table listing genes differentially expressed in each detected cell type, along with log2 fold-change and associated p-value. |
For more details about these output files, see the Cell Type Annotation Outputs page.