alterlab-cellxgene

CZ CELLxGENE Census

概述

CZ CELLxGENE Census 提供对 CZ CELLxGENE Discover 标准化单细胞基因组学数据的程序化、带版本访问。2025-11-08 LTS 版本包含 162,025,130 个人类细胞和 46,299,127 只小鼠细胞，以及标准化元数据（细胞类型、组织、疾病、供体）、原始基因表达矩阵、预先计算的嵌入，并集成了 PyTorch、scanpy 和其他分析工具。细胞数量会随着每次发布而增长——请从 census["census_info"]["summary"] 读取数量，不要在方法部分引用固定数字。

何时使用此技能

在以下情况下使用此技能：

• 按细胞类型、组织或疾病查询单细胞表达数据
• 探索可用的单细胞数据集和元数据
• 使用单细胞数据训练机器学习模型
• 执行大规模跨数据集分析
• 将 Census 数据与 scanpy 或其他分析框架集成
• 计算数百万个细胞的统计数据
• 访问预先计算的嵌入或模型预测结果

若要分析自己的数据集（而非参考图谱），请改用 scanpy 或 scvi-tools。

安装

uv pip install cellxgene-census
# For PyTorch ML workflows (loaders moved out of cellxgene-census):
uv pip install tiledbsoma-ml

核心工作流

1. 使用上下文管理器打开 Census；为保证可复现性，请固定 census_version。"stable" 是最新 LTS 版本的别名（截至 2026-09 为 2025-11-08），而 "latest" 跟踪每周构建版本；LTS 版本至少保留五年。
2. 先探索元数据（get_obs / 数据集摘要），了解有哪些可用内容——始终筛选 is_primary_data == True，以避免重复细胞。
3. 在加载表达数据前估算查询规模。少于 100k 个细胞 → 使用 get_anndata()（内存中）；更多 → 使用 axis_query() 进行外存迭代。
4. 使用 obs_value_filter（细胞）和 var_value_filter（基因）查询表达数据；仅选择所需的 obs_column_names。
5. 下游分析：将返回的 AnnData 交给 scanpy，或将批次数据流式传入 PyTorch 数据加载器进行机器学习。

最简框架：

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",
    )

不适用的情况

场景	改用
对已有的 AnnData 执行标准化/聚类/UMAP	alterlab-scanpy
拼接或整理本地 .h5ad/zarr 文件	alterlab-anndata
训练深度生成模型 / 对自己的数据进行批次整合	alterlab-scvi-tools
浏览或下载特定的 GEO/ArrayExpress 登录号	alterlab-geo
通过命令行一次性运行 gget cellxgene 查询	alterlab-gget

路由指南

• 小型/中型查询（可放入 RAM） → get_anndata()。参见 references/querying_expression.md。
• 查询超出 RAM 容量 → 使用 axis_query() 进行分块迭代和增量统计。参见 references/querying_expression.md。
• 训练机器学习模型 → 使用 tiledbsoma_ml PyTorch 数据加载器 / ExperimentDataset。参见 references/ml_and_scanpy.md。
• 标准 scanpy 分析 / 多组织整合 → 参见 references/ml_and_scanpy.md。
• 需要完整架构、所有元数据字段或筛选语法详情 → references/census_schema.md。

参考索引

• references/querying_expression.md — 打开 Census、探索元数据、小型/中型 get_anndata() 查询，以及使用增量统计进行大型核外 axis_query() 处理。
• references/ml_and_scanpy.md — tiledbsoma_ml PyTorch 数据加载器 / ExperimentDataset 训练-测试划分、scanpy 集成、多数据集/组织集成（anndata.concat），以及四个实际用例。
• references/best_practices_and_troubleshooting.md — 原始数据筛选、版本固定、查询大小估算、tissue_general 与 tissue 的区别、存在矩阵、完整的 obs/var 元数据字段列表，以及故障排查指南。
• references/census_schema.md — Census 数据结构、所有元数据字段、值筛选语法/运算符、SOMA 对象类型，以及数据纳入标准。
• references/common_patterns.md — 核心配方之外的内容：核外增量（Welford）方差、按本体术语筛选、批处理扫描，以及常见问题列表。

属于 AlterLab Academic Skills 套件。