cellxgene-census

CZ CELLxGENE Census

概述

CZ CELLxGENE Census 提供对 CZ CELLxGENE Discover 中经过标准化、带版本管理的综合单细胞和空间转录组数据集的程序化访问。此技能可高效查询和分析公开的 Census 版本，无需先下载整个数据集。

Census 包含：

• 超过 2.17 亿个细胞和 超过 1.25 亿个独特细胞，来自 2025-11-08 稳定 LTS 版本
• 1,845 个数据集，来自 2025-11-08 稳定 LTS 版本
• 当前架构中的人类、小鼠、狨猴、恒河猴和黑猩猩数据
• 标准化元数据（细胞类型、组织、疾病、供体）
• 原始基因表达矩阵，以及用于查找／下载源 H5AD 文件的辅助工具
• 预计算的汇总计数、嵌入和空间数据
• 与 AnnData、Scanpy、TileDB-SOMA、TileDB-SOMA-ML 和其他分析工具集成

何时使用此技能

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

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

安装与设置

安装 Census API：

uv pip install "cellxgene-census==1.17.*"

对于空间工作流：

uv pip install "cellxgene-census[spatial]==1.17.*" "spatialdata[extra]>=0.2.5"

对于 PyTorch 模型训练，请使用 TileDB-SOMA-ML。旧版 cellxgene_census.experimental.ml 加载器已弃用：

uv pip install "cellxgene-census==1.17.*" tiledbsoma-ml

核心工作流模式

references/core_workflow_patterns.md 中列出了八种模式，每种都附有代码：

1. 打开 Census — 始终固定 census_version，确保分析可复现。
2. 探索 Census 信息 — 查看可用数据集、细胞计数和汇总表。
3. 查询表达数据 — 将小到中等规模的数据载入 AnnData。
4. 大规模查询 — 当数据切片无法装入内存时，进行内存外处理。
5. 使用 PyTorch 进行机器学习 — 使用 Census 数据加载器。
6. 空间 Census 数据 — 访问空间检测数据。
7. 与 Scanpy 集成 — 将 Census 数据切片交给标准 Scanpy 工作流处理。
8. 多数据集集成 — 合并数据集并处理批次效应。

核心概念与最佳实践

始终筛选主要数据

除非要分析重复数据，否则查询时始终包含 is_primary_data == True，以避免重复计数细胞：

obs_value_filter="cell_type == 'B cell' and is_primary_data == True"

指定 Census 版本以确保可复现性

在生产分析中始终指定 Census 版本：

census = cellxgene_census.open_soma(census_version="2025-11-08")

加载前估算查询规模

对于大型查询，先检查细胞数量，以避免内存问题：

# Get cell count
metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="tissue_general == 'brain' and is_primary_data == True",
    column_names=["soma_joinid"]
)
n_cells = len(metadata)
print(f"Query will return {n_cells:,} cells")

# If too large (>100k), use out-of-core processing

使用 tissue_general 进行更宽泛的分组

tissue_general 字段提供的类别比 tissue 更粗略，适用于跨组织分析：

# Broader grouping
obs_value_filter="tissue_general == 'immune system'"

# Specific tissue
obs_value_filter="tissue == 'peripheral blood mononuclear cell'"

仅选择所需列

仅指定必需的元数据列，以尽量减少数据传输：

obs_column_names=["cell_type", "tissue_general", "disease"]  # Not all columns

基因特定查询时检查数据集是否包含目标基因

分析特定基因时，请确认哪些数据集测量了这些基因：

presence = cellxgene_census.get_presence_matrix(
    census,
    "homo_sapiens",
    var_value_filter="feature_name in ['CD4', 'CD8A']"
)

两步工作流：先探索，再查询

先探索元数据以了解可用数据，再查询表达数据：

# Step 1: Explore what's available
metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="disease == 'COVID-19' and is_primary_data == True",
    column_names=["cell_type", "tissue_general"]
)
print(metadata.value_counts())

# Step 2: Query based on findings
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="disease == 'COVID-19' and cell_type == 'T cell' and is_primary_data == True",
)

可用元数据字段

细胞元数据（obs）

用于筛选的关键字段：

• cell_type、cell_type_ontology_term_id
• tissue、tissue_general、tissue_ontology_term_id
• disease、disease_ontology_term_id
• assay、assay_ontology_term_id
• donor_id、sex、self_reported_ethnicity
• development_stage、development_stage_ontology_term_id
• dataset_id
• is_primary_data（布尔值：True = 独特细胞）

当前架构包含人类和小鼠之外的生物集合。使用 list(census["census_data"].keys()) 确认所选版本中可用的生物。

基因元数据 (var)

• feature_id（Ensembl 基因 ID，例如 "ENSG00000161798"）
• feature_name（基因符号，例如 "FOXP2"）
• feature_type
• feature_length（基因长度，单位为碱基对）
• nnz、n_measured_obs（可用性汇总信息，可用于检查稀疏性和覆盖范围）

参考文档

此技能包含详细的参考文档：

references/census_schema.md

全面介绍：

• Census 数据结构和组织方式
• 所有可用的元数据字段
• 值筛选语法和运算符
• SOMA 对象类型
• 数据纳入标准

何时阅读： 需要详细的架构信息、完整的元数据字段列表或复杂的筛选语法时。

references/common_patterns.md

以下内容的示例和模式：

• 探索性查询（仅元数据）
• 小到中型查询（AnnData）
• 大型查询（外存处理）
• PyTorch 集成
• 空间 Census 访问模式
• Scanpy 集成工作流
• 多数据集集成
• 最佳实践和常见陷阱

何时阅读： 实现特定查询模式、查找代码示例或排查常见问题时。

常见用例

用例 1：探索组织中的细胞类型

with cellxgene_census.open_soma() as census:
    cells = cellxgene_census.get_obs(
        census, "homo_sapiens",
        value_filter="tissue_general == 'lung' and is_primary_data == True",
        column_names=["cell_type"]
    )
    print(cells["cell_type"].value_counts())

用例 2：查询标记基因表达

with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19']",
        obs_value_filter="cell_type in ['T cell', 'B cell'] and is_primary_data == True",
    )

用例 3：训练细胞类型分类器

import tiledbsoma as soma
from tiledbsoma_ml import ExperimentDataset, experiment_dataloader

with cellxgene_census.open_soma() as census:
    experiment = census["census_data"]["homo_sapiens"]
    with experiment.axis_query(
        measurement_name="RNA",
        obs_query=soma.AxisQuery(value_filter="is_primary_data == True"),
    ) as query:
        dataset = ExperimentDataset(
            query=query,
            layer_name="raw",
            obs_column_names=["cell_type"],
            batch_size=128,
            shuffle=True,
        )
        dataloader = experiment_dataloader(dataset)

        for X, obs in dataloader:
            labels = obs["cell_type"]
            # Training logic
            pass

用例 4：跨组织分析

with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        obs_value_filter="cell_type == 'macrophage' and tissue_general in ['lung', 'liver', 'brain'] and is_primary_data == True",
    )

    # Analyze macrophage differences across tissues
    sc.tl.rank_genes_groups(adata, groupby="tissue_general")

故障排查

查询返回的细胞过多

• 添加更具体的筛选条件以缩小范围
• 使用 tissue 而非 tissue_general，以获得更细的粒度
• 如果知道具体的 dataset_id，则按其筛选
• 对大型查询切换为外存处理

内存错误

• 使用限制性更强的筛选条件缩小查询范围
• 使用 var_value_filter 选择更少的基因
• 使用 axis_query() 进行外存处理
• 分批处理数据

结果中存在重复细胞

• 筛选时始终包含 is_primary_data == True
• 检查是否有意跨多个数据集进行查询

未找到基因

• 确认基因名称拼写正确（区分大小写）
• 尝试使用 feature_id 和 Ensembl ID，而非 feature_name
• 检查数据集存在矩阵，确认是否测量了该基因
• Census 构建过程中可能已过滤掉某些基因

版本不一致

• 始终明确指定 census_version
• 所有分析均使用相同版本
• 查看发行说明，了解特定版本的变更

Agent 操作流程

1. 检查环境。 确认网络访问权限、API 密钥（如需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于会改变结果的任何值，应先询问，而不是猜测。
3. 先运行小规模任务。 获取一条已知记录，并在批量查询前检查响应格式。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数，并记录数据库版本或访问日期。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	遵守速率限制，采用退避策略、分批请求，并如实报告部分结果。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

诚信准则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 切勿编造登录号、ID 或记录；如果未找到，请报告“未找到”。
• 请将此处与版本相关的细节视为可能已过时，并根据已安装版本的官方文档进行确认。
• 对于需要付费、消耗共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征求同意。

相关技能

• anndata：用于单细胞分析的注释矩阵数据结构。
• scanpy：标准的单细胞 RNA-seq 分析流程。
• scvi-tools：训练并应用 scvi-tools 概率深度生成模型（scVI、scANVI、totalVI、MultiVI、PeakVI、DestVI、Solo、CellAssign、MrVI…