AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cellxgene-census

Queries 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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--cellxgene-census at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

references/census_schema.md

CZ CELLxGENE Census Data Schema Reference

Overview

The CZ CELLxGENE Census is a versioned collection of single-cell and spatial transcriptomics data built on the TileDB-SOMA framework. This reference documents the data structure, available metadata fields, and query syntax.

Current reference point:

  • Package examples target cellxgene-census==1.18.0
  • Current stable LTS Census: 2025-11-08
  • Census schema version: 2.4.0
  • CELLxGENE dataset schema version: 7.0.0
  • SDK tested against this LTS: cellxgene-census 1.18.0 / TileDB-SOMA 2.3.0
  • Sources: official schema and release notes, reviewed 2026-09-30.

High-Level Structure

The Census is organized as a SOMACollection with these main components:

1. census_info

Summary information including:

  • summary: Build date, cell counts, dataset statistics
  • datasets: Source datasets included in this release (not all of Discover); fields include dataset_id, dataset_version_id, dataset_title, collection_id, collection_name, collection_doi, citation, dataset_h5ad_path, and dataset_total_cell_count. Disease and tissue live on obs, not this table.
  • organisms: organism, organism_label, and organism_ontology_term_id mappings
  • summary_cell_counts: Cell counts stratified by metadata categories

2. census_data

Organism-specific SOMAExperiment objects:

  • "homo_sapiens": Human single-cell data
  • "mus_musculus": Mouse single-cell data
  • "callithrix_jacchus": Common marmoset single-cell data
  • "macaca_mulatta": Rhesus macaque single-cell data
  • "pan_troglodytes": Chimpanzee single-cell data

3. census_spatial_sequencing

Spatial organism-specific SOMAExperiment objects for supported releases. Spatial and non-spatial data share core metadata requirements, while spatial observations also include spatial columns such as array_col, array_row, and in_tissue.

Single-Cell Data Structure Per Organism

Each organism experiment contains:

obs (Cell Metadata)

Cell-level annotations stored as a SOMADataFrame. Access via:

census["census_data"]["homo_sapiens"].obs

ms["RNA"] (Measurement)

RNA measurement data including:

  • X: Data matrices with layers:
    • raw: Raw count data
    • normalized: Library-size-normalized values; full-gene assays also receive gene-length normalization. This is not log-transformed. Inspect list(experiment.ms["RNA"].X) for the selected release. Spatial data provides raw only.
  • var: Gene metadata
  • feature_dataset_presence_matrix: Sparse boolean array showing which genes were measured in each dataset

Spatial Data Structure Per Organism

Spatial data is stored separately from the single-cell Census data:

census["census_spatial_sequencing"]["homo_sapiens"]

Each spatial organism experiment contains:

  • obs: Spatial observation metadata, including core Census metadata and spatial fields such as array_col, array_row, and in_tissue
  • ms["RNA"]: RNA measurement matrices and feature metadata
  • spatial[scene_id].obsl["loc"]: point-cloud positions for each scene, with x, y, and soma_joinid

Use axis_query(...).to_spatialdata(X_name="raw") when exporting a spatial slice to spatialdata.

Cell Metadata Fields (obs)

Required/Core Fields

Identity & Dataset:

  • soma_joinid: Unique integer identifier for joins
  • dataset_id: Source dataset identifier
  • is_primary_data: Boolean flag (True = primary representation, False = duplicate across datasets)

Cell Type:

  • cell_type: Human-readable cell type name
  • cell_type_ontology_term_id: Standardized ontology term (e.g., "CL:0000236")

Tissue:

  • tissue: Specific tissue name
  • tissue_general: Broader tissue category (useful for grouping)
  • tissue_ontology_term_id: Standardized ontology term
  • tissue_general_ontology_term_id: Standardized ontology term for the broader tissue category

Assay:

  • assay: Sequencing technology used
  • assay_ontology_term_id: Standardized ontology term

Disease:

  • disease: Disease status or condition
  • disease_ontology_term_id: Standardized ontology term

Donor:

  • donor_id: Source-provided donor identifier; do not assume global uniqueness across studies
  • sex: Biological sex (male, female, unknown)
  • self_reported_ethnicity: Ethnicity information
  • development_stage: Life stage (adult, child, embryonic, etc.)
  • development_stage_ontology_term_id: Standardized ontology term

Organism: Select the experiment by its organism key. Organism labels/ontology IDs are in census_info["organisms"], not guaranteed obs columns.

Technical:

  • suspension_type: Sample preparation type (cell, nucleus, na)
  • tissue_type: tissue or organoid for included observations
  • observation_joinid: Source observation identity
  • nnz, n_measured_vars, raw_sum, raw_mean_nnz, raw_variance_nnz: Count summaries; the _nnz statistics exclude zeros

Gene Metadata Fields (var)

Access via:

census["census_data"]["homo_sapiens"].ms["RNA"].var

Available Fields:

  • soma_joinid: Unique integer identifier for joins
  • feature_id: Ensembl gene ID (e.g., "ENSG00000161798")
  • feature_name: Gene symbol (e.g., "FOXP2"); duplicates are allowed since schema 2.4.0, so use feature_id as the stable feature key
  • feature_type: Present in the verified 2025-11-08 build, although omitted from the upstream schema field list; inspect the live schema
  • feature_length: Gene length in base pairs
  • nnz: Non-zero count summary
  • n_measured_obs: Number of measured observations for the feature

Value Filter Syntax

Queries use Python-like expressions for filtering. The syntax is processed by TileDB-SOMA.

Comparison Operators

  • ==: Equal to
  • !=: Not equal to
  • <, >, <=, >=: Numeric comparisons
  • in: Membership test (e.g., feature_id in ['ENSG00000161798', 'ENSG00000188229'])

Logical Operators

  • and, &: Logical AND
  • or, |: Logical OR

Examples

Single condition:

value_filter="cell_type == 'B cell'"

Multiple conditions with AND:

value_filter="cell_type == 'B cell' and tissue_general == 'lung' and is_primary_data == True"

Using IN for multiple values:

value_filter="tissue in ['lung', 'liver', 'kidney']"

Complex condition:

value_filter="(cell_type == 'neuron' or cell_type == 'astrocyte') and disease != 'normal'"

Filtering genes:

var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19']"

Multi-Value Disease Fields

In current LTS releases, disease and disease_ontology_term_id may contain multiple values delimited by ||. Exact equality filters such as disease == 'COVID-19' can miss cells whose disease field contains multiple labels. For comprehensive disease queries, first inspect available values with get_obs() or summary_cell_counts, then choose filters that match the selected release's encoding.

Data Inclusion Criteria

The Census includes all data from CZ CELLxGENE Discover meeting:

  1. Species: Supported human, mouse, marmoset, rhesus macaque, and chimpanzee data; inspect the selected release's organism table and collections
  2. Technology: Approved sequencing technologies for RNA
  3. Count Type: Raw counts only (no processed/normalized-only data)
  4. Metadata: Standardized following CELLxGENE schema
  5. Sample type: Tissue and organoid observations; primary cell culture is excluded
  6. Both spatial and non-spatial data: Includes qualifying assays, with spatial data stored separately

Important Data Characteristics

Duplicate Cells

Cells may appear across multiple datasets. Use is_primary_data == True to filter for unique cells in most analyses.

Count Types

The Census includes:

  • Molecule counts: From UMI-based methods
  • Full-gene sequencing read counts: From non-UMI methods These may need different normalization approaches.

Versioning

Census releases are versioned (e.g., "2025-11-08", "stable", "latest"). Always specify an LTS build date for reproducible analysis:

census = cellxgene_census.open_soma(census_version="2025-11-08")

stable resolves to the current LTS release. latest resolves to the newest weekly release, which provides fast access to newly ingested datasets but is retained for a shorter period than LTS releases.

Feature Dataset Presence Matrix

Access which genes were measured in each dataset:

presence_matrix = census["census_data"]["homo_sapiens"].ms["RNA"]["feature_dataset_presence_matrix"]

This sparse boolean matrix helps understand:

  • Gene coverage across datasets
  • Which datasets to include for specific gene analyses
  • Technical batch effects related to gene coverage

SOMA Object Types

Core TileDB-SOMA objects used:

  • DataFrame: Tabular data (obs, var)
  • SparseNDArray: Sparse matrices (X layers, presence matrix)
  • DenseNDArray: Dense arrays (less common)
  • Collection: Container for related objects
  • Experiment: Top-level container for measurements
  • SOMAScene: Spatial transcriptomics scenes
  • obs_spatial_presence: A DataFrame mapping observations to scenes, not a separate SOMA object type