cellxgene-census

用途

CZ CELLxGENE Census 提供了对 CZ CELLxGENE Discover 中标准化单细胞基因组学数据的编程访问能力。该技能用于高效查询和分析来自数千个数据集、数以百万计的细胞。

Census 包含：

• 来自人类和小鼠的 6100 万以上细胞
• 标准化元数据（细胞类型、组织、疾病、供体）
• 原始基因表达矩阵
• 预先计算的嵌入和统计信息
• 与 PyTorch、scanpy 及其他分析工具的集成

适用场景

该技能适用于以下情况：

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

安装与设置

安装 Census API：

pip install cellxgene-census

对于机器学习工作流，安装额外依赖：

pip install cellxgene-census[experimental]

使用方式

打开 Census

始终使用上下文管理器以确保资源正确清理：

import cellxgene_census

# 打开最新稳定版本
with cellxgene_census.open_soma() as census:
    # 处理 census 数据

# 打开特定版本以保证可复现性
with cellxgene_census.open_soma(census_version="2023-07-25") as census:
    # 处理 census 数据

要点：使用 with 语句实现自动清理；指定 census_version 以保证分析可复现；默认打开最新的 "stable" 版本。

探索 Census 信息

在查询表达数据之前，先探索可用的数据集和元数据。可访问摘要信息、获取所有数据集并按条件筛选。查询细胞元数据以了解可用数据时，注意始终过滤 is_primary_data == True，除非专门分析重复项。

查询表达数据（中小规模）

对于返回小于 10 万个细胞、可放入内存的查询，使用 get_anndata()。支持 obs_value_filter 进行细胞过滤，var_value_filter 进行基因过滤，条件可用 and、or 组合，in 用于多值匹配。可用 obs_column_names 只选择需要的列。也可单独使用 get_obs 查询细胞元数据、get_var 查询基因元数据。

大规模查询（核外处理）

对于超出可用内存的查询，使用 axis_query() 配合迭代处理（import tiledbsoma as soma），通过 query.X("raw").tables() 分块遍历表达矩阵，并可计算增量统计量。

机器学习与 PyTorch

训练模型时使用实验性 PyTorch 集成，通过 from cellxgene_census.experimental.ml import experiment_dataloader 创建数据加载器，支持批量、打乱及训练循环。可使用 ExperimentDataset 进行训练/测试集划分。

与 Scanpy 集成

可将 Census 数据无缝集成到 scanpy 工作流中，执行标准化、对数变换、高变基因选择、降维、聚类和可视化。

多数据集整合

可分别查询多个组织后拼接，或直接一次性查询多个数据集。

关键概念与最佳实践

• 始终过滤主要数据：除非分析重复项，始终在查询中包含 is_primary_data == True，避免重复计数。
• 指定 Census 版本：生产分析中始终指定 census_version。
• 加载前估算查询规模：大型查询先检查细胞数避免内存问题，超过 10 万细胞改用核外处理。
• 使用 tissue_general 进行更宽的归类：适合跨组织分析。
• 只选择需要的列：减少数据传输。
• 检查数据集存在性：分析特定基因时用 get_presence_matrix 确认哪些数据集测量了它们。
• 两步工作流：先探索再查询：先探索元数据，再查询表达数据。

可用元数据字段

细胞元数据（obs） 关键字段：cell_type、tissue、tissue_general、disease、assay、donor_id、sex、development_stage、dataset_id、is_primary_data 等。

基因元数据（var）：feature_id（Ensembl 基因 ID）、feature_name（基因符号）、feature_length（基因长度）。

参考文档

该技能包含详细参考文档：references/census_schema.md（数据结构、元数据字段、过滤语法、SOMA 对象类型、数据纳入标准）和 references/common_patterns.md（探索性查询、中小规模查询、大规模核外处理、PyTorch 集成、Scanpy 集成、常见陷阱）。

常见用例

包括：探索组织中的细胞类型、查询标记基因表达、训练细胞类型分类器、跨组织分析。

故障排查

• 查询返回过多细胞：增加更具体的过滤条件，使用 tissue 而非 tissue_general，按 dataset_id 过滤，改用核外处理。
• 内存错误：用更严格的过滤缩小范围，减少基因数，使用 axis_query() 核外处理并分批处理。
• 结果中细胞重复：始终包含 is_primary_data == True。
• 找不到基因：核对基因名拼写（区分大小写），尝试用 feature_id 的 Ensembl ID，检查数据集存在性矩阵。
• 版本不一致：始终显式指定 census_version，在所有分析中使用相同版本。