api_access.md
105 lines · skills/cellxgene-census/references/api_access.md at 5f2bc03
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.
Raw lines 1 to 8Public 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.
Raw lines 52 to 74Discover 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.