cellxgene-census

cellxgene-census: A Cloud-Based Query Tool for Single-Cell Transcriptomic Data

Skill Overview

cellxgene-census is a skill for programmatically querying single-cell and spatial transcriptomic data from the CZ CELLxGENE Census. It provides access to more than 217 million cells across over 1,845 datasets, enabling efficient analysis without downloading complete datasets.

Use Cases

Large-Scale Single-Cell Data Exploration

When you need to query single-cell expression data from a specific tissue, cell type, or disease, this skill can retrieve data directly from the cloud. For example, you can query neuronal cells in brain tissue, T cells from patients with COVID-19, or the distribution of cell types in the immune system.

Machine Learning Model Training

When training classifiers or clustering models on single-cell data, this skill supports streaming data loading and PyTorch integration. With TileDB-SOMA-ML, you can efficiently train cell-type classifiers and process expression matrices containing millions of cells without loading the entire dataset into memory at once.

Cross-Dataset Integrative Analysis

When comparing single-cell data across different tissues, diseases, or experimental conditions, this skill can query multiple datasets simultaneously and return standardized AnnData objects. Combined with Scanpy workflows, it supports direct dimensionality reduction, clustering, and differential expression analysis.

Core Features

Flexible Single-Cell Data Queries

Supports filtering single-cell data across multiple dimensions, including cell type, tissue, disease, and species. You can query small datasets using get_anndata or process very large datasets in a streaming manner using axis_query. Results are returned in standardized AnnData format for seamless integration with Scanpy analysis workflows.

Spatial Transcriptomics Data Access

Provides query interfaces for spatial transcriptomics sequencing data, such as Visium and Slide-seq V2. You can retrieve spatial coordinates and expression matrices by dataset ID, with output in SpatialData format for spatial visualization and analysis.

Metadata Exploration and Statistics

Before querying expression data, you can explore dataset overviews, cell-type distributions, tissue statistics, and other metadata. This functionality helps users quickly understand the available data and design more precise query conditions.

Frequently Asked Questions

Does cellxgene Census require authentication?

No. Census public datasets are fully accessible without registration or an API key. Simply install the Python package (pip install cellxgene-census) to begin querying data. For scenarios requiring a higher access frequency or private data, you may need to contact CZI for special permissions.

How can I avoid querying duplicate cell data?

Always add the is_primary_data == True filter to your query conditions. Some cells in Census may be included in multiple datasets, and is_primary_data identifies unique, deduplicated cells. Without this filter, the same cell may be counted multiple times, resulting in inflated statistics.

How should I handle out-of-memory errors during single-cell queries?

When a query returns more than 100,000 cells, it is recommended to use axis_query() for batch processing rather than loading all cells at once. This skill supports streaming access to expression matrices, allowing you to compute statistics or train models chunk by chunk, significantly reducing memory usage. You can also narrow the query scope by using tissue instead of tissue_general, specifying a particular dataset_id, or applying other restrictive filters.