domains / science / cellxgene-census-query / cellxgene-census

cellxgene-census

Skill card

combined

The three copies overlap heavily on the core Census workflow (open_soma, get_obs/get_anndata, axis_query, is_primary_data filtering, and scanpy integration), but they disagree on versioning, scale, and ML installation. K-Dense-AI pins cellxgene-census 1.18.0, uses the 2025-11-08 LTS build, and installs tiledbsoma-ml for PyTorch; aipoch and FreedomIntelligence use older/unpinned versions, the 2023-07-25 example build, and the [experimental] extra. K-Dense also adds spatial support, presence-matrix checks, and a reference to eight workflow patterns, while aipoch provides a complete runnable script and FreedomIntelligence provides more detailed inline patterns. Crowning one copy would hide the alternative versioning and ML setup choices.

Repositories

Other copies

Combined skill

---
name: cellxgene-census
description: Query the CZ CELLxGENE Census for versioned single-cell and spatial transcriptomics data. Use for population-scale expression, metadata, embeddings, spatial data, and reference atlas comparisons.
license: MIT
---

# CZ CELLxGENE Census

## When to Use
- Cross-tissue, cross-disease, or cross-cell-type expression comparisons.
- Reference atlas lookups to contextualize your own single-cell data.
- Population-scale metadata exploration and cell counts.
- Large-scale expression statistics requiring out-of-core iteration.
- Model training on curated atlas data.

## Installation

Pin the SDK version for reproducibility. The K-Dense copy pins 1.18.0; other copies use latest. Choose the version that matches your environment.

```bash
uv pip install "cellxgene-census==1.18.0"
```

For spatial workflows:
```bash
uv pip install "cellxgene-census[spatial]==1.18.0"
```

For PyTorch model training, the K-Dense copy uses tiledbsoma-ml; the aipoch and FreedomIntelligence copies use the [experimental] extra. The experimental loaders are absent from 1.18.0, so use tiledbsoma-ml with that version.

```bash
uv pip install "cellxgene-census==1.18.0" tiledbsoma-ml
```

## Core Workflow

### 1. Open the Census
Always use a context manager and pin the census version.\n
```python
import cellxgene_census

# Resolve the stable build once and record it
version = cellxgene_census.get_census_version_description("stable")["release_build"]

with cellxgene_census.open_soma(census_version=version) as census:
    # Work with census data
```

### 2. Explore Census Information

```python
summary = census["census_info"]["summary"].read().concat().to_pandas()
print(f"Total cells: {summary['total_cell_count'].iloc[0]:,}")

datasets = census["census_info"]["datasets"].read().concat().to_pandas()
```

### 3. Query Cell and Gene Metadata
Always filter for primary data unless analyzing duplicates.

```python
obs = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="tissue_general == 'brain' and is_primary_data == True",
    column_names=["cell_type", "tissue_general", "disease", "donor_id"],
)

genes = cellxgene_census.get_var(
    census, "homo_sapiens",
    value_filter="feature_name in ['CD4', 'CD8A']",
    column_names=["soma_joinid", "feature_id", "feature_name"],
)
```

### 4. Small/Medium Expression Queries
Use get_anndata when the result fits in memory.

```python
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="cell_type == 'T cell' and disease == 'COVID-19' and is_primary_data == True",
    var_value_filter="feature_name in ['CD4', 'CD8A', 'FOXP3']",
    obs_column_names=["cell_type", "tissue_general", "disease", "donor_id", "sex"],
)
```

### 5. Large-Scale Out-of-Core Queries
Use axis_query and iterate over batches when the matrix will not fit in memory.

```python
import tiledbsoma as soma

query = census["census_data"]["homo_sapiens"].axis_query(
    measurement_name="RNA",
    obs_query=soma.AxisQuery(
        value_filter="tissue_general == 'brain' and is_primary_data == True"
    ),
    var_query=soma.AxisQuery(
        value_filter="feature_name in ['FOXP2', 'TBR1', 'SATB2']"
    ),
)

n = 0
s = 0.0
for batch in query.X("raw").tables():
    values = batch["soma_data"].to_numpy(zero_copy_only=False)
    n += values.size
    s += float(values.sum())

mean_expr = s / n if n else float("nan")
```

### 6. Gene Presence Checks
For gene-specific queries, verify which datasets measured the genes.

```python
presence = cellxgene_census.get_presence_matrix(census, "homo_sapiens")
gene_presence = presence[:, genes["soma_joinid"].to_numpy()]
```

### 7. Spatial Census Data
Install the spatial extra and use the spatial assay access patterns.

### 8. Integration with Scanpy
Hand a Census AnnData slice to a standard Scanpy workflow.

## Best Practices
- Always pin census_version for reproducibility.
- Always include is_primary_data == True unless analyzing duplicates.
- Use tissue_general for broader groupings and tissue for specific tissues.
- Select only needed metadata columns to minimize data transfer.
- Estimate query size before loading; cell count alone is not a memory estimate.
- Gene symbols are not necessarily unique; keep feature_id as the canonical identifier.

## Conflicts
- K-Dense-AI/scientific-agent-skills pins cellxgene-census==1.18.0 and the 2025-11-08 LTS build; aipoch/medical-research-skills and FreedomIntelligence/OpenClaw-Medical-Skills use unpinned/latest installs and the 2023-07-25 example build.
- K-Dense-AI/scientific-agent-skills installs tiledbsoma-ml for PyTorch ML workflows; aipoch/medical-research-skills and FreedomIntelligence/OpenClaw-Medical-Skills install cellxgene-census[experimental].
- K-Dense-AI/scientific-agent-skills reports 217+ million cells and 1,845 datasets; aipoch/medical-research-skills and FreedomIntelligence/OpenClaw-Medical-Skills report 61+ million cells.