Query the CZ CELLxGENE Census programmatically for versioned public single-cell and spatial transcriptomics data. Use when you need population-scale cell metadata, gene expression slices, Census summary counts, source H5AD URIs/downloads, embeddings, spatial Census data, or reference atlas comparisons across organisms, tissues, diseases, assays, and cell types. For analyzing your own local single-cell data use scanpy, anndata, or scvi-tools.
SKILL.md
CZ CELLxGENE Census
Overview
The CZ CELLxGENE Census provides programmatic access to a comprehensive, versioned collection of standardized single-cell and spatial transcriptomics data from CZ CELLxGENE Discover. This skill enables efficient querying and analysis of public Census releases without downloading whole datasets first.
The Census includes:
217+ million total cells and 125+ million unique cells in the 2025-11-08 stable LTS release
1,845 datasets in the 2025-11-08 stable LTS release
Human, mouse, marmoset, rhesus macaque, and chimpanzee data in the current schema
Opening the Census — always pin census_version so an analysis stays reproducible.
Exploring Census information — available datasets, cell counts, and summary tables.
Querying expression data — small to medium scale into an AnnData.
Large-scale queries — out-of-core processing when the slice will not fit in memory.
Machine learning with PyTorch — the Census data loaders.
Spatial Census data — accessing spatial assays.
Integration with Scanpy — handing a Census slice to a standard Scanpy workflow.
Multi-dataset integration — combining datasets and handling batch effects.
Key Concepts and Best Practices
Always Filter for Primary Data
Unless analyzing duplicates, always include is_primary_data == True in queries to avoid counting cells multiple times:
obs_value_filter="cell_type == 'B cell' and is_primary_data == True"
Specify Census Version for Reproducibility
Always specify the Census version in production analyses:
census = cellxgene_census.open_soma(census_version="2025-11-08")
Estimate Query Size Before Loading
For large queries, first check the number of cells to avoid memory issues:
# Get cell count
metadata = cellxgene_census.get_obs(
census, "homo_sapiens",
value_filter="tissue_general == 'brain' and is_primary_data == True",
column_names=["soma_joinid"]
)
n_cells = len(metadata)
print(f"Query will return {n_cells:,} cells")
# If too large (>100k), use out-of-core processing
Use tissue_general for Broader Groupings
The tissue_general field provides coarser categories than tissue, useful for cross-tissue analyses:
The current schema includes organism collections beyond human and mouse. Confirm available organisms for the selected release with list(census["census_data"].keys()).
