alterlab-cellxgene
Query the CZ CELLxGENE Census (200M+ cells) programmatically via cellxgene-census and TileDB-SOMA, slicing expression by tissue, disease, or cell type and returning AnnData. Use when pulling reference single-cell RNA-seq data from the largest curated public atlas, running populat
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-cellxgene
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
CZ CELLxGENE Census
Overview
The CZ CELLxGENE Census provides programmatic, versioned access to standardized single-cell genomics data from CZ CELLxGENE Discover. The 2025-11-08 LTS release holds 162,025,130 human and 46,299,127 mouse cells with standardized metadata (cell types, tissues, diseases, donors), raw gene expression matrices, pre-calculated embeddings, and integration with PyTorch, scanpy, and other analysis tools. Cell counts grow with each release — read them from census["census_info"]["summary"] rather than quoting a number in a methods section.
When to Use This Skill
Use this skill when:
- 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
For analyzing your own dataset (not the reference atlas), use scanpy or scvi-tools instead.
Installation
uv pip install cellxgene-census
# For PyTorch ML workflows (loaders moved out of cellxgene-census):
uv pip install tiledbsoma-ml
Core Workflow
- Open the Census with a context manager; pin
census_versionfor reproducibility."stable"is the alias for the most recent LTS release (2025-11-08 as of 2026-09) and"latest"tracks the weekly build; LTS releases are kept available for at least five years. - Explore metadata first (
get_obs/ datasets summary) to understand what's available — always filteris_primary_data == Trueto avoid duplicate cells. - Estimate query size before loading expression. < 100k cells →
get_anndata()(in-memory); larger →axis_query()out-of-core iteration. - Query expression with
obs_value_filter(cells) andvar_value_filter(genes); select only theobs_column_namesyou need. - Downstream: hand the returned AnnData to scanpy, or stream batches into a PyTorch dataloader for ML.
Minimal skeleton:
import cellxgene_census
with cellxgene_census.open_soma(census_version="2025-11-08") as census: # pinned LTS
adata = cellxgene_census.get_anndata(
census=census,
organism="Homo sapiens",
obs_value_filter="cell_type == 'B cell' and tissue_general == 'lung' and is_primary_data == True",
)
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Normalize/cluster/UMAP an AnnData you already have | alterlab-scanpy |
Concatenate or wrangle local .h5ad/zarr files |
alterlab-anndata |
| Train a deep generative model / batch-integrate your own data | alterlab-scvi-tools |
| Browse or download a specific GEO/ArrayExpress accession | alterlab-geo |
One-off gget cellxgene lookup from the CLI |
alterlab-gget |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-scanpy) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Routing Guidance
- Small/medium query (fits in RAM) →
get_anndata(). Seereferences/querying_expression.md. - Query exceeds RAM →
axis_query()with chunked iteration and incremental stats. Seereferences/querying_expression.md. - Training ML models →
tiledbsoma_mlPyTorch dataloader /ExperimentDataset. Seereferences/ml_and_scanpy.md. - Standard scanpy analysis / multi-tissue integration → see
references/ml_and_scanpy.md. - Need full schema, all metadata fields, or filter-syntax details →
references/census_schema.md.
Reference Index
references/querying_expression.md— Opening the Census, exploring metadata, small/mediumget_anndata()queries, and large out-of-coreaxis_query()processing with incremental statistics.references/ml_and_scanpy.md—tiledbsoma_mlPyTorch dataloader /ExperimentDatasettrain-test splits, scanpy integration, multi-dataset/tissue integration (anndata.concat), and four worked use cases.references/best_practices_and_troubleshooting.md— Primary-data filtering, version pinning, query-size estimation,tissue_generalvstissue, presence matrices, the full obs/var metadata field list, and a troubleshooting guide.references/census_schema.md— Census data structure, all metadata fields, value-filter syntax/operators, SOMA object types, and data inclusion criteria.references/common_patterns.md— Extras beyond the core recipes: incremental (Welford) variance out-of-core, ontology-term filtering, batch-processing sweeps, and a common-pitfalls list.
Part of the AlterLab Academic Skills suite.
Files (alterlab-academic-skills)
-
evals
-
evals.json 4.8 KB
Loading…
-
-
references
-
best_practices_and_troubleshooting.md 4.3 KB
Loading… -
census_schema.md 5.6 KB
Loading… -
common_patterns.md 3.3 KB
Loading… -
ml_and_scanpy.md 5.6 KB
Loading… -
querying_expression.md 4.6 KB
Loading…
-
-
SKILL.md 5.9 KB
--- name: alterlab-cellxgene description: Query the CZ CELLxGENE Census (200M+ cells) programmatically via cellxgene-census and TileDB-SOMA, slicing expression by tissue, disease, or cell type and returning AnnData. Use when pulling reference single-cell RNA-seq data from the largest curated public atlas, running population-scale queries, or benchmarking your data against a reference — for analyzing your own dataset use scanpy or scvi-tools. Part of the AlterLab Academic Skills suite. license: MIT allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*) compatibility: "Self-contained — runs under `uv run python` with `cellxgene-census` installed (1.18.0 as of 2026-09; it pulls in tiledbsoma). Reads are anonymous over the public S3 bucket, so no API key or account is required, but a network connection and several GB of scratch are." metadata: skill-author: AlterLab version: "1.1.0" last_updated: "2026-09-23" --- # CZ CELLxGENE Census ## Overview The CZ CELLxGENE Census provides programmatic, versioned access to standardized single-cell genomics data from CZ CELLxGENE Discover. The **2025-11-08 LTS release** holds **162,025,130 human and 46,299,127 mouse cells** with standardized metadata (cell types, tissues, diseases, donors), raw gene expression matrices, pre-calculated embeddings, and integration with PyTorch, scanpy, and other analysis tools. Cell counts grow with each release — read them from `census["census_info"]["summary"]` rather than quoting a number in a methods section. ## When to Use This Skill Use this skill when: - 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 For analyzing **your own** dataset (not the reference atlas), use scanpy or scvi-tools instead. ## Installation ```bash uv pip install cellxgene-census # For PyTorch ML workflows (loaders moved out of cellxgene-census): uv pip install tiledbsoma-ml ``` ## Core Workflow 1. **Open the Census** with a context manager; pin `census_version` for reproducibility. `"stable"` is the alias for the most recent LTS release (**2025-11-08** as of 2026-09) and `"latest"` tracks the weekly build; LTS releases are kept available for at least five years. 2. **Explore metadata first** (`get_obs` / datasets summary) to understand what's available — always filter `is_primary_data == True` to avoid duplicate cells. 3. **Estimate query size** before loading expression. < 100k cells → `get_anndata()` (in-memory); larger → `axis_query()` out-of-core iteration. 4. **Query expression** with `obs_value_filter` (cells) and `var_value_filter` (genes); select only the `obs_column_names` you need. 5. **Downstream**: hand the returned AnnData to scanpy, or stream batches into a PyTorch dataloader for ML. Minimal skeleton: ```python import cellxgene_census with cellxgene_census.open_soma(census_version="2025-11-08") as census: # pinned LTS adata = cellxgene_census.get_anndata( census=census, organism="Homo sapiens", obs_value_filter="cell_type == 'B cell' and tissue_general == 'lung' and is_primary_data == True", ) ``` ### Does NOT Trigger | Scenario | Use Instead | |----------|-------------| | Normalize/cluster/UMAP an AnnData you already have | `alterlab-scanpy` | | Concatenate or wrangle local `.h5ad`/zarr files | `alterlab-anndata` | | Train a deep generative model / batch-integrate your own data | `alterlab-scvi-tools` | | Browse or download a specific GEO/ArrayExpress accession | `alterlab-geo` | | One-off `gget cellxgene` lookup from the CLI | `alterlab-gget` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-scanpy`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Routing Guidance - **Small/medium query (fits in RAM)** → `get_anndata()`. See `references/querying_expression.md`. - **Query exceeds RAM** → `axis_query()` with chunked iteration and incremental stats. See `references/querying_expression.md`. - **Training ML models** → `tiledbsoma_ml` PyTorch dataloader / `ExperimentDataset`. See `references/ml_and_scanpy.md`. - **Standard scanpy analysis / multi-tissue integration** → see `references/ml_and_scanpy.md`. - **Need full schema, all metadata fields, or filter-syntax details** → `references/census_schema.md`. ## Reference Index - **`references/querying_expression.md`** — Opening the Census, exploring metadata, small/medium `get_anndata()` queries, and large out-of-core `axis_query()` processing with incremental statistics. - **`references/ml_and_scanpy.md`** — `tiledbsoma_ml` PyTorch dataloader / `ExperimentDataset` train-test splits, scanpy integration, multi-dataset/tissue integration (`anndata.concat`), and four worked use cases. - **`references/best_practices_and_troubleshooting.md`** — Primary-data filtering, version pinning, query-size estimation, `tissue_general` vs `tissue`, presence matrices, the full obs/var metadata field list, and a troubleshooting guide. - **`references/census_schema.md`** — Census data structure, all metadata fields, value-filter syntax/operators, SOMA object types, and data inclusion criteria. - **`references/common_patterns.md`** — Extras beyond the core recipes: incremental (Welford) variance out-of-core, ontology-term filtering, batch-processing sweeps, and a common-pitfalls list. Part of the AlterLab Academic Skills suite.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.