企业官网建设流程全解析

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-skills

CZ 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 查询数据工作流示意图

环境与版本约定

本文所有示例均以技能仓库中声明的环境为前提，保持一致可获得可复现的结果：

技能依赖包清单在 tests/skill-requirements.toml 中登记为cellxgene-census、tiledbsoma、tiledbsoma-ml、scanpy、spatialdata，安装命令如下：

# 基础安装（查询、AnnData 工作流） uv pip install "cellxgene-census==1.17.*" # 空间转录组工作流 uv pip install "cellxgene-census[spatial]==1.17.*" "spatialdata[extra]>=0.2.5" # PyTorch 模型训练 uv pip install "cellxgene-census==1.17.*" tiledbsoma-ml

Census 构建在 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_version="2025-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(f"Total cells: {int(summary_values['total_cell_count']):,}") print(f"Unique 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_filter="tissue_general == 'brain' and is_primary_data == True", column_names=["cell_type"] # 只取需要的列，减少传输 ) unique_cell_types = cell_metadata["cell_type"].unique() print(f"Found {len(unique_cell_types)} cell types in brain") # 按组织统计去重细胞数 tissue_metadata = cellxgene_census.get_obs( census, "homo_sapiens", value_filter="is_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_id（Ensembl 基因 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( census=census, organism="Homo sapiens", # 或 "Mus musculus" obs_value_filter="cell_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( census=census, organism="Homo sapiens", var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19', 'FOXP3']", obs_value_filter="cell_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.md）：

• obs_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_filter="disease == '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_filter="feature_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 query）：obs 轴与 var 轴各自独立过滤 with census["census_data"]["homo_sapiens"].axis_query( measurement_name="RNA", obs_query=soma.AxisQuery( value_filter="tissue_general == 'brain' and is_primary_data == True" ), var_query=soma.AxisQuery( value_filter="feature_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_name="RNA", obs_query=soma.AxisQuery(value_filter="tissue_general == 'brain' and is_primary_data == True"), var_query=soma.AxisQuery(value_filter="feature_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_ml：

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="tissue_general == 'liver' and is_primary_data == True" ), ) as query: dataset = ExperimentDataset( query=query, layer_name="raw", # 使用原始计数层 obs_column_names=["cell_type"], # 从 obs 带出的标签列 batch_size=128, shuffle=True, ) 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, seed=42) train_loader = experiment_dataloader(train_dataset, num_workers=2) test_loader = experiment_dataloader(test_dataset, num_workers=2)

易错点：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.5）：

import cellxgene_census import tiledbsoma as soma with cellxgene_census.open_soma(census_version="2025-11-08") as census: spatial_experiment = census["census_spatial_sequencing"]["homo_sapiens"] with spatial_experiment.axis_query( measurement_name="RNA", obs_query=soma.AxisQuery( # 用 dataset_id 圈定某个空间数据集 value_filter="dataset_id == '4cceac62-9513-42a4-90e5-2878dbb0192c'" ), ) as query: # 一步导出为 spatialdata.SpatialData sdata = query.to_spatialdata(X_name="raw")

得到的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( census=census, organism="Homo sapiens", obs_value_filter="cell_type == 'neuron' and tissue_general == 'cortex' and is_primary_data == True", ) # 标准 Scanpy 工作流 sc.pp.normalize_total(adata, target_sum=1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes=2000) # 降维 sc.pp.pca(adata, n_comps=50) 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( census=census, organism="Homo sapiens", obs_value_filter="cell_type == 'macrophage' and tissue_general in ['lung', 'liver', 'brain'] and is_primary_data == True", ) # 比较巨噬细胞在不同组织间的差异表达基因 sc.tl.rank_genes_groups(adata, groupby="tissue_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( census=census, organism="Homo sapiens", obs_value_filter=f"tissue_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, label="tissue", keys=tissues)

策略 2：一次查询多个组织——条件更简单、返回单个AnnData，适合数据同质化的场景：

adata = cellxgene_census.get_anndata( census=census, organism="Homo sapiens", obs_value_filter="tissue_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 中的原则，以下纪律应贯穿于上述所有模式：

1. 无条件使用上下文管理器——所有open_soma()、axis_query()都放进with块，杜绝资源泄漏；
2. 固定 Census 版本——同一套分析在所有步骤中使用同一个census_version，并关注发布说明中的版本变更；
3. 默认过滤is_primary_data == True——避免重复计数；只有专门分析重复细胞时才关闭；
4. 只取需要的列与基因——用obs_column_names、var_value_filter把数据裁剪到最小可用集，减少传输与内存压力；
5. 宽窄组织字段各取所需——跨组织粗分组用tissue_general（如'immune system'），精细场景用tissue（如'peripheral blood mononuclear cell'）；
6. 优先使用本体论术语——cell_type_ontology_term_id == 'CL:0000236'比跨数据集的自由文本cell_type == 'B cell'更稳定（见 common_patterns.md）；
7. 查询前检查数据集存在矩阵——get_presence_matrix()确认目标基因是否真的被测序，避免得到意外的空结果；
8. 先探索、后查询、再分批——从get_obs()元数据统计起步，规模可控时用get_anndata()，超过内存就用axis_query()核外迭代。

常见故障排查要点（详见 SKILL.md 的 Troubleshooting 小节）：返回细胞过多时收紧过滤器、用tissue替代tissue_general提高粒度或按dataset_id圈定数据集；出现内存错误时缩减基因集合或转入核外迭代；结果中出现重复细胞时检查is_primary_data过滤；报"基因未找到"时注意基因符号大小写敏感、改用feature_id（Ensembl ID）重试，并通过存在矩阵确认该基因是否在 Census 构建时被过滤。

延伸阅读

Census skill 在仓库中还提供了三份可相互配套的参考文档，按需深入：

• census_schema.md：Census 数据组织、全部元数据字段、过滤语法与运算符、SOMA 对象类型、数据收录标准；
• common_patterns.md：按"探索型查询 / 中小查询 / 大查询 / PyTorch / 空间 / 集成"分类的更多代码示例与坑位清单；
• core_workflow_patterns.md：本文骨架对应的完整八模式权威代码源。

在实际研究管线中，请把模式 1～8 组合使用：用模式 1 固定环境、模式 2 完成数据侦察、模式 3/4 按规模取数、模式 5～8 分别对接建模、空间、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