cz-cellxgene

name

cz_cellxgene

description

Expert reference for pulling single-cell RNA data from CZ CELLxGENE — the cellxgene-census Python/R API (query, slice, and download cells across the whole harmonized corpus via TileDB-SOMA) and the CELLxGENE Discover Curation REST API (find and download published datasets/collections). Use whenever the user wants data from CELLxGENE / cziscience / cellxgene-census: opening the Census (open_soma), writing obs/var value_filters, building an AnnData with get_anndata, listing cell metadata, deduplicating with is_primary_data, loading hosted embeddings (scVI, Geneformer, UCE), downloading a source H5AD by dataset_id, or querying collections/datasets over REST. Also triggers on "cellxgene census", "cziscience", "get_anndata", "census_data", "下载 cellxgene 数据", "查询单细胞图谱". Gives correct API signatures, the exact obs/var schema and filter syntax (which models routinely get wrong), memory-safe query patterns, and version pinning for reproducibility.

CZ CELLxGENE — Census API & Discover REST reference

Two distinct tools live under cellxgene.cziscience.com. Pick the right one:

Goal	Tool	Reference
Query/slice cells across the whole corpus by cell type / tissue / disease, get an AnnData, load hosted embeddings	cellxgene-census (Python/R, TileDB-SOMA)	references/census-python-api.md
Filter cells — which obs/var columns exist, valid values, value_filter syntax, raw vs normalized	schema	references/schema-and-filters.md
Find / download a published dataset or collection (one H5AD or RDS file), list collections programmatically	Discover Curation REST API	references/discover-rest-api.md
Ready-to-adapt end-to-end tasks	recipes	references/recipes.md
Avoid the common mistakes (version pinning, dedup, memory, filter syntax)	read this before writing a query	references/gotchas.md

Notable atlas: Tabula Sapiens (human multi-organ reference, ~500K cells, DOI 10.1126/science.abl4896) is already in the corpus as the Tabula Sapiens collection — get it via Census filter or Discover download; see the Tabula Sapiens block in references/discover-rest-api.md.

Runnable helpers in scripts/:

• census_query.py — open the Census, apply obs/var filters, write an .h5ad slice.
• discover_download.py — stdlib-only; search collections/datasets over REST and download a dataset's H5AD by id.

When you're on a CELLxGENE task, do this

1. Discover vs Census. "Download this specific published dataset/paper" → Discover REST (discover-rest-api.md). "Get all cells matching a biological filter across datasets" → Census (census-python-api.md).
2. Before writing any value_filter, confirm the column name and its categorical values against references/schema-and-filters.md. Guessing a column like tissue vs tissue_general, or a value like 'lung' vs 'lung parenchyma', silently returns 0 cells.
3. Always pin a Census version for reproducible results (open_soma(census_version="2025-..."), not the moving "stable"), and add is_primary_data == True to avoid counting the same cell twice. See gotchas.md.
4. Choose the X layer deliberately: X_name="raw" for counts, X_name="normalized" for library-size-normalized values. There is no log layer — you log-transform yourself.
5. Copy the closest recipe from references/recipes.md and adapt it rather than writing from scratch.

Install

pip install -U cellxgene-census          # pulls tiledbsoma, anndata
# R: install.packages("cellxgene.census", repos=c("https://chanzuckerberg.r-universe.dev","https://cloud.r-project.org"))

Access to the corpus is anonymous over public S3 — no account or key. Data is large and remote; queries stream from the cloud, so filter narrowly (see gotchas.md).

Authoritative docs (fetch when a signature is uncertain)

• Census docs home: https://chanzuckerberg.github.io/cellxgene-census/
• Python API reference: https://chanzuckerberg.github.io/cellxgene-census/python-api.html
• Discover docs: https://cellxgene.cziscience.com/docs
• Curation REST (OpenAPI/Swagger): https://api.cellxgene.cziscience.com/curation/ui/