Cellxgene Census

What it does

When your agent uses it

• You need population-scale cell metadata
• Gene expression slices
• Census summary counts
• Source H5AD URIs/downloads

Example prompts

• “Use the cellxgene-census skill to query the CZ CELLxGENE Census programmatically for versioned public single-cell and spatial transcriptomics data”
• “/cellxgene-census”

Requirements

• Python 3
• Compatibility (from SKILL.md): Requires Linux or macOS, Python 3.10+ and network access to public HTTPS manifests and S3. Tested with Python 3.12, cellxgene-census 1.18.0 and TileDB-SOMA 2.3.0. Spatial export needs the spatial extra; ML needs tiledbsoma-ml and PyTorch. No Census credentials required.
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

1. 1Opening the Census — always pin census_version so an analysis stays reproducible.
2. 2Exploring Census information — available datasets, cell counts, and summary tables.
3. 3Querying expression data — small to medium scale into an AnnData.
4. 4Large-scale queries — out-of-core processing when the slice will not fit in memory.
5. 5Machine learning with PyTorch — TileDB-SOMA-ML data loaders.
6. 6Spatial Census data — accessing spatial assays.
7. 7Integration with Scanpy — handing a Census slice to a standard Scanpy workflow.
8. 8Multi-dataset integration — combining datasets and handling batch effects.

What it can do on your machine

Read from SKILL.md and the folder at commit 92ace75. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • uv

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • arxiv.org
  • doi.org
  • export.arxiv.org

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires Linux or macOS, Python 3.10+ and network access to public HTTPS manifests and S3. Tested with Python 3.12, cellxgene-census 1.18.0 and TileDB-SOMA 2.3.0. Spatial export needs the spatial extra; ML needs tiledbsoma-ml and PyTorch. No Census credentials required.

  From compatibility in the SKILL.md frontmatter.

Context cost

Cellxgene Census loads about 3.4k tokens when it runs, and up to ~14k if it reads all its reference files. Until then it costs about 116 tokens; SKILL.md has 1,087 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~116

When it runs · the whole SKILL.md, loaded when a task matches

~3.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~14k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Read, Write, Edit, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from K-Dense-AI/scientific-agent-skills at commit 92ace75, republished under its MIT licence (© K-Dense-AI). 1,087 words, ~3,408 tokens.

name

cellxgene-census

description

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.

allowed-tools

Read, Write, Edit, Bash

compatibility

Requires Linux or macOS, Python 3.10+ and network access to public HTTPS manifests and S3. Tested with Python 3.12, cellxgene-census 1.18.0 and TileDB-SOMA 2.3.0. Spatial export needs the spatial extra; ML needs tiledbsoma-ml and PyTorch. No Census credentials required.

license

MIT

metadata.version

1.5

metadata.last-reviewed

2026-09-30

metadata.skill-author

K-Dense Inc.

uv pip install "cellxgene-census==1.18.0"

uv pip install "cellxgene-census[spatial]==1.18.0"

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

obs_value_filter="cell_type == 'B cell' and is_primary_data == True"

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

import tiledbsoma as soma
with census["census_data"]["homo_sapiens"].axis_query(
    measurement_name="RNA",
    obs_query=soma.AxisQuery(
        value_filter="tissue_general == 'brain' and is_primary_data == True"
    ),
) as query:
    print(f"Selected {query.n_obs:,} cells and {query.n_vars:,} genes")

# Query axes consume memory too; stream expression if the matrix will not fit.

# Broader grouping
obs_value_filter="tissue_general == 'immune system'"

# Specific tissue
obs_value_filter="tissue == 'venous blood'"

obs_column_names=["cell_type", "tissue_general", "disease"]  # Not all columns

genes = cellxgene_census.get_var(
    census, "homo_sapiens",
    value_filter="feature_name in ['CD4', 'CD8A']",
    column_names=["soma_joinid", "feature_id", "feature_name"],
)
presence = cellxgene_census.get_presence_matrix(census, "homo_sapiens")
# Columns use Census join IDs, not positions in the filtered gene table.
gene_presence = presence[:, genes["soma_joinid"].to_numpy()]

# Step 1: Explore what's available
metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="disease == 'COVID-19' and is_primary_data == True",
    column_names=["cell_type", "tissue_general"]
)
print(metadata.value_counts())

# Step 2: Query based on findings
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="disease == 'COVID-19' and cell_type == 'T cell' and is_primary_data == True",
)

with cellxgene_census.open_soma(census_version="2025-11-08") as census:
    cells = cellxgene_census.get_obs(
        census, "homo_sapiens",
        value_filter="tissue_general == 'lung' and is_primary_data == True",
        column_names=["cell_type"]
    )
    print(cells["cell_type"].value_counts())

with cellxgene_census.open_soma(census_version="2025-11-08") as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19']",
        obs_value_filter="cell_type in ['T cell', 'B cell'] and is_primary_data == True",
    )

import tiledbsoma as soma
from tiledbsoma_ml import ExperimentDataset, experiment_dataloader

with cellxgene_census.open_soma(census_version="2025-11-08") as census:
    experiment = census["census_data"]["homo_sapiens"]
    with experiment.axis_query(
        measurement_name="RNA",
        obs_query=soma.AxisQuery(value_filter="is_primary_data == True"),
    ) as query:
        dataset = ExperimentDataset(
            query=query,
            layer_name="raw",
            obs_column_names=["cell_type"],
            batch_size=128,
            shuffle=True,
        )
        dataloader = experiment_dataloader(dataset)

        for X, obs in dataloader:
            labels = obs["cell_type"]
            # Training logic
            pass

with cellxgene_census.open_soma(census_version="2025-11-08") as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        obs_value_filter="cell_type == 'macrophage' and tissue_general in ['lung', 'liver', 'brain'] and is_primary_data == True",
    )

    # Exploratory cell-level marker ranking; Census X contains raw counts.
    import scanpy as sc
    adata.layers["counts"] = adata.X.copy()
    sc.pp.normalize_total(adata, target_sum=1e4)
    sc.pp.log1p(adata)
    sc.tl.rank_genes_groups(adata, groupby="tissue_general")

© K-Dense-AI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (references) in skills/cellxgene-census of K-Dense-AI/scientific-agent-skills.

• SKILL.md
• references/api_access.md
• references/census_schema.md
• references/common_patterns.md
• references/core_workflow_patterns.md

Open the folder on GitHubat commit 92ace75

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in K-Dense-AI/scientific-agent-skills, which our catalogue first saw on October 7, 2026.

• lingxling/awesome-skills-cnclaude-scientific-skills/skills/cellxgene-census