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/api_access.md

API access, provenance, and current contracts

Reviewed 2026-09-30 against the released Python SDK 1.18.0, its installed source, the official documentation, and public LTS reads. Use a separate environment; Linux/macOS are supported. PyPI now advertises Python 3.13 as well as 3.10–3.12, while the installation page still lists 3.10–3.12. This skill's runtime checks used Python 3.12, TileDB-SOMA 2.3.0, and TileDB-SOMA-ML 0.1.0.

Public service locations

Census is a TileDB-SOMA data service, not a general JSON /query REST endpoint. Let the SDK resolve these manifests and storage locations:

| Resource | Current location and contract | | --- | --- | | Build directory | https://census.cellxgene.cziscience.com/cellxgene-census/v1/release.json; JSON aliases and release descriptors, resolved by get_census_version_description / get_census_version_directory | | Mirrors | https://census.cellxgene.cziscience.com/cellxgene-census/v1/mirrors.json; JSON default mirror and base URI configuration | | Reviewed LTS SOMA | s3://cellxgene-census-public-us-west-2/cell-census/2025-11-08/soma/; public anonymous S3, region us-west-2 | | Source H5ADs | Release descriptor's h5ads locator plus dataset_h5ad_path; obtain through get_source_h5ad_uri, never construct a Discover API URL from a dataset UUID | | Embedding manifest | https://contrib.cellxgene.cziscience.com/contrib/cell-census/contributions.json; SDK filters contributions by exact build, organism, and embedding type |

All three HTTPS manifests returned valid JSON during review. A pinned SOMA read verified the collections, metadata schemas, a 10-cell × 3-gene count slice, feature presence, source locator, and spatial dataset selection. No credentials are needed. No bulk H5AD or full spatial image export was downloaded during review.

SDK reads use SOMA/Arrow iterators (read(), .tables()); there is no Census REST page number/cursor to invent. .concat() and get_obs() materialize the selection. AxisQuery(coords=(... ,)) takes global soma_joinid coordinates; slices are inclusive, and join IDs are release-specific. get_anndata() returns cells in rows and genes in columns. Reconcile outputs using returned join IDs, not an assumption that requested coordinate order was preserved.

Resolve then pin

import cellxgene_census

release = cellxgene_census.get_census_version_description("stable")
build = release["release_build"]
print(build, release["soma"])
with cellxgene_census.open_soma(census_version=build) as census:
    print(list(census["census_data"]))

stable resolved to 2025-11-08 during review. latest is a moving weekly build with short retention; pinning it alone does not guarantee long-term availability. Use an LTS build for a lasting analysis, save package versions and source dataset citations, and check the live directory rather than inferring a newer build from the calendar. Passing uri= to open_soma overrides version resolution.

Source H5AD lookup and optional download

from uuid import UUID

# Example UUID verified in the reviewed LTS; normally choose from datasets table.
dataset_id = str(UUID("d7476ae2-e320-4703-8304-da5c42627e71"))
locator = cellxgene_census.get_source_h5ad_uri(
    dataset_id, census_version="2025-11-08"
)
print(locator["uri"], locator.get("s3_region"))

# Illustrative bulk transfer: run only when the complete source file is needed.
# Destination must be a new file; the helper refuses to overwrite an existing one.
# cellxgene_census.download_source_h5ad(
#     dataset_id, to_path="source.h5ad", census_version="2025-11-08"
# )

The locator is a mapping, not a URL string. Lookup does not guarantee the remote H5AD is available. The source H5AD can include cells/features excluded by Census; record the dataset version and do not assume its row ordering matches Census.

Discover embeddings before requesting them

from cellxgene_census.experimental import get_all_available_embeddings

available = get_all_available_embeddings("2025-11-08")  # list of metadata dicts
human = [item for item in available if item["experiment_name"] == "homo_sapiens"]
print([(item["embedding_name"], item["data_type"]) for item in human])

For a small previously inspected cell/gene selection, pass a discovered name via get_anndata(..., obs_embeddings=[name]); the result is in adata.obsm[name]. Alternatively, get_embedding(census_version, embedding_uri, obs_soma_joinids) returns a NumPy array aligned to those requested join IDs. Require a matching build and organism, and inspect non-finite rows: missing embeddings are returned as NaN, not as zero vectors. Available models vary by build and organism; do not reuse a scVI/TranscriptFormer embedding from another build. A two-cell scVI read returned a finite 2 × 50 array during review; direct get_embedding was source/signature checked. No model training or benchmark was performed.

Official sources