★ FEATURED ARTICLE CZ CELLxgene Census 核心工作流模式实战指南基于 scientific-agent-skills 技能库的人口级单细胞数据查询范式【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsCZ CELLxgene Census以下简称 Census是 CZ CELLxgene Discover 提供的一个版本化、标准化的公共单细胞与空间转录组数据仓库由 CELLxgene Census skill 封装在 scientific-agent-skills 技能库中。本指南以该技能的核心参考文档 core_workflow_patterns.md 为主体骨架系统讲解贯穿 Census 使用全过程的8 种核心工作流模式打开 Census、探索元数据、中小规模表达查询、大规模核外out-of-core处理、PyTorch 机器学习、空间转录组数据、Scanpy 集成与多数据集整合。读完本文你将掌握一套可复用、可落地、规模自适配的 Census 查询方法论能够在任意一次单细胞研究中快速完成元数据探查 → 表达量切片 → 下游分析/建模的完整闭环。CZ CELLxgene Census 查询数据工作流示意图环境与版本约定本文所有示例均以技能仓库中声明的环境为前提保持一致可获得可复现的结果项目约定值Python3.10,3.13来自 SKILL.md front mattercellxgene-census 包1.17.*稳定 LTS Census 版本2025-11-08schema 2.4.0CELLxGENE 数据集 schema 7.0.0空间数据需cellxgene-census[spatial]extra 与TileDB-SOMA 1.15.5机器学习需tiledbsoma-ml旧cellxgene_census.experimental.ml已弃用认证公共 Census 数据无需任何认证技能依赖包清单在 tests/skill-requirements.toml 中登记为cellxgene-census、tiledbsoma、tiledbsoma-ml、scanpy、spatialdata安装命令如下# 基础安装查询、AnnData 工作流 uv pip install cellxgene-census1.17.* # 空间转录组工作流 uv pip install cellxgene-census[spatial]1.17.* spatialdata[extra]0.2.5 # PyTorch 模型训练 uv pip install cellxgene-census1.17.* tiledbsoma-mlCensus 构建在 TileDB-SOMA 框架之上公开会话以SOMACollection组织顶层包含三个主要集合census_info汇总信息与数据集清单、census_data按物种组织的单细胞SOMAExperiment与census_spatial_sequencing空间转录组实验。在 2025-11-08 LTS 版本中census_data覆盖人、小鼠、绒猴、恒河猴与黑猩猩五个物种技能文档记录的规模为 2.17 亿总细胞、1.25 亿去重细胞与 1,845 个数据集。关于完整结构、元数据字段与 SOMA 对象类型的细节可查阅 census_schema.md。模式 1打开 Census任何工作流的起点都是打开 Census。文档明确要求始终使用上下文管理器with语句以保证底层 TileDB 资源得到正确清理避免连接泄漏。import cellxgene_census # 打开最新稳定版本解析到当前 LTS release with cellxgene_census.open_soma() as census: # 在此处处理 Census 数据退出 with 块自动完成资源清理 ... # 显式指定 LTS 版本以确保分析可复现 with cellxgene_census.open_soma(census_version2025-11-08) as census: # 使用固定版本的分析结果在未来可被复现 ...关键要点优先使用上下文管理器with块退出后自动清理资源比裸调用open_soma()更安全显式固定census_version在正式分析中固定日期版本如2025-11-08可复现性优先版本别名语义stable指向当前长期支持LTS版本latest指向最新周更版本能最快访问新收录的数据集但保留周期比 LTS 版本短得多仅适合探索性使用。模式 2探索 Census 信息在真正查询表达量之前先探索仓库里到底有什么。Census 提供两级探索入口一是census_info下的聚合摘要表二是基于get_obs()的按需元数据查询。访问聚合摘要信息# 读取摘要统计返回 label/value 行式结构 summary census[census_info][summary].read().concat().to_pandas() summary_values summary.set_index(label)[value] print(fTotal cells: {int(summary_values[total_cell_count]):,}) print(fUnique cells: {int(summary_values[unique_cell_count]):,}) # 获取全量数据集清单含出处、组织、疾病等元数据 datasets census[census_info][datasets].read().concat().to_pandas() # 获取按物种/细胞类型/组织/疾病/assay 预计算的细胞计数 summary_counts census[census_info][summary_cell_counts].read().concat().to_pandas() tissue_counts summary_counts[summary_counts[category].eq(tissue_general)]查询细胞元数据理解可用数据的组成# 获取某个组织中的去重细胞类型列表 cell_metadata cellxgene_census.get_obs( census, homo_sapiens, value_filtertissue_general brain and is_primary_data True, column_names[cell_type] # 只取需要的列减少传输 ) unique_cell_types cell_metadata[cell_type].unique() print(fFound {len(unique_cell_types)} cell types in brain) # 按组织统计去重细胞数 tissue_metadata cellxgene_census.get_obs( census, homo_sapiens, value_filteris_primary_data True, column_names[tissue_general], ) tissue_counts tissue_metadata[tissue_general].value_counts()重要原则除非是在专门分析重复细胞否则永远在过滤条件中加上is_primary_data True。同一生物学细胞可能被多个数据集收录该字段为True代表它是唯一的、非重复的观测不加以过滤会导致细胞被重复计数、统计失真。Census 官方把这一条列为第一最佳实践见 SKILL.md 与 common_patterns.md。常用的元数据字段obs细胞维度包括cell_type/cell_type_ontology_term_id、tissue/tissue_general后者是更粗粒度、适合跨组织归类的分组、disease、assay、donor_id、sex、self_reported_ethnicity、development_stage、dataset_id、is_primary_data。基因维度var字段则包括feature_idEnsembl 基因 ID如ENSG00000161798、feature_name基因符号如FOXP2、feature_length碱基长度以及nnz、n_measured_obs两个可用来评估稀疏度与覆盖度的统计字段。完整字段清单参见 census_schema.md。查询前的规模预估若担心查询过大可先用元数据查询估计将返回的细胞数再决定后续路线见模式 4。估数时只需把column_names收窄到[soma_joinid]然后读取 DataFrame 长度即可。模式 3查询表达数据中小规模 10 万细胞当查询结果可以整体载入内存一般 10 万细胞时使用高层 APIget_anndata()一步把筛选结果物化为AnnData对象# 基础查询按细胞类型 组织过滤 adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, # 或 Mus musculus obs_value_filtercell_type B cell and tissue_general lung and is_primary_data True, obs_column_names[assay, disease, sex, donor_id], ) # 多基因 多条件组合查询 adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, var_value_filterfeature_name in [CD4, CD8A, CD19, FOXP3], obs_value_filtercell_type T cell and disease COVID-19 and is_primary_data True, obs_column_names[cell_type, tissue_general, donor_id], )过滤语法速查语法由 TileDB-SOMA 解析执行详见 census_schema.mdobs_value_filter过滤细胞维度var_value_filter过滤基因维度逻辑组合使用and、or亦支持、|多值成员判断使用in如tissue in [lung, liver]数值比较支持、、、用obs_column_names/var_column_names只选取需要的列需要括号分组时可直接书写如(cell_type neuron or cell_type astrocyte) and disease ! normal。值得警惕的坑在当前 LTS release 中disease与disease_ontology_term_id字段可能以||分隔符存放多个值。此时像disease COVID-19这样的精确相等过滤会漏掉同时标注了其他疾病标签的细胞。若要做完整的疾病队列分析先用get_obs()或summary_cell_counts检查该版本里字段的实际编码再选择匹配的过滤表达式。元数据与表达矩阵分开取# 只查细胞元数据不触碰表达矩阵 cell_metadata cellxgene_census.get_obs( census, homo_sapiens, value_filterdisease COVID-19 and is_primary_data True, column_names[cell_type, tissue_general, donor_id] ) # 只查基因元数据校验基因名/Ensembl ID 是否存在 gene_metadata cellxgene_census.get_var( census, homo_sapiens, value_filterfeature_name in [CD4, CD8A], column_names[feature_id, feature_name, feature_length] )先探索、再查询的两步工作流是官方推荐的做法先用get_obs()得到目标队列在细胞类型、组织上的value_counts()分布确认数据存在且规模可控后再据此构造精确的get_anndata()表达查询避免盲目拉取大矩阵。若某个基因在特定数据集里根本没有被测序get_anndata()结果会受到影响——此时可借助get_presence_matrix(census, homo_sapiens, var_value_filter...)查询基因-数据集存在矩阵对应底层的feature_dataset_presence_matrix稀疏布尔矩阵参见 census_schema.md先确认覆盖情况再选数据集。模式 4大规模查询核外 / Out-of-Core 处理当筛选结果超过可用内存如脑组织的全部去重细胞就不能再用get_anndata()一次性物化。此时应降级到 TileDB-SOMA 的axis_query()接口对表达矩阵分块迭代逐批消费、边取边算import tiledbsoma as soma # 创建轴查询axis queryobs 轴与 var 轴各自独立过滤 with census[census_data][homo_sapiens].axis_query( measurement_nameRNA, obs_querysoma.AxisQuery( value_filtertissue_general brain and is_primary_data True ), var_querysoma.AxisQuery( value_filterfeature_name in [FOXP2, TBR1, SATB2] ), ) as query: # 逐块迭代稀疏表达矩阵 iterator query.X(raw).tables() for batch in iterator: # batch 是 pyarrow.Table关键列 # - soma_data : 表达值计数 # - soma_dim_0: 细胞obs坐标 # - soma_dim_1: 基因var坐标 process_batch(batch)增量统计示例——在无法全量载入时用游走式累加计算均值import tiledbsoma as soma # 例增量计算三基因的全局平均表达 n_observations 0 sum_values 0.0 with census[census_data][homo_sapiens].axis_query( measurement_nameRNA, obs_querysoma.AxisQuery(value_filtertissue_general brain and is_primary_data True), var_querysoma.AxisQuery(value_filterfeature_name in [FOXP2, TBR1, SATB2]), ) as query: iterator query.X(raw).tables() for batch in iterator: values batch[soma_data].to_numpy() # 稀疏表只含非零条目 n_observations len(values) sum_values values.sum() mean_expression sum_values / n_observations若还需要方差可把均值扩展为Welford 在线算法n/mean/M2三变量递推完整实现见 common_patterns.md。核外模式的取舍逻辑很明确先用模式 2/3 的元数据查询估算细胞数规模过大典型阈值 10 万细胞就切换到axis_query()分块处理。在技能最佳实践中SKILL.md这一先估数再定路线的流程被单独列为一节。模式 5基于 PyTorch 的机器学习当训练数据量大到无法直接做全内存转换时可直接在axis_query()之上挂接TileDB-SOMA-ML的数据集与 DataLoader。注意旧的cellxgene_census.experimental.mlPyTorch loaders已经弃用并计划移除一律使用tiledbsoma_mlimport 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_nameRNA, obs_querysoma.AxisQuery( value_filtertissue_general liver and is_primary_data True ), ) as query: dataset ExperimentDataset( queryquery, layer_nameraw, # 使用原始计数层 obs_column_names[cell_type], # 从 obs 带出的标签列 batch_size128, shuffleTrue, ) dataloader experiment_dataloader(dataset) # 训练循环X 为表达张量obs 为元数据字典 for epoch in range(num_epochs): # num_epochs/model/criterion/optimizer 由你定义 dataset.set_epoch(epoch) # 每个 epoch 需要先设置 epoch重置打乱状态 for X, obs in dataloader: labels obs[cell_type] # 前向 outputs model(X) loss criterion(outputs, labels) # 反向与优化 optimizer.zero_grad() loss.backward() optimizer.step()训练/测试划分ExperimentDataset内置random_split返回两个独立数据集train_dataset, test_dataset dataset.random_split(0.8, 0.2, seed42) train_loader experiment_dataloader(train_dataset, num_workers2) test_loader experiment_dataloader(test_dataset, num_workers2)易错点batch_size与shuffle必须设置在ExperimentDataset上而不是torch.utils.data.DataLoader上experiment_dataloader()会拒绝DataLoader 层级的batch_size、shuffle、sampler、batch_sampler参数。原因在于分块与打乱逻辑必须由数据集层基于 TileDB-SOMA 查询驱动才能在核外模式下保持一致性。技能中同款模式还可用于直接构建细胞类型分类器见 SKILL.md 的 Use Case 3。模式 6空间转录组数据Spatial Census对于受支持的 Census release空间数据存放在独立的census_spatial_sequencing集合中与单细胞数据分离管理。空间 obs 在共享核心元数据的基础上额外携带array_col、array_row、in_tissue等空间列每个场景scene下还提供spatial[scene_id].obsl[loc]点云坐标。查询 Visium 或 Slide-seq V2 数据前需安装cellxgene-census[spatial]extra并使用较新的 TileDB-SOMA 版本技能要求 1.15.5import cellxgene_census import tiledbsoma as soma with cellxgene_census.open_soma(census_version2025-11-08) as census: spatial_experiment census[census_spatial_sequencing][homo_sapiens] with spatial_experiment.axis_query( measurement_nameRNA, obs_querysoma.AxisQuery( # 用 dataset_id 圈定某个空间数据集 value_filterdataset_id 4cceac62-9513-42a4-90e5-2878dbb0192c ), ) as query: # 一步导出为 spatialdata.SpatialData sdata query.to_spatialdata(X_nameraw)得到的sdata是标准的spatialdata.SpatialData对象可直接进入空间转录组下游可视化与分析管线。关于空间对象结构obs、ms[RNA]、spatial[scene_id].obsl[loc]可参考 census_schema.md。模式 7与 Scanpy 的集成Census 与 Scanpy 生态无缝衔接get_anndata()返回的就是标准AnnData可直接进入 Scanpy 的经典单细胞流程标准化 → 对数化 → 高变基因 → PCA → 邻接图 → UMAP → 可视化import scanpy as sc # 从 Census 载入数据返回 AnnData adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, obs_value_filtercell_type neuron and tissue_general cortex and is_primary_data True, ) # 标准 Scanpy 工作流 sc.pp.normalize_total(adata, target_sum1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes2000) # 降维 sc.pp.pca(adata, n_comps50) sc.pp.neighbors(adata) sc.tl.umap(adata) # 可视化按细胞类型/组织/疾病着色 sc.pl.umap(adata, color[cell_type, tissue, disease])在跨组织比较场景中可以先在get_anndata()中把组织字段带入obs再调用差异表达等 Scanpy 工具with cellxgene_census.open_soma() as census: adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, obs_value_filtercell_type macrophage and tissue_general in [lung, liver, brain] and is_primary_data True, ) # 比较巨噬细胞在不同组织间的差异表达基因 sc.tl.rank_genes_groups(adata, groupbytissue_general)这一模式SKILL.md 的 Use Case 4说明了 Census 数据与本地单细胞分析栈的互操作方式——当分析对象是你自己的本地数据时应改用 scanpy / anndata / scvi-tools 等技能Census 的价值在于提供跨数据集的公共参考坐标。模式 8多数据集 / 跨组织集成整合多个数据集有两种互补策略分别对应显式分而治之与单查询合并策略 1分别查询多个组织再拼接——适合需要对每个子集做个性化预处理、或按来源跟踪批次的情况tissues [lung, liver, kidney] adatas [] for tissue in tissues: adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, obs_value_filterftissue_general {tissue} and is_primary_data True, ) adata.obs[tissue] tissue # 显式打上组织标签防止拼接后信息丢失 adatas.append(adata) # 使用 AnnData 当前版本 API 拼接自动对齐 var 轴基因 import anndata as ad combined ad.concat(adatas, labeltissue, keystissues)策略 2一次查询多个组织——条件更简单、返回单个AnnData适合数据同质化的场景adata cellxgene_census.get_anndata( censuscensus, organismHomo sapiens, obs_value_filtertissue_general in [lung, liver, kidney] and is_primary_data True, )更高阶的批次校正可在拼接后交给 Scanpy 外部工具链完成例如逐个dataset_id查询得到各AnnData列表后调用scanpy.external的scanorama_integrate(adatas)示例见 common_patterns.md。多数据集场景下的关键提醒仍然是只要不是刻意分析跨库重复过滤条件中的is_primary_data True不能省若要做基因层面的跨数据集可比性分析先用存在矩阵确认目标基因在各数据集中的覆盖情况。贯穿八个模式的通用最佳实践综合 SKILL.md 与 common_patterns.md 中的原则以下纪律应贯穿于上述所有模式无条件使用上下文管理器——所有open_soma()、axis_query()都放进with块杜绝资源泄漏固定 Census 版本——同一套分析在所有步骤中使用同一个census_version并关注发布说明中的版本变更默认过滤is_primary_data True——避免重复计数只有专门分析重复细胞时才关闭只取需要的列与基因——用obs_column_names、var_value_filter把数据裁剪到最小可用集减少传输与内存压力宽窄组织字段各取所需——跨组织粗分组用tissue_general如immune system精细场景用tissue如peripheral blood mononuclear cell优先使用本体论术语——cell_type_ontology_term_id CL:0000236比跨数据集的自由文本cell_type B cell更稳定见 common_patterns.md查询前检查数据集存在矩阵——get_presence_matrix()确认目标基因是否真的被测序避免得到意外的空结果先探索、后查询、再分批——从get_obs()元数据统计起步规模可控时用get_anndata()超过内存就用axis_query()核外迭代。常见故障排查要点详见 SKILL.md 的 Troubleshooting 小节返回细胞过多时收紧过滤器、用tissue替代tissue_general提高粒度或按dataset_id圈定数据集出现内存错误时缩减基因集合或转入核外迭代结果中出现重复细胞时检查is_primary_data过滤报基因未找到时注意基因符号大小写敏感、改用feature_idEnsembl ID重试并通过存在矩阵确认该基因是否在 Census 构建时被过滤。延伸阅读Census skill 在仓库中还提供了三份可相互配套的参考文档按需深入census_schema.mdCensus 数据组织、全部元数据字段、过滤语法与运算符、SOMA 对象类型、数据收录标准common_patterns.md按探索型查询 / 中小查询 / 大查询 / PyTorch / 空间 / 集成分类的更多代码示例与坑位清单core_workflow_patterns.md本文骨架对应的完整八模式权威代码源。在实际研究管线中请把模式 18 组合使用用模式 1 固定环境、模式 2 完成数据侦察、模式 3/4 按规模取数、模式 58 分别对接建模、空间、Scanpy 与多数据集场景即可在 2.17 亿级细胞的公共参考数据上构建可复现、可扩展的单细胞分析流程。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
