cellxgene-census

用途

CZ CELLxGENE Census 技能用于以编程方式查询 CZ CELLxGENE Discover 提供的、经过标准化的单细胞与空间转录组学数据集合。它适合在需要群体规模细胞数据时使用，无需先下载完整数据集即可进行查询与分析。

主要能力

Census 提供带版本号的公开数据发布。根据资料，2025-11-08 稳定 LTS 版本包含 217+ 百万总细胞、125+ 百万唯一细胞，以及 1,845 个数据集。当前 schema 涵盖人类、小鼠、狨猴、恒河猴和黑猩猩数据。

数据内容包括：标准化元数据（细胞类型、组织、疾病、供体）、原始基因表达矩阵及源 H5AD 查找/下载辅助工具、预计算的汇总计数、嵌入与空间数据。可与 AnnData、Scanpy、TileDB-SOMA、TileDB-SOMA-ML 及其他分析工具集成。

使用方式

安装 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：打开 Census（始终固定 census_version 以保证分析可复现）、探索 Census 信息、查询表达数据（小到中等规模写入 AnnData）、大规模查询（切片无法放入内存时使用核外处理）、使用 PyTorch 进行机器学习、空间 Census 数据、与 Scanpy 集成、多数据集整合。

关键概念与最佳实践

始终过滤主要数据：除非分析重复项，查询中应包含 is_primary_data == True，避免重复计数细胞。
指定 Census 版本以保证可复现性：生产分析中始终指定版本，例如 census = cellxgene_census.open_soma(census_version="2025-11-08")。
加载前估算查询规模：大查询先检查细胞数量，避免内存问题；若过大（>100k）则使用核外处理。
使用 tissue_general 进行更宽泛的分组，tissue 用于更细粒度。
仅选择所需列，减少数据传输。
针对特定基因查询时，检查数据集存在性矩阵。
采用“先探索再查询”的两步工作流。

可用元数据字段

细胞元数据（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 表示唯一细胞）。当前 schema 包含人类和小鼠之外的生物体集合，可用 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 集成工作流、多数据集整合、最佳实践与常见陷阱。

常见用例

探索组织中的细胞类型：按 tissue_general 过滤并统计 cell_type。
查询标记基因表达：按 feature_name 和 cell_type 过滤获取 AnnData。
训练细胞类型分类器：使用 tiledbsoma_ml 的 ExperimentDataset 与 experiment_dataloader。
跨组织分析：按 cell_type 和多个 tissue_general 过滤后比较差异。

排错

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

智能体操作流程

检查环境（网络访问、API 密钥、当前 API 文档与速率限制）；确认输入（格式、标识符、参数，不确定时询问而非猜测）；先运行小版本（获取单条已知记录检查响应格式）；执行完整任务；验证结果（标识符可解析、记录计数已报告、记录数据库版本或访问日期）；报告（说明运行内容、检查内容与仍不确定之处）。

遇到 HTTP 429 或 5xx 错误时，遵守速率限制并退避、批量请求、如实报告部分结果。若指令中的函数、标志或端点与已安装版本不符，查阅已安装版本自身文档并告知用户，绝不虚构 API。若必需输入、标识符或参数不明确，询问用户或在运行前明确说明假设。

完整性规则

绝不捏造结果、参数、标识符、引用或统计。无法运行或验证时如实说明。绝不虚构登录号、ID 或记录，应报告“未找到”。版本相关细节可能过时，需对照已安装版本的官方文档确认。涉及花钱、占用共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前应先询问。

技能介绍

用途