cellxgene-census-query

CZ CELLxGENE Census

The CZ CELLxGENE Census provides programmatic access to a comprehensive, versioned collection of standardized single-cell genomics data from CZ CELLxGENE Discover. This skill enables efficient querying and analysis of millions of cells across thousands of datasets.

The Census includes:

• 61+ million cells from human and mouse
• Standardized metadata (cell types, tissues, diseases, donors)
• Raw gene expression matrices
• Pre-calculated embeddings and statistics
• Integration with PyTorch, scanpy, and other analysis tools

What it does

• Querying single-cell expression data by cell type, tissue, or disease
• Exploring available single-cell datasets and metadata
• Training machine learning models on single-cell data
• Performing large-scale cross-dataset analyses
• Integrating Census data with scanpy or other analysis frameworks
• Computing statistics across millions of cells
• Accessing pre-calculated embeddings or model predictions

Why this exists

This skill encodes the correct, scalable methodological decisions for population-level single-cell data:

• Uses the official tiledbsoma backend to query data remotely without downloading massive files.
• Automatically handles out-of-core processing (axis_query) for datasets larger than your available RAM.
• Always enforces is_primary_data == True to prevent statistical inflation from duplicate cells.
• Native, memory-efficient integration directly into PyTorch DataLoaders and Scanpy objects.

Usage

1. Opening the Census

Always use the context manager to ensure proper resource cleanup:

import cellxgene_census

# Open latest stable version
with cellxgene_census.open_soma() as census:
    # Work with census data

# Open specific version for reproducibility
with cellxgene_census.open_soma(census_version="2023-07-25") as census:
    # Work with census data

Key points:

• Use context manager (with statement) for automatic cleanup
• Specify census_version for reproducible analyses
• Default opens latest "stable" release