Name: CZ CELLxGENE Discover Census LTS 2025-11-08
Creator: Chan Zuckerberg Initiative (CZI)
Published: 2023-10-30
License: https://creativecommons.org/licenses/by/4.0/

信息速览

数据集名称CELLxGENE

数据类型H5AD AnnData, TileDB-SOMA

规模约 17,651 名人类供体

接入方式CZI Single-Cell Biology, 社区贡献

AI 就绪度

CZ CELLxGENE — 单细胞转录组标准化数据平台

千方病案医数集 · AI Ready 数据集 | 状态：published

CZ CELLxGENE 是全球最大、增长最快的标准化单细胞转录组平台。其 Census 组件 (LTS 2025-11-08) 以 TileDB-SOMA 格式统一了 2.17 亿细胞（1.62 亿人类 + 4,630 万小鼠 + 1,000 万其他灵长类），覆盖 898 种细胞类型和 417 种组织。通过严格的 ONTOLOGY 对齐标注（Cell Ontology + UBERON + MONDO + EFO）和原始 Count Matrix 标准化，Census 已成为所有单细胞 AI 基础模型——scGPT (33M 细胞预训练)、Geneformer (30M/104M)、UCE (36M)、CellFM (>100M)、TranscriptFormer (112M)——的标准预训练数据源。CZI 于 2025 年 2 月启动的 Billion Cells Project 目标在首年生成近 5 亿细胞数据，将单细胞 AI 推向下一个量级。

§0 出版与审核声明：page_status: published。核心论文：CZI Single-Cell Biology Program, bioRxiv 2023.10.30.563174 (2023)。数据版本：Census LTS 2025-11-08（Census Schema 2.4.0, Dataset Schema 7.0.0）。维护方：Chan Zuckerberg Initiative (CZI) + Lattice Curation Team (Stanford University)。许可：CC BY 4.0。点击导航：§1 概览 | §2 科学背景 | §3 技术规格 | §4 数据结构 | §5 下载 | §6 AI 指南 | §7 坑点 | §8 SOTA | §9 资源 | §10 声明卡 | §C 校验

§1 概览

§1.1 平台定位

CZ CELLxGENE (Chan Zuckerberg CELL by GENE) 是由 Chan Zuckerberg Initiative (CZI) 于 2017 年发起、2018 年正式发布的单细胞转录组交互式数据平台。其核心使命是将全球分散的单细胞测序数据统一到一个标准化、可互操作的数据基础设施中，使研究人员能够无需下载数据即可在云端查询、分析、建模数亿细胞的基因表达谱。

CELLxGENE 由三个互补组件构成：

组件	定位	用户界面	核心技术	目标用户
Discover	Web 门户	浏览器	React + WebGL 可视化	生物学家/临床医生
Census	程序化访问	Python/R API	TileDB-SOMA 列式存储	计算生物学家/AI 研究者
Annotate	桌面工具	本地安装 (MIT)	Python + Flask + D3	实验生物学家/策展人

§1.2 Census LTS 2025-11-08 核心统计

指标	人类	小鼠	猕猴	绒猴	黑猩猩	合计
总细胞数	162,025,130	46,299,127	7,010,229	2,275,451	158,099	217,767,936
独特细胞数	99,633,637	21,029,771	2,929,014	1,712,738	158,099	125,463,259
数据集数	—	—	—	—	—	1,845
细胞类型	898	473	54	40	25	—
组织	417	101	29	33	1	—
组织大类	70	36	2	1	1	—
Assay 类型	37	16	2	1	1	—
疾病	192	16	1	1	1	—
发育阶段	194	66	4	3	1	—
自报种族	33	1	1	1	1	—

独特细胞（unique cells）指去除重复后实际参与 Census 构建的细胞数。总细胞数大于独特细胞数是因为同一细胞可能出现在多个数据集中（如同一数据集被多个研究引用），Census 通过 is_primary_data 标志去重。

§1.3 版本演进时间线

时间	里程碑	关键变化
2017	CZI 成立	Chan Zuckerberg Initiative 成立，单细胞生物学列为优先方向
2018.06	CELLxGENE Discover 上线	首批 8 个数据集，React 前端，UMAP/t-SNE 交互可视化
2019	CELLxGENE Annotate 发布	开源桌面工具 (MIT)，支持协作式细胞类型标注
2020	Lattice 策展团队成立	Stanford 大学获 CZI 资助，专职数据标准化策展
2022.03	Schema 1.0 发布	首个正式数据提交规范，强制 ONTOLOGY 对齐
2022.12	Census v1 (“stable”)	首个 Census 版本，~50M 细胞，TileDB-SOMA 格式
2023.10	bioRxiv 预印本发表	CZI Single-Cell Biology, doi:10.1101/2023.10.30.563174
2023.12	Census LTS 2023-12-15	73M 细胞，Schema 3.0，加入小鼠数据
2024.02	scGPT 发表 (Nature Methods)	首个基于 CELLxGENE 预训练的单细胞基础模型
2024.05	TranscriptFormer 预印本	CZI 自研基础模型，12 物种 112M 细胞
2024.07	Schema 5.0 → 6.0	新增多组学字段、空间转录组支持
2025.01	Census LTS 2025-01-30	125M 细胞，Schema 6.1，加入 TranscriptFormer 嵌入
2025.02	Billion Cells Project 启动	目标首年 5 亿细胞，CZI 投入 $2.5 亿
2025.06	Schema 7.0 发布	disease 字段支持多值，feature_name 不再唯一
2025.11	Census LTS 2025-11-08	当前稳定版：217M 细胞，Schema 2.4.0/7.0.0

§1.4 INFOBOX

┌──────────────────────────────────────────────────────────┐
│  CZ CELLxGENE                                            │
├──────────────────────────────────────────────────────────┤
│  全称         Chan Zuckerberg CELL by GENE              │
│  维护方       Chan Zuckerberg Initiative (CZI)          │
│  策展方       Lattice Curation Team (Stanford)          │
│  成立时间     2018 年                                    │
│  当前版本     Census LTS 2025-11-08                      │
│  数据规模     2.17 亿细胞 (1.62 亿人类)                  │
│  数据集数     1,845 个标准化数据集                        │
│  细胞类型     898 种 (人类)                               │
│  组织覆盖     417 种 (人类)                               │
│  Assay 类型   37 种 (人类)                               │
│  数据格式     H5AD (AnnData) / TileDB-SOMA               │
│  许可证       CC BY 4.0                                  │
│  数据下载     AWS S3 (免签名) / Census API (Python/R)    │
│  核心论文     bioRxiv 2023.10.30.563174                   │
│  DOI          10.1101/2023.10.30.563174                   │
│  网站         https://cellxgene.cziscience.com/          │
│  GitHub       github.com/chanzuckerberg/cellxgene-census │
│  AI 模型      scGPT / Geneformer / UCE / CellFM / TF     │
└──────────────────────────────────────────────────────────┘

§2 单细胞生物学科学背景

§2.1 从 bulk RNA-seq 到 single-cell RNA-seq

传统 bulk RNA-seq 将组织中数百万细胞的基因表达取平均值，生成一个"平均转录组"。这种方法掩盖了细胞间的异质性——一个看似同质的肿瘤样本实际上可能包含癌细胞、免疫细胞、基质细胞、内皮细胞等数十种细胞类型，每种都有截然不同的基因表达谱。

单细胞 RNA-seq (scRNA-seq) 通过将组织解离为单个细胞，逐一测量每个细胞的基因表达，从根本上解决了这个问题：

维度	Bulk RNA-seq	scRNA-seq
测量单位	组织平均值	单个细胞
分辨率	细胞群体水平	单细胞水平
稀有细胞检测	被平均效应掩盖	可检测 <1% 的稀有群体
细胞类型发现	不可行	可发现全新细胞类型
发育轨迹	不可行	可推断分化轨迹
数据量	~20K 基因 × 1 样本	~20K 基因 × 10K-100K 细胞
稀疏度	~10-20% 零值	90-95% 零值
成本/样本	~$100-300	~$3,000-10,000

§2.2 10x Chromium droplet 技术原理

当前 scRNA-seq 领域的主导平台是 10x Genomics Chromium，它采用微流控液滴技术 (droplet-based microfluidics) 实现高通量单细胞捕获：

第 1 步——样本制备：组织样本通过酶解或机械解离成为单细胞悬液。活细胞比例需 >70%，细胞浓度调整至 700-1,200 cells/μL。

第 2 步——GEM 生成：在 Chromium X 仪器上，细胞悬液与含有条形码凝胶珠 (Gel Bead) 的试剂混合，通过微流控芯片生成数万个 GEMs (Gel Beads-in-emulsions)。每个 GEM 是一个纳升级油包水液滴，理想情况下包含一个细胞和一个 Gel Bead。

第 3 步——细胞裂解与 mRNA 捕获：GEM 中的细胞被裂解，释放的 mRNA 被 Gel Bead 上的 oligo(dT) 引物捕获。每个引物包含：

10x Barcode（16 bp）：标识细胞身份（同一 GEM 中所有分子共享同一 barcode）
UMI（12 bp）：标识原始 mRNA 分子（每个引物独立）
poly(dT)：捕获 mRNA 的 poly(A) 尾

第 4 步——逆转录与文库构建：mRNA 被逆转录为 cDNA，GEMs 被打破，cDNA 池被扩增并通过酶切构建测序文库。

第 5 步——高通量测序：在 Illumina NovaSeq 上进行双端测序。Read 1 含 10x Barcode + UMI，Read 2 含 cDNA 序列。

第 6 步——Cell Ranger 处理：10x 官方软件 Cell Ranger 将原始 FASTQ 处理为基因 × 细胞的计数矩阵：

Read 1 提取 10x Barcode 和 UMI
Read 2 比对到参考基因组 (STAR)
UMI 去重（同一 cell barcode + gene + UMI 的 reads 合并为一个计数）
EmptyDrops 区分真实细胞与背景噪声
输出 MEX 格式计数矩阵（genes × cells，90-95% 为零）

典型产出：一次 10x Chromium 实验约 10,000-20,000 细胞，~20,000 基因，产生 ~160M-400M 个数据点（大部分为零）。

§2.3 scRNA-seq 数据分析标准流程

scRNA-seq 数据的分析通常遵循以下标准流程，CELLxGENE 的标准化体系即建立在每一步的最佳实践之上：

步骤	操作	工具	CELLxGENE 对应
1. 质控	过滤低质量细胞（低基因数、高线粒体比例）和双联体 (doublets)	Scanpy/Seurat	提交方完成，`is_primary_data` 标志
2. 归一化	消除文库大小差异	Scanpy (`sc.pp.normalize_total`)	Census 保留原始 Count，不归一化
3. 对数变换	使数据分布更接近正态	`sc.pp.log1p`	用户自行处理
4. 高变基因选择	选取 2,000-4,000 个高变基因 (HVGs)	`sc.pp.highly_variable_genes`	Census 提供全基因矩阵
5. 降维	PCA 降至 50 维	`sc.pp.pca`	Census 预计算 scVI 嵌入
6. 聚类	Leiden/Louvain 算法	`sc.tl.leiden`	原作者标注 + CL 标准化
7. 可视化	UMAP/t-SNE 2D 投影	`sc.tl.umap`	Discover 门户内置
8. 细胞类型注释	Marker gene + 自动注释工具	CellTypist/SingleR	Lattice 策展 + CL 映射
9. 差异表达	簇间差异基因	Wilcoxon/MAST	Census API 支持
10. 轨迹分析	发育/分化轨迹推断	Monocle/Slingshot	发育阶段字段 (`development_stage`)

§2.4 细胞图谱愿景与 Human Cell Atlas

CELLxGENE 的终极目标是构建人类细胞图谱 (Human Cell Atlas, HCA)——一个覆盖人体所有组织、所有细胞类型的全面参考图谱。

项目	主导方	规模	与 CELLxGENE 的关系
Human Cell Atlas (HCA)	国际联盟 (Wellcome + CZI)	目标 10 亿细胞	数据贡献者，HCA 数据流入 CELLxGENE
Tabula Sapiens	CZ Biohub + Stanford	~500K 细胞, 24 组织	CELLxGENE 上的标杆数据集
Tabula Muris	CZ Biohub	~100K 细胞, 20 组织	小鼠参考图谱
Allen Brain Cell Atlas	Allen Institute	~5M 细胞	脑组织数据贡献
Billion Cells Project	CZI	目标 5 亿/年	CELLxGENE 的下一代扩展

HCA 的愿景是：人体约 37 万亿细胞，估计约 200-500 种主要细胞类型（含亚型可能达数千种）。截至 2025 年，CELLxGENE 已覆盖 898 种细胞类型和 417 种组织，但仍远未完成全图谱。

§2.5 单细胞基础模型与 CELLxGENE 的数据角色

2023-2025 年，单细胞生物学经历了与 NLP 类似的"基础模型革命"：在大规模无标注数据上预训练 Transformer，然后在下游任务上微调。CELLxGENE Census 在这一浪潮中扮演了**“Common Crawl for single-cell biology”**的角色——几乎所有主流单细胞基础模型都使用 Census 作为核心预训练数据：

模型	年份	预训练数据	数据来源	参数量	架构	核心论文
scGPT	2024	33M 人类细胞	CELLxGENE Census	~50M	Transformer (512 dim, 12 layer, 8 head)	Nature Methods
Geneformer V1	2023	30M 细胞	Genecorpus (CELLxGENE 子集)	~30M-100M	BERT-style rank encoding	Nature
Geneformer V2	2025	104M 细胞	CELLxGENE Census 扩展	~100M-300M	同 V1 + 多物种	bioRxiv
UCE	2023	36M 细胞	CELLxGENE Census	650M	Encoder-only, 多物种	bioRxiv
CellFM	2025	>100M 细胞	CELLxGENE + 其他	800M	Encoder + 跨模态	Nature Comms
TranscriptFormer	2025	112M 细胞 (12 物种)	CELLxGENE Census	~300M	Encoder-decoder, CZI 自研	bioRxiv
scPRINT	2024	50M 细胞	CELLxGENE Census	~100M	Encoder, 多任务	bioRxiv
AIDO.Cell	2025	100M+ 细胞	CELLxGENE Census	~1B	多模态	arXiv

为什么 CELLxGENE 成为标准预训练源？

规模：2.17 亿细胞是迄今最大规模的单细胞数据集合
标准化：所有数据经过 ONTOLOGY 对齐和 Lattice 策展，元数据一致
原始 Count：提供未经归一化的原始 UMI Count，允许用户自定义预处理
多样性：覆盖 5 个物种、898 种细胞类型、417 种组织、192 种疾病
可编程访问：Census API 支持按条件筛选子集，无需下载全部数据
许可：CC BY 4.0 允许商业使用（不同于 HCA 的部分数据限制）
版本稳定：LTS 版本保证 5 年可访问，支持预训练实验复现
嵌入预计算：内置 scVI 和 TranscriptFormer 嵌入，可直接用于下游分析

§2.6 ONTOLOGY 对齐体系

CELLxGENE 最核心的标准化创新是强制 ONTOLOGY 对齐——所有元数据字段必须使用标准本体论术语，而非自由文本：

元数据字段	本体论	前缀	示例	维护方
`cell_type`	Cell Ontology (CL)	`CL:`	`CL:0000084` (T cell)	OBO Foundry
`tissue`	UBERON	`UBERON:`	`UBERON:0002370` (thymus)	OBO Foundry
`disease`	MONDO	`MONDO:`	`MONDO:0005148` (COVID-19)	OBO Foundry
`assay`	EFO	`EFO:`	`EFO:0009901` (10x v3)	EBI
`development_stage`	HsapDv / MmusDv	`HsapDv:`	`HsapDv:0000082` (adult)	OBO Foundry
`self_reported_ethnicity`	HANCESTRO	`HANCESTRO:`	`HANCESTRO:0005` (European)	HANCESTRO
`sex`	PATO	`PATO:`	`PATO:0000384` (female)	OBO Foundry

策展流程：原始数据提交者提供自由文本注释（author_cell_type 字段），Lattice 策展团队对照 ONTOLOGY 标准进行映射，生成标准化字段（cell_type）。例如：

原作者标注 "CD4+ helper T cells" → CL 映射 → CL:0000491 (CD4-positive helper T cell)
原作者标注 "lung adenocarcinoma" → MONDO 映射 → MONDO:0005061

§3 技术规格

§3.1 Census 架构：TileDB-SOMA

Census 不使用传统的关系型数据库或文件系统存储，而是采用 TileDB-SOMA (Storage of Objects, Matrices, and Arrays)——一种基于 TileDB 的列式多维数组存储引擎：

层级	概念	说明
TileDB 引擎	底层存储	稀疏/稠密多维数组引擎，支持云原生 (S3)
SOMA 层	数据抽象	Collection / DataFrame / SparseNDArray / DenseNDArray
Census 层	业务逻辑	按物种组织的 obs/var/X/MS 矩阵

为什么不用 H5AD/AnnData？

维度	H5AD (AnnData)	TileDB-SOMA
格式	单个 HDF5 文件	目录/云对象集合
随机访问	需加载整个文件	支持列式随机读取
云原生	需下载后访问	直接从 S3 流式读取
并发写	不支持	支持多写者
压缩率	一般	列式压缩，3-5 倍
查询速度	全量加载	10-100 倍快（条件查询）
版本管理	文件覆盖	TileDB 时间旅行

Census 目录结构：

census/
├── census_info/                    # Census 元信息
│   ├── summary/                    # 汇总统计
│   ├── datasets/                   # 数据集清单
│   └── census_schema_version/      # Schema 版本
├── census_data/
│   ├── homo_sapiens/               # 人类数据
│   │   ├── obs/                    # 细胞元数据 (DataFrame)
│   │   ├── var/                    # 基因元数据 (DataFrame)
│   │   ├── ms/                     # 测量集 (Measurement Set)
│   │   │   └── RNA/
│   │   │       ├── X/             # Count 矩阵
│   │   │       │   ├── raw/       # 原始 UMI Count (SparseNDArray)
│   │   │       │   └── normalized/ # 归一化矩阵 (SparseNDArray, 可选)
│   │   │       ├── var/           # RNA 测量级基因元数据
│   │   │       └── featuremappings/ # 基因 ID 映射
│   │   └── obs_embeddings/         # 预计算细胞嵌入
│   │       ├── scvi/               # scVI 嵌入
│   │       ├── tf-sapiens/         # TranscriptFormer 人类嵌入
│   │       └── tf-exemplar-human/  # TF exemplar 嵌入
│   ├── mus_musculus/               # 小鼠数据 (同构)
│   ├── macaca_mulatta/             # 猕猴数据
│   ├── callithrix_jacchus/         # 绒猴数据
│   └── pan_troglodytes/            # 黑猩猩数据
└── census_subsets/                 # 预定义子集

§3.2 Census Schema 版本演进

Schema 版本	发布时间	关键变化
1.0	2022.03	首个正式 Schema，强制 ONTOLOGY 对齐
2.0	2022.06	新增 `is_primary_data` 去重字段
3.0	2022.12	新增小鼠数据支持；`raw` 矩阵字段
4.0	2023.06	新增空间转录组字段 (`spatial_coordinates`)
5.0	2024.03	新增多组学字段 (`multiome`); `cell_type_ontology_term_id` 格式统一
6.0	2024.07	新增 `suspension_type` (cell/nucleus); 空间数据正式支持
7.0	2025.06	`disease` 支持多值 (` \

§3.3 数据提交与策展流程

CELLxGENE 的数据来源是社区驱动 + Lattice 策展的混合模式：

第 1 步——数据提交：研究者在发表论文后将 scRNA-seq 数据提交到 CELLxGENE Discover。提交需遵循 Dataset Schema，包含原始 Count 矩阵 (H5AD) 和元数据。

第 2 步——自动验证：CELLxGENE 数据摄入管道自动检查：

H5AD 文件格式完整性
必填元数据字段是否存在
ONTOLOGY 术语是否有效（对照 CL/UBERON/MONDO/EFO 最新版本）
基因 ID 是否为 Ensembl ID
Count 矩阵是否为非负整数

第 3 步——Lattice 人工策展：Lattice 策展团队（Stanford 大学，CZI 资助）对通过自动验证的数据集进行人工策展：

将 author_cell_type（自由文本）映射到 Cell Ontology 标准术语
校验组织注释与 UBERON 的一致性
检查疾病注释与 MONDO 的对应关系
验证实验方法与 EFO 的匹配
处理提交者无法完成的复杂或模糊标注

第 4 步——版本冻结：策展完成后，数据集获得一个稳定的 CELLxGENE Collection ID 和 Dataset ID，进入 Discover 门户。

第 5 步——Census 合并：每周，新通过策展的数据集被合并到 Census “latest” 构建中。每 6 个月，冻结一个 LTS 版本。

§3.4 数据集收录标准

CELLxGENE Census 对数据集有严格的收录标准：

标准	要求	说明
物种	人类、小鼠、猕猴、绒猴、黑猩猩	2025 年扩展到 5 种灵长类
数据类型	scRNA-seq + 空间转录组	含 10x、Smart-seq2、Slide-seq 等 37 种 assay
原始 Count	必须提供未经归一化的 UMI Count	不接受已归一化/已对数变换的数据
基因标识	Ensembl Gene ID	不接受 Gene Symbol 作为主键
元数据	必填字段完整	cell_type/tissue/disease/assay/sex 等
ONTOLOGY	全部字段 ONTOLOGY 对齐	自由文本仅保留在 `author_*` 字段
许可	CC BY 4.0	不接受更限制性的许可
出版物	优先已发表论文	预印本也可收录
质控	基本细胞质控已完成	线粒体比例、双联体检测等

§3.5 预计算嵌入

Census LTS 2025-11-08 内置了多种预计算嵌入，用户无需自行训练即可获取细胞的向量化表示：

嵌入	方法	维度	物种覆盖	用途
scVI	深度生成模型 (variational autoencoder)	30	人类 + 小鼠	批次校正、整合分析
tf-sapiens	TranscriptFormer 物种特异嵌入	256	人类 + 小鼠	跨数据集细胞类型比较
tf-exemplar	TranscriptFormer exemplar 嵌入	256	人类 + 小鼠	参考图谱映射

嵌入通过 cellxgene_census.experimental.get_embedding() 或 get_anndata(obs_embeddings=...) 获取，存储为 TileDB DenseNDArray。

§3.6 空间转录组支持

2025 年 Schema 6.0+ 正式支持空间转录组数据：

Assay	技术	分辨率	Census 支持
10x Visium	斑点捕获 (55 μm)	近单细胞	✅
Slide-seq v2	DNA 条形码珠 (10 μm)	亚细胞	✅
MERFISH	原位测序	单分子	实验性
Stereo-seq	DNA 纳米球阵列	亚细胞	实验性

空间数据在 Census 中额外包含：

spatial_coordinates：x/y 坐标
cell_size：细胞面积（Visium spot 模式下为 spot 面积）
spatial_tools：可用的空间分析工具标记

§3.7 Assay 类型分布

Census LTS 2025-11-08 人类数据包含 37 种 assay，按细胞数排序前 10：

排名	Assay	EFO ID	典型细胞数/实验	占比
1	10x 3’‘’‘’‘’‘’‘’‘’‘’’ v3	EFO:0009901	5,000-20,000	~45%
2	10x 3’‘’‘’‘’‘’‘’‘’‘’’ v2	EFO:0009899	3,000-10,000	~20%
3	10x 5’‘’‘’‘’‘’‘’‘’‘’’ v3	EFO:0009922	5,000-15,000	~8%
4	Smart-seq2	EFO:0008931	100-1,000	~5%
5	10x 5’‘’‘’‘’‘’‘’‘’‘’’ v2	EFO:0009900	3,000-10,000	~4%
6	10x Multiome	EFO:0030062	5,000-15,000	~3%
7	Drop-seq	EFO:0008728	1,000-5,000	~2%
8	10x 3’‘’‘’‘’‘’‘’‘’‘’’ v1	EFO:0010183	500-3,000	~1%
9	BD Rhapsody	EFO:0008641	2,000-10,000	~1%
10	Slide-seq v2	EFO:0030063	10,000-50,000	<1%

10x Chromium 主导效应：约 80% 的细胞来自 10x Genomics 平台。不同 assay 间的技术差异（捕获效率、基因检出数、dropout 率）是批次效应的主要来源。

§4 数据结构详解

§4.1 obs（细胞元数据）字段表

obs 是 Census 中每个细胞的元数据 DataFrame，包含以下核心字段：

字段名	类型	必填	示例	说明
`soma_joinid`	int64	是	1234567	Census 内部行 ID
`dataset_id`	str	是	“0a5b8b…”	数据集 UUID
`assay`	str	是	“10x 3’‘’‘’‘’‘’‘’‘’‘’’ v3”	EFO 标准化实验方法
`assay_ontology_term_id`	str	是	“EFO:0009901”	EFO URI
`cell_type`	str	是	“T cell”	CL 标准化细胞类型
`cell_type_ontology_term_id`	str	是	“CL:0000084”	CL URI
`tissue`	str	是	“blood”	UBERON 标准化组织
`tissue_ontology_term_id`	str	是	“UBERON:0000178”	UBERON URI
`tissue_general`	str	是	“blood”	组织大类
`tissue_general_ontology_term_id`	str	是	“UBERON:0000178”	UBERON URI
`disease`	str	是	“normal”	MONDO 标准化疾病（可多值）
`disease_ontology_term_id`	str	是	“MONDO:0000001”	MONDO URI
`donor_id`	str	是	“donor_42”	供体标识（去标识化）
`is_primary_data`	bool	是	True	是否为首次发布（去重标志）
`development_stage`	str	是	“adult”	HsapDv 标准化发育阶段
`development_stage_ontology_term_id`	str	是	“HsapDv:0000082”	HsapDv URI
`self_reported_ethnicity`	str	否	“European”	HANCESTRO 标准化种族
`self_reported_ethnicity_ontology_term_id`	str	否	“HANCESTRO:0005”	HANCESTRO URI
`sex`	str	是	“female”	PATO 标准化性别
`sex_ontology_term_id`	str	是	“PATO:0000384”	PATO URI
`suspension_type`	str	是	“cell”	cell / nucleus / na
`observation_joinid`	str	是	“dataset_id:barcoded_sample_cell_id”	全局唯一标识

§4.2 var（基因元数据）字段表

var 是每个基因的元数据 DataFrame：

字段名	类型	说明
`soma_joinid`	int64	Census 内部行 ID
`feature_id`	str	Ensembl Gene ID（唯一，如 `ENSG00000141510`）
`feature_name`	str	Gene Symbol（Schema 7.0+ 不再保证唯一）
`feature_length`	int64	基因长度 (bp)
`nnz`	int64	非零值数量（用于过滤低表达基因）
`n_measured_obs`	int64	检测到该基因的细胞数

§4.3 X（Count 矩阵）

X 是核心的基因表达矩阵，以 TileDB SparseNDArray 存储：

属性	值
维度	obs × var (细胞 × 基因)
格式	COO 稀疏矩阵（仅存储非零值）
数据类型	int32 (raw count)
非零值数量	~数十亿 (人类部分)
稀疏度	90-95% 零值
存储位置	`census_data/homo_sapiens/ms/RNA/X/raw/`

关键设计决策：Census 仅存储 原始 UMI Count（X/raw），不进行任何归一化。这允许用户根据自身需求选择归一化策略（如 Scanpy 的 sc.pp.normalize_total + sc.pp.log1p，或 scVI 的深度学习归一化）。

§4.4 obs_embeddings（预计算嵌入）

嵌入名称	存储路径	维度	数据类型	方法
`scvi`	`obs_embeddings/scvi/`	30	float32	scVI variational autoencoder
`tf-sapiens`	`obs_embeddings/tf-sapiens/`	256	float32	TranscriptFormer 物种特异
`tf-exemplar`	`obs_embeddings/tf-exemplar-human/`	256	float32	TranscriptFormer exemplar

§5 下载与访问

§5.1 Census API (Python) — 推荐方式

# 安装
# pip install cellxgene-census==1.17.*

import cellxgene_census

# 打开最新 LTS 版本（推荐用于可复现研究）
with cellxgene_census.open_soma(census_version="stable") as census:
    # 查看可用物种
    print(census["census_data"].keys())
    # [''''''''''''''''homo_sapiens'''''''''''''''', ''''''''''''''''mus_musculus'''''''''''''''', ''''''''''''''''macaca_mulatta'''''''''''''''',
    #  ''''''''''''''''callithrix_jacchus'''''''''''''''', ''''''''''''''''pan_troglodytes'''''''''''''''']

    # 查看人类数据汇总
    human = census["census_data"]["homo_sapiens"]
    print(f"总细胞数: {human.obs.count}")
    print(f"总基因数: {human.ms[''''''''''''''''RNA''''''''''''''''].var.count}")

§5.2 按条件筛选子集

import cellxgene_census

with cellxgene_census.open_soma() as census:
    # 获取特定组织+细胞类型的 AnnData 对象
    adata = cellxgene_census.get_anndata(
        census,
        organism="homo_sapiens",
        obs_value_filter="tissue == ''''''''''''''''blood'''''''''''''''' and cell_type in [''''''''''''''''T cell'''''''''''''''', ''''''''''''''''B cell'''''''''''''''', ''''''''''''''''natural killer cell'''''''''''''''']",
        var_value_filter="feature_name in [''''''''''''''''CD3D'''''''''''''''', ''''''''''''''''CD3E'''''''''''''''', ''''''''''''''''CD4'''''''''''''''', ''''''''''''''''CD8A'''''''''''''''', ''''''''''''''''MS4A1'''''''''''''''', ''''''''''''''''NKG7'''''''''''''''']",
        column_names={
            "obs": ["cell_type", "tissue", "disease", "donor_id", "assay"],
            "var": ["feature_name", "feature_id"]
        }
    )

    print(f"筛选细胞数: {adata.n_obs}")
    print(f"筛选基因数: {adata.n_vars}")
    print(adata.obs["cell_type"].value_counts())

§5.3 获取预计算嵌入

import cellxgene_census

with cellxgene_census.open_soma() as census:
    # 获取 scVI 嵌入
    adata = cellxgene_census.get_anndata(
        census,
        organism="homo_sapiens",
        obs_value_filter="tissue == ''''''''''''''''lung''''''''''''''''",
        obs_embeddings=["scvi"],
        column_names={"obs": ["cell_type", "tissue"]}
    )

    # 嵌入存储在 adata.obsm 中
    print(f"scVI 嵌入维度: {adata.obsm[''''''''''''''''scvi''''''''''''''''].shape}")
    # (n_cells, 30)

§5.4 AWS S3 直接下载

# 下载 LTS 2025-11-08 的 TileDB-SOMA 文件
aws s3 sync no-sign-request \
  s3://cellxgene-census-public-us-west-2/cell-census/2025-11-08/soma/ \
  ./census_soma/

# 下载 LTS 2025-11-08 的所有源 H5AD 文件
aws s3 sync no-sign-request \
  s3://cellxgene-census-public-us-west-2/cell-census/2025-11-08/h5ads/ \
  ./census_h5ads/

# 使用本地 Census
python -c "
import cellxgene_census
with cellxgene_census.open_soma(uri=''''''''''''''''./census_soma/'''''''''''''''') as census:
    print(census[''''''''''''''''census_data''''''''''''''''][''''''''''''''''homo_sapiens''''''''''''''''].obs.count)
"

§5.5 R 语言访问

# 安装
# install.packages("cellxgene.census")

library(cellxgene.census)

# 打开 LTS 版本
census <- open_soma(census_version = "stable")

# 获取 AnnData (Seurat 对象)
adata <- get_anndata(
  census,
  organism = "homo_sapiens",
  obs_value_filter = "tissue == ''''''''''''''''brain'''''''''''''''' and cell_type in [''''''''''''''''neuron'''''''''''''''', ''''''''''''''''astrocyte'''''''''''''''', ''''''''''''''''microglial cell'''''''''''''''']"
)

print(dim(adata))

§5.6 Discover Web 门户

CELLxGENE Discover (https://cellxgene.cziscience.com/) 提供 Web 界面：

数据集浏览：按组织、疾病、细胞类型筛选 1,845 个数据集
交互式可视化：UMAP/t-SNE 散点图，按任意元数据着色
基因表达查看：在散点图上叠加任意基因的表达水平
差异表达：选择细胞群后自动计算差异基因
嵌入对比：scVI 嵌入 vs 原始 PCA
H5AD 下载：直接下载单个数据集的 AnnData 文件

§5.7 访问方式对比

方式	适用场景	数据传输量	延迟	编程门槛
Census API (Python)	大规模分析/AI 训练	按需 (仅筛子集)	低 (S3 流式)	中
Census API ®	R 生态分析	按需	低	中
AWS S3 全量下载	离线/频繁查询	~500 GB+	一次性高	低
Discover Web	探索性查看	浏览器加载	中	无
TileDB-SOMA 直连	高级自定义查询	按需	最低	高

§6 AI 就绪指南

§6.1 Census 数据加载与 PyTorch DataLoader

"""
CELLxGENE Census → PyTorch DataLoader
使用 TileDB-SOMA-ML 实现高效流式数据加载
"""
# pip install cellxgene-census==1.17.* tiledbsoma-ml torch

import cellxgene_census
import tiledbsoma.ml
import torch
from torch.utils.data import DataLoader

def create_census_dataloader(
    organism="homo_sapiens",
    tissue="blood",
    cell_types=None,
    batch_size=512,
    shuffle=True,
    census_version="stable"
):
    """从 Census 创建 PyTorch DataLoader"""
    with cellxgene_census.open_soma(census_version=census_version) as census:
        # 构建 obs 过滤条件
        obs_filter = f"tissue == ''''''''''''''''{tissue}''''''''''''''''"
        if cell_types:
            ct_list = ", ".join([f"''''''''''''''''{ct}''''''''''''''''" for ct in cell_types])
            obs_filter += f" and cell_type in [{ct_list}]"

        # 使用 TileDB-SOMA-ML 创建数据集
        experiment = census["census_data"][organism]
        query = experiment.axis_query(
            measurement_name="RNA",
            obs_query=tiledbsoma.AxisQuery(value_filter=obs_filter)
        )

        # 创建 PyTorch Dataset
        dataset = tiledbsoma.ml.ExperimentDataset(
            query,
            layer_name="raw",
            obs_column_names=["cell_type", "tissue", "disease"]
        )

        print(f"数据集大小: {len(dataset)} 细胞")
        print(f"基因数: {dataset.shape[1]}")

        # 创建 DataLoader
        dataloader = DataLoader(
            dataset,
            batch_size=batch_size,
            shuffle=shuffle,
            num_workers=4,
            pin_memory=True
        )

        return dataloader

# 使用示例
dataloader = create_census_dataloader(
    tissue="blood",
    cell_types=["T cell", "B cell", "natural killer cell", "monocyte"],
    batch_size=256
)

for batch in dataloader:
    # batch["X"] 是 count 矩阵 (batch_size, n_genes)
    # batch["cell_type"] 等是元数据
    expressionevent-blocked= batch["X"]  # torch.Tensor, shape (256, ~20000)
    print(f"Batch shape: {expressions.shape}")
    break

§6.2 scGPT 预训练数据准备

"""
从 CELLxGENE Census 准备 scGPT 预训练数据
scGPT 使用 value binning tokenization: 基因 ID token + 表达值 binned token
"""
import cellxgene_census
import numpy as np
import scanpy as sc
from collections import Counter

def prepare_scgpt_pretraining_data(
    census_version="stable",
    target_cells=33_000_000,  # scGPT 原始预训练规模
    min_genes_per_cell=200,
    max_genes_per_cell=6000,
    min_cells_per_gene=10
):
    """准备 scGPT 格式预训练数据"""
    with cellxgene_census.open_soma(census_version=census_version) as census:
        human = census["census_data"]["homo_sapiens"]

        # 获取全部人类细胞元数据（仅必要列）
        obs_df = human.obs.read(
            column_names=[
                "soma_joinid", "cell_type", "tissue", "assay",
                "is_primary_data", "donor_id"
            ]
        ).concat().to_pandas()

        # 去重：仅保留 is_primary_data=True 的细胞
        obs_df = obs_df[obs_df["is_primary_data"] == True]
        print(f"去重后细胞数: {len(obs_df):,}")

        # 统计细胞类型分布
        ct_dist = obs_df["cell_type"].value_counts()
        print(f"细胞类型数: {len(ct_dist)}")
        print(f"Top-10 细胞类型:\n{ct_dist.head(10)}")

        # 按比例采样到目标规模
        if len(obs_df) > target_cells:
            # 分层采样保持细胞类型分布
            from sklearn.model_selection import train_test_split
            sampled, _ = train_test_split(
                obs_df, train_size=target_cells,
                stratify=obs_df["cell_type"],
                random_state=42
            )
            obs_df = sampled

        print(f"最终预训练细胞数: {len(obs_df):,}")

        # 分批获取 Count 矩阵并进行 scGPT tokenization
        batch_size = 100_000
        all_tokenized = []

        for start in range(0, len(obs_df), batch_size):
            end = min(start + batch_size, len(obs_df))
            batch_ids = obs_df["soma_joinid"].iloc[start:end].values

            # 读取该批次的 Count 矩阵
            adata = cellxgene_census.get_anndata(
                census,
                organism="homo_sapiens",
                obs_coordinates=batch_ids,
                column_names={"obs": ["cell_type"]}
            )

            # 质控过滤
            sc.pp.filter_cells(adata, min_genes=min_genes_per_cell)
            sc.pp.filter_genes(adata, min_cells=min_cells_per_gene)

            # scGPT value binning: 将连续表达值离散化为 b bins
            # scGPT 原论文使用 52 个 bin
            n_bins = 52
            X = adata.X.toarray() if hasattr(adata.X, ''''''''''''''''toarray'''''''''''''''') else adata.X

            # 对数归一化后分箱
            lib_sizes = X.sum(axis=1, keepdims=True)
            lib_sizes[lib_sizes == 0] = 1
            normalized = np.log1p(X / lib_sizes * 1e4)

            # 分位数分箱
            bins = np.quantile(normalized[normalized > 0], np.linspace(0, 1, n_bins + 1))
            tokenized = np.digitize(normalized, bins[1:-1])

            all_tokenized.append(tokenized)

            if start % 1_000_000 == 0:
                print(f"  已处理 {start:,} / {len(obs_df):,} 细胞")

        return all_tokenized, obs_df

# 运行
tokenized_data, metadata = prepare_scgpt_pretraining_data()
print(f"\nscGPT 预训练数据准备完成")
print(f"Tokenized 矩阵数: {len(tokenized_data)}")

§6.3 Geneformer 嵌入提取与零样本分析

"""
Geneformer 嵌入提取
Geneformer 使用 rank-based tokenization: 基因按表达水平排序（相对中位数）
"""
# pip install geneformer transformers torch

import cellxgene_census
import numpy as np
import torch
from transformers import AutoModel, AutoTokenizer
from geneformer import TranscriptomeTokenizer

def extract_geneformer_embeddings(
    tissue="heart",
    n_cells=10000,
    model_name="ctheodoris/Geneformer/geneformer-12L-30M"
):
    """从 Census 获取数据并用 Geneformer 提取嵌入"""
    # 第 1 步：从 Census 获取数据
    with cellxgene_census.open_soma() as census:
        adata = cellxgene_census.get_anndata(
            census,
            organism="homo_sapiens",
            obs_value_filter=f"tissue == ''''''''''''''''{tissue}''''''''''''''''",
            column_names={
                "obs": ["cell_type", "tissue", "disease"]
            }
        )

    print(f"获取 {adata.n_obs} 细胞, {adata.n_vars} 基因")

    # 第 2 步：Geneformer rank-based tokenization
    # 对每个细胞，将基因按表达量排序（相对全语料中位数）
    # Geneformer V2 输入长度 = 4096 genes/cell
    tokenizer = TranscriptomeTokenizer({
        "gene_id": "ensembl",
        "gene_name": "symbol",
        "count": "count"
    })

    # 计算 rank encoding
    X = adata.X.toarray() if hasattr(adata.X, ''''''''''''''''toarray'''''''''''''''') else adata.X

    # 基因级中位数（跨所有细胞）
    gene_medians = np.median(X[X > 0], axis=0)
    gene_medians[np.isnan(gene_medians)] = 0

    # 每个细胞：rank = 表达量 / 中位数，取 top-4096
    tokenized_cells = []
    for i in range(min(len(adata), n_cells)):
        x = X[i]
        # 排序基因 by 表达量/中位数比值
        ratios = np.where(gene_medians > 0, x / gene_medians, 0)
        top_indices = np.argsort(ratios)[::-1][:4096]
        # Geneformer 格式: [CLS] gene_1 gene_2 ... [EOS]
        tokens = ["[CLS]"] + [f"ENSG{idx:011d}" for idx in top_indices] + ["[EOS]"]
        tokenized_cells.append(tokens)

    # 第 3 步：加载 Geneformer 模型并提取嵌入
    model = AutoModel.from_pretrained(model_name)
    model.eval()

    embeddings = []
    with torch.no_grad():
        for tokens in tokenized_cells[:n_cells]:
            # 获取 [CLS] token 的最后隐藏层作为细胞嵌入
            inputs = AutoTokenizer.from_pretrained(model_name)(
                tokens, return_tensors="pt", padding=True, truncation=True
            )
            outputs = model(**inputs)
            cls_embedding = outputs.last_hidden_state[:, 0, :]  # [CLS] token
            embeddings.append(cls_embedding.squeeze().numpy())

    embeddings = np.array(embeddings)
    print(f"Geneformer 嵌入: {embeddings.shape}")  # (n_cells, 512)

    return embeddings, adata.obs

embeddings, obs = extract_geneformer_embeddings(tissue="heart")

§6.4 TranscriptFormer 推理与细胞类型注释

"""
TranscriptFormer (CZI 自研) 推理
直接使用 Census 内置的 tf-sapiens 嵌入进行细胞类型注释
"""
import cellxgene_census
import numpy as np
from sklearn.neighbors import KNeighborsClassifier
from sklearn.model_selection import cross_val_score

def transcriptformer_cell_annotation(
    query_tissue="blood",
    n_reference_cells=50000,
    n_folds=5
):
    """使用 Census 内置 TranscriptFormer 嵌入进行细胞类型注释"""
    with cellxgene_census.open_soma() as census:
        # 获取带有 TF 嵌入的数据
        adata = cellxgene_census.get_anndata(
            census,
            organism="homo_sapiens",
            obs_value_filter=f"tissue == ''''''''''''''''{query_tissue}''''''''''''''''",
            obs_embeddings=["tf-sapiens"],
            column_names={"obs": ["cell_type"]}
        )

    # 过滤细胞数 > 100 的类型
    ct_counts = adata.obs["cell_type"].value_counts()
    valid_types = ct_counts[ct_counts >= 100].index
    mask = adata.obs["cell_type"].isin(valid_types)
    adata = adata[mask].copy()

    print(f"参考数据: {adata.n_obs} 细胞, {len(valid_types)} 细胞类型")
    print(f"TF 嵌入维度: {adata.obsm[''''''''''''''''tf-sapiens''''''''''''''''].shape}")

    # 采样到参考规模
    if adata.n_obs > n_reference_cells:
        sc.pp.subsample(adata, n_obs=n_reference_cells)

    X = adata.obsm["tf-sapiens"]
    y = adata.obs["cell_type"].values

    # KNN 分类器（TF 嵌入空间中最近邻）
    knn = KNeighborsClassifier(n_neighbors=15, metric="cosine")

    # 5 折交叉验证
    scores = cross_val_score(knn, X, y, cv=n_folds, scoring="f1_macro")
    print(f"\nKNN (k=15) 5-fold CV F1-macro: {scores.mean():.4f} ± {scores.std():.4f}")

    # 在全部参考数据上训练
    knn.fit(X, y)

    # 预测新细胞
    # new_embeddings = ... (新数据的 TF 嵌入)
    # predictionevent-blocked= knn.predict(new_embeddings)

    return knn, adata

classifier, ref_data = transcriptformer_cell_annotation("blood", 50000)

§6.5 scVI 批次校正与数据整合

"""
scVI 批次校正：使用 Census 内置 scVI 嵌入进行跨数据集整合
"""
# pip install scvi-tools scanpy

import cellxgene_census
import scanpy as sc
import scvi
import numpy as np

def scvi_batch_correction(
    tissue="lung",
    min_cells_per_dataset=500
):
    """使用 scVI 进行跨数据集批次校正"""
    with cellxgene_census.open_soma() as census:
        adata = cellxgene_census.get_anndata(
            census,
            organism="homo_sapiens",
            obs_value_filter=f"tissue == ''''''''''''''''{tissue}''''''''''''''''",
            obs_embeddings=["scvi"],  # Census 预计算 scVI
            column_names={"obs": ["cell_type", "dataset_id", "assay", "donor_id"]}
        )

    # 过滤小数据集
    ds_counts = adata.obs["dataset_id"].value_counts()
    valid_ds = ds_counts[ds_counts >= min_cells_per_dataset].index
    adata = adata[adata.obs["dataset_id"].isin(valid_ds)].copy()

    print(f"整合数据: {adata.n_obs} 细胞, {len(valid_ds)} 数据集")
    print(f"批次来源: {adata.obs[''''''''''''''''dataset_id''''''''''''''''].nunique()} 个数据集")

    # 方法 1：直接使用 Census 预计算的 scVI 嵌入
    # 无需训练，直接用于下游分析
    scvi_emb = adata.obsm["scvi"]
    print(f"Census 预计算 scVI 嵌入: {scvi_emb.shape}")

    # UMAP 可视化
    sc.pp.neighbors(adata, use_rep="scvi")
    sc.tl.umap(adata)
    sc.pl.umap(adata, color=["cell_type", "dataset_id"], wspace=0.4)

    # 方法 2：自定义 scVI 训练（如需特定批次变量）
    # scvi.model.SCVI.setup_anndata(
    #     adata,
    #     layer=None,  # 使用 .X (raw count)
    #     batch_key="dataset_id",
    #     categorical_covariate_keys=["assay"],
    # )
    # model = scvi.model.SCVI(adata, n_latent=30, n_layers=2)
    # model.train(max_epochs=400, early_stopping=True)
    # adata.obsm["X_scVI_custom"] = model.get_latent_representation()

    return adata

adata_integrated = scvi_batch_correction("lung")

§6.6 扰动响应预测

"""
使用 Census 预训练的单细胞基础模型预测基因扰动响应
基于 scGPT 的 perturbation prediction pipeline
"""
# pip install scgpt torch scanpy

import torch
import numpy as np
import scanpy as sc
from scipy.stats import pearsonr

def perturbation_prediction_example():
    """
    预测基因敲除后的转录组变化
    使用 Norman et al. 2019 扰动数据集作为示例
    """
    # 加载预训练 scGPT 模型
    from scgpt.model import TransformerModel
    from scgpt.token import tokenize_and_pad_batch
    from scgpt.preprocess import Preprocessor

    # 第 1 步：加载扰动数据（示例：Norman 2019）
    # 实际数据从 https://dataverse.harvard.edu/api/access/datafile/6154020 下载
    # adata = sc.read_h5ad("norman_2019.h5ad")
    # 包含：control cells + perturbed cells (gene knockouts)

    # 第 2 步：使用 Census 预训练的 scGPT
    # 模型配置（与 Nature Methods 2024 论文一致）
    model_conevent-blocked= {
        "embsize": 512,       # 嵌入维度
        "nheads": 8,          # 注意力头数
        "nlayers": 12,        # Transformer 层数
        "vocab_size": 60697,  # 基因词汇表大小
        "n_bins": 52,         # 表达值分箱数
        "dropout": 0.0,
        "pad_token": "<pad>",
        "max_seq_len": 4096   # 最大基因数/细胞
    }

    # 第 3 步：扰动预测逻辑
    # 1. 取 control cell 的 tokenized 表达谱
    # 2. 将目标基因的 token 替换为 "knockout" token (表达值=0)
    # 3. 通过 scGPT forward pass 预测扰动后的表达谱
    # 4. 计算 predicted vs actual 的 delta (变化量)

    # 评估指标
    def evaluate_prediction(pred_delta, true_delta):
        """Pearson delta correlation"""
        r, p = pearsonr(pred_delta.flatten(), true_delta.flatten())
        return r, p

    def top_k_recall(pred_delta, true_delta, k=20):
        """Top-K differentially expressed genes recall"""
        pred_top = set(np.argsort(np.abs(pred_delta))[-k:])
        true_top = set(np.argsort(np.abs(true_delta))[-k:])
        recall = len(pred_top &amp; true_top) / k
        return recall

    # scGPT 论文报告的 Norman 数据集结果:
    # - Pearson delta correlation: ~0.85 (top 20 DEGs)
    # - Top-20 recall: ~0.65
    print("scGPT 扰动预测评估指标:")
    print("  Norman 2019 dataset:")
    print("    Pearson delta r (DEG): ~0.85")
    print("    Top-20 recall: ~0.65")
    print("  Adamson 2016 dataset:")
    print("    Pearson delta r (DEG): ~0.75")
    print("    Top-20 recall: ~0.55")

perturbation_prediction_example()

§6.7 跨物种细胞类型比较

"""
跨物种细胞类型比较：利用 Census 多物种数据
"""
import cellxgene_census
import scanpy as sc
import numpy as np

def cross_species_comparison(
    tissue="brain",
    species=["homo_sapiens", "mus_musculus", "macaca_mulatta"]
):
    """跨物种细胞类型比较分析"""
    all_embeddings = {}
    all_metadata = {}

    with cellxgene_census.open_soma() as census:
        for organism in species:
            print(f"\n- {organism} -")
            adata = cellxgene_census.get_anndata(
                census,
                organism=organism,
                obs_value_filter=f"tissue_general == ''''''''''''''''{tissue}''''''''''''''''" if organism == "homo_sapiens"
                                else f"tissue == ''''''''''''''''{tissue}''''''''''''''''",
                obs_embeddings=["scvi"],
                column_names={"obs": ["cell_type", "tissue"]}
            )

            # 仅保留常见细胞类型
            ct_counts = adata.obs["cell_type"].value_counts()
            commonevent-blocked= ct_counts[ct_counts >= 100].index
            adata = adata[adata.obs["cell_type"].isin(common_types)].copy()

            print(f"  细胞数: {adata.n_obs}")
            print(f"  细胞类型数: {len(common_types)}")
            print(f"  scVI 嵌入: {adata.obsm[''''''''''''''''scvi''''''''''''''''].shape}")

            all_embeddings[organism] = adata.obsm["scvi"]
            all_metadata[organism] = adata.obs

    # 跨物种比较：
    # 1. 使用 TranscriptFormer 的跨物种嵌入（tf-sapiens）
    #    TF 在 12 物种 112M 细胞上训练，天然支持跨物种比较
    # 2. 使用直系同源基因 (one-to-one orthologs) 限制基因集后重新计算 scVI
    # 3. 使用 MNN (Mutual Nearest Neighbors) 进行物种间对齐

    # 细胞类型保守性分析
    for ct in ["neuron", "astrocyte", "microglial cell", "oligodendrocyte"]:
        counts = {}
        for org in species:
            if ct in all_metadata[org]["cell_type"].values:
                counts[org] = (all_metadata[org]["cell_type"] == ct).sum()
        if len(counts) > 1:
            print(f"\n{ct}: {counts}")

cross_species_comparison("brain")

§6.8 计算资源需求

任务	CPU	内存	GPU	存储	预计时间
Census API 子集查询 (<1M 细胞)	4 核	16 GB	无	10 GB	<5 分钟
Census 全量 obs 元数据读取	8 核	32 GB	无	5 GB	~10 分钟
scGPT 微调 (<100K 细胞)	8 核	64 GB	1× A100 40GB	20 GB	2-4 小时
Geneformer 推理 (<10K 细胞)	4 核	32 GB	1× V100 16GB	5 GB	<30 分钟
scVI 自定义训练 (<1M 细胞)	8 核	64 GB	1× A100 40GB	50 GB	4-12 小时
全量 Census 下载 (S3)	4 核	8 GB	无	500 GB+	2-6 小时
TranscriptFormer 嵌入推理 (1M 细胞)	16 核	128 GB	4× A100 80GB	100 GB	6-12 小时

§7 已知坑点

§7.1 is_primary_data 去重陷阱

问题：Census 中同一细胞可能出现在多个数据集中（如同一研究的数据被多个 Collection 收录）。is_primary_data 字段标识该数据集是否为该细胞的"首次发布"来源。如果不加过滤地使用所有数据，会导致重复细胞污染训练集。

解决方案：

# 始终过滤 is_primary_data=True
adata = cellxgene_census.get_anndata(
    census,
    organism="homo_sapiens",
    obs_value_filter="is_primary_data == True and tissue == ''''''''''''''''blood''''''''''''''''"
)

§7.2 批次效应——数据集间系统性差异

问题：不同数据集来自不同实验室、不同 10x 版本、不同解离方案、不同测序深度，即使相同组织相同细胞类型，表达谱也可能存在系统差异。直接混合训练会导致模型学习批次特征而非生物学信号。

解决方案：

使用 Census 预计算的 scVI 嵌入（已做批次校正）
在自定义训练中加入 batch covariate（如 dataset_id）
使用 scVI/scANVI 进行显式批次建模
评估时使用留一数据集 (leave-one-dataset-out) 验证

§7.3 基因 ID 版本同步问题

问题：Census 使用 Ensembl Gene ID 作为基因主键，但 Ensembl 参考基因组版本会定期更新。不同 Census 版本可能使用不同 Ensembl 版本，导致同一基因 ID 在不同版本间不兼容。

解决方案：

固定使用特定 Census LTS 版本（如 census_version="2025-11-08"）
使用 featuremappings 子集进行跨版本基因 ID 映射
始终使用 Ensembl ID（而非 Gene Symbol）作为基因标识

§7.4 Schema 版本间的不兼容变更

问题：Census Schema 持续演进，某些变更可能破坏现有分析代码：

Schema 7.0: disease 字段可包含多值（"normal || MONDO:0005061"），使用精确字符串匹配 (disease == ''''''''''''''''normal'''''''''''''''') 的查询会遗漏多值细胞
Schema 7.0: feature_name 不再保证唯一，同一名（如 MARCH1）可能对应多个 Ensembl ID
Schema 6.0: 新增 suspension_type 字段，旧代码可能未处理

解决方案：

查询 disease 时使用 disease_ontology_term_id 而非 disease 文本字段
使用 feature_id (Ensembl ID) 而非 feature_name 作为基因标识
检查 Census schema 版本并适配代码

§7.5 物种和组织的覆盖偏倚

问题：Census 数据覆盖存在系统性偏倚：

物种偏倚：人类占 74.5%、小鼠 21.3%、其他灵长类仅 4.2%
组织偏倚：血液/免疫 (~25%)、脑 (~20%)、肿瘤 (~15%) 过度代表；皮肤、骨骼肌、内分泌组织覆盖不足
疾病偏倚：正常组织占多数 (~60%)；罕见病数据稀缺
种族偏倚：欧洲裔供体过代表 (~55%)，非洲、亚洲、南美裔代表性不足

影响：在此数据上预训练的基础模型可能对低代表组织/种族的细胞类型注释性能较差。

§7.6 测序技术差异导致的 assay bias

问题：~80% 的细胞来自 10x Chromium 平台。Smart-seq2 数据（全长转录组、更高基因检出率但通量低）和其他平台数据在 Census 中比例很小。不同 assay 间的基因检出率、dropout 模式、UMI vs read count 差异巨大。

解决方案：

训练基础模型时考虑 assay 作为批次协变量
使用 assay 字段进行分层采样
评估模型在低代表 assay（如 Smart-seq2）上的泛化性

§7.7 Census “latest” vs “stable” 的版本混淆

问题：

census_version="stable"：最新 LTS 版本（当前 2025-11-08），保证 5 年可访问
census_version="latest"：每周更新版本，仅保留 1 个月

如果使用 “latest” 进行预训练，一周后数据可能已变化，无法复现。

解决方案：

预训练和发表论文时始终使用 LTS 版本（如 census_version="2025-11-08"）
在论文中记录具体 Census 版本号
仅在探索性分析时使用 “latest”

§7.8 细胞类型注释的粒度不一致

问题：不同数据集的原始细胞类型注释粒度差异巨大：

数据集 A: "T cell" (粗粒度)
数据集 B: "CD4-positive alpha-beta T cell, regulatory" (细粒度)
Lattice 策展映射到 CL 时可能统一到较粗粒度，丢失细粒度信息

解决方案：

同时查看 cell_type（标准化）和 author_cell_type（原始标注）
使用 CL 本体论的层级关系进行粒度调整
对需要细粒度的分析，手动审查 author_cell_type 字段

§7.9 空间转录组数据的局限性

问题：Census 中的空间数据（Visium、Slide-seq）存在特殊问题：

Visium spot 可能包含多个细胞（不是真正的单细胞）
空间坐标的坐标系不统一（不同实验使用不同的坐标系原点和缩放）
空间数据的稀疏度更高（Dropout 更严重）

解决方案：

使用 suspension_type 字段区分 true single-cell 和 spot
空间数据分析时始终检查 assay 字段
使用专门的空间分析方法（如 Squidpy、SpatialData）

§7.10 供体去标识化与隐私

问题：Census 数据经过去标识化处理，但 scRNA-seq 数据本身具有可识别性——每个细胞的基因型（尤其 HLA 区域、性染色体、线粒体单倍型）可用于个体识别。在大规模数据合并时，理论上可能通过基因型匹配重新识别供体。

解决方案：

CZI 已对供体 ID 进行不可逆哈希处理
不提供原始 FASTQ 数据（仅 Count 矩阵）
遵循 IRB 审批和知情同意要求
用户不应尝试跨数据集进行供体重识别

§7.11 "正常"组织的定义模糊

问题：Census 中 disease == "normal" 的组织来自多种来源：健康供体活检、手术切除的癌旁组织、器官移植供体等。这些来源的组织在转录组上可能存在差异（如癌旁组织可能受肿瘤微环境影响）。

解决方案：

分析正常组织时同时检查 dataset_id 和原始论文来源
考虑使用 donor_id 作为协变量
对异常结果进行来源溯源验证

§8 基准与生态

§8.1 单细胞数据平台横向对比

维度	CELLxGENE	GEO	Single Cell Portal	HCA Data Portal	10x Cell Atlas
数据规模	217M 细胞	不限（原始数据）	~10M 细胞	~50M 细胞	10x 内部
标准化	强制 ONTOLOGY	无标准化	部分	部分标准化	10x 格式
数据格式	TileDB-SOMA / H5AD	FASTQ/BAM/MTX	H5AD	H5AD/MTX	10x MTX
API	Python/R + S3	FTP/HTTP	REST	REST	无
可视化	WebGL 交互	无	Web UMAP	Web 可视化	Loupe Browser
许可	CC BY 4.0	各异	各异	混合	商业
AI 训练	✅ Census API	❌ 需自行处理	❌	部分	❌
策展	Lattice 人工策展	无	提交者自策展	HCA 策展	10x 内部
版本管理	LTS + weekly	无	无	版本化	无
多物种	5 种灵长类	不限	人类为主	人类为主	人类/小鼠
空间数据	✅ (Visium/Slide-seq)	✅	❌	部分	✅

§8.2 单细胞基础模型性能对比

模型	预训练数据	参数量	细胞注释 F1	批次整合 (AvgBIO)	扰动预测 (ΔPearson)	发表期刊
scGPT	33M (Census)	~50M	0.92	0.68	0.85	Nature Methods 2024
Geneformer V1	30M	~30M	0.88	0.61	0.72	Nature 2023
Geneformer V2	104M (Census)	~100M	0.93	0.70	0.80	bioRxiv 2025
UCE	36M (Census)	650M	0.90	0.65	—	bioRxiv 2023
CellFM	>100M	800M	0.91	0.67	—	Nature Comms 2025
TranscriptFormer	112M/12物种	~300M	0.94	0.72	—	bioRxiv 2025
scPRINT	50M (Census)	~100M	0.89	0.64	—	bioRxiv 2024
AIDO.Cell	100M+ (Census)	~1B	0.93	0.71	—	arXiv 2025
scVI (基线)	各自训练	~1M	0.85	0.63	—	Nature Methods 2018
Random Forest (基线)	—	—	0.72	—	—	—

注意：上述数字为各论文自报的最佳结果，任务和数据集不同，不可直接横向比较。2025 年 Theis Lab 发表的系统基准测试 (Nature Methods) 表明，预训练数据规模和多样性的增加对模型性能提升有限，预训练数据质量比规模更重要。

§8.3 scGPT vs Geneformer 架构对比

维度	scGPT	Geneformer
Tokenization	Value binning (52 bins)	Rank encoding (genes sorted by expression/median)
输入格式	(gene_id, binned_value) pairs	Ranked gene ID sequence
位置编码	无（基因无序）	隐含在排名顺序中
预训练目标	Masked gene modeling (MSE loss)	Masked language modeling (CE loss)
架构	Transformer encoder	BERT-style encoder
嵌入维度	512	512 (V1) / 768 (V2)
层数	12	12 (V1) / 24 (V2)
注意力头	8	8 (V1) / 12 (V2)
输入长度	可变 (所有基因)	4096 genes/cell
多组学	✅ (ATAC + RNA)	❌ (仅 RNA)
多物种	❌ (仅人类)	✅ (V2 多物种)
优势	表达值保留；多组学	对 dropout 鲁棒；规模更大
劣势	对噪声敏感	丢失绝对表达量信息

§8.4 TranscriptFormer——CZI 自研模型

TranscriptFormer 是 CZI 于 2025 年发布的单细胞基础模型，与 Census 深度集成：

属性	值
预训练数据	1.12 亿细胞，12 个物种
参数量	~300M
架构	Encoder-decoder Transformer
输入	基因 ID + 表达值（类似 scGPT）
输出	基因表达预测（生成式）
嵌入	256 维（内置 Census）
物种	人类、小鼠、猕猴、绒猴、黑猩猩、大鼠、斑马鱼、果蝇、线虫等 12 种
代码	github.com/czi-cellgenomics/transcriptformer
Census 集成	tf-sapiens (物种特异) + tf-exemplar (参考映射)

核心创新：

多物种预训练：首次在 12 个物种上联合预训练，学习跨物种保守的细胞状态表示
生成式解码器：可生成虚拟细胞（in silico cell generation），用于数据增强和假设验证
Census 原生集成：嵌入预计算并内置在 Census 中，用户无需自行推理

§8.5 CELLxGENE 在单细胞 AI 生态中的角色

CELLxGENE Census 在单细胞 AI 生态中扮演类似 ImageNet 在计算机视觉中的角色——一个大规模、标准化、公开可用的预训练数据基准：

类比维度	ImageNet (CV)	CELLxGENE Census (scRNA-seq)
数据规模	1.28M 图像	217M 细胞
类别数	1,000 类	898 种细胞类型
标注质量	人工标注	Lattice + ONTOLOGY 策展
许可	研究用途	CC BY 4.0 (商业可用)
预训练模型	ResNet/ViT/CLIP	scGPT/Geneformer/UCE/TF
下游任务	检测/分割/生成	注释/整合/扰动/生成
基准测试	ImageNet-C/A/R	scIB/Perturbation benchmarks
版本管理	静态	LTS + weekly

§8.6 Billion Cells Project

2025 年 2 月，CZI 启动了 Billion Cells Project，这是单细胞生物学领域迄今最大规模的数据生成计划：

维度	详情
目标	首年生成近 5 亿细胞（当前 2.17 亿 → 7 亿+）
投资	CZI 投入 $2.5 亿
技术	10x Chromium X / Xenium / 新兴单细胞平台
组织重点	补充当前覆盖不足的组织（皮肤、肌肉、内分泌、消化系统）
物种	扩展非人灵长类和模式动物
疾病	增加罕见病和肿瘤亚型覆盖
AI 集成	数据生成与 AI 模型训练同步推进
时间表	2025.02 启动，2026 年底首阶段完成

对 AI 的影响：5 亿+ 细胞的预训练数据将使单细胞基础模型的规模从当前的 ~1B 参数扩展到 ~10B+ 参数，接近 LLM 的规模。

§8.7 关键科学发现案例

CELLxGENE 数据已直接支撑多项重要科学发现：

发现	数据来源	期刊	年份	影响
Tabula Sapiens——首张全组织人类细胞图谱	Tabula Sapiens dataset (Census)	Science	2022	24 组织、~500K 细胞、400+ 细胞类型
COVID-19 免疫图谱	多中心 COVID 单细胞研究 (Census)	Nature Medicine	2021	揭示重症 COVID 的免疫失调机制
肠道细胞图谱	Gut Cell Atlas (Census)	Nature	2021	发现新的肠内分泌细胞亚型
肺纤维化细胞图谱	肺纤维化 scRNA-seq (Census)	Science Advances	2022	识别病理性成纤维细胞亚群
跨物种神经元保守性	人类+小鼠+猕猴脑数据 (Census)	Nature	2023	跨物种细胞类型进化分析
scGPT 基础模型	33M Census 细胞	Nature Methods	2024	首个大规模单细胞基础模型
Geneformer 疾病基因发现	30M Census 细胞	Nature	2023	心肌病候选治疗靶点

§8.8 社区与生态工具

工具	类型	与 CELLxGENE 的关系
Scanpy	Python scRNA-seq 分析	Census 数据直接加载为 AnnData
Seurat	R scRNA-seq 分析	通过 Census R API 获取数据
scVI/scANVI	深度学习整合	Census 预计算 scVI 嵌入
CellTypist	自动细胞类型注释	使用 CL 本体论（与 Census 一致）
Squidpy	空间转录组分析	兼容 Census 空间数据
Celligner	细胞系-肿瘤对齐	部分使用 Census 参考
CellxGene Annotate	交互式标注工具	CELLxGENE 组件之一
TileDB-SOMA	存储引擎	Census 底层技术
bio_embeddings	蛋白质嵌入	可与 Census 嵌入联合分析

§9 资源索引

§9.1 核心论文

论文	期刊	年份	DOI
CZ CELLxGENE Discover preprint	bioRxiv	2023	10.1101/2023.10.30.563174
scGPT: foundation model for single-cell	Nature Methods	2024	10.1038/s41592-024-02201-0
Geneformer V1	Nature	2023	10.1038/s41586-023-06139-9
UCE (Universal Cell Embeddings)	bioRxiv	2023	10.1101/2023.11.28.568918
CellFM	Nature Communications	2025	—
TranscriptFormer	bioRxiv	2025	—
scPRINT	bioRxiv	2024	—
Tabula Sapiens	Science	2022	10.1126/science.abl4896
scVI	Nature Methods	2018	10.1038/s41592-018-0229-2
预训练数据规模评估	Nature Methods	2025	10.1038/s41592-026-03120-y

§9.2 官方资源

资源	URL
Discover 门户	https://cellxgene.cziscience.com/
Census 文档	https://chanzuckerberg.github.io/cellxgene-census/
Census Python API	`pip install cellxgene-census`
Census R API	`install.packages("cellxgene.census")`
Census AWS S3	`s3://cellxgene-census-public-us-west-2/`
GitHub (Census)	https://github.com/chanzuckerberg/cellxgene-census
GitHub (Annotate)	https://github.com/chanzuckerberg/cellxgene
Census 数据发布	https://chanzuckerberg.github.io/cellxgene-census/cellxgene_census_docsite_data_release_info.html
Virtual Cell Models	https://virtualcellmodels.cziscience.com/
Schema 文档	https://github.com/chanzuckerberg/single-cell-curation/blob/main/schema/5.0.0/schema.md
Billion Cells Project	https://chanzuckerberg.com/science/programs-resources/single-cell-biology/

§9.3 模型与代码

模型	GitHub / HuggingFace
scGPT	github.com/bowang-lab/scGPT
Geneformer	huggingface.co/ctheodoris/Geneformer
UCE	github.com/snap-stanford/UCE
CellFM	github.com/PharMolix-Lab/CellFM
TranscriptFormer	github.com/czi-cellgenomics/transcriptformer
scPRINT	github.com/czi-cellgenomics/scPRINT
scVI	github.com/scvi-tools/scvi-tools
AIDO.Cell	github.com/genomoncology/aido

§9.4 外部关联资源

资源	URL
Human Cell Atlas	https://www.humancellatlas.org/
GEO (Gene Expression Omnibus)	https://www.ncbi.nlm.nih.gov/geo/
Single Cell Portal	https://singlecell.broadinstitute.org/
Allen Brain Cell Atlas	https://alleninstitute.org/division/brain-science/
CZ Biohub	https://www.czbiohub.org/
OBO Foundry (Ontologies)	http://obofoundry.org/
Cell Ontology	https://www.ebi.ac.uk/ols/ontologies/cl
UBERON	https://www.ebi.ac.uk/ols/ontologies/uberon
MONDO	https://www.ebi.ac.uk/ols/ontologies/mondo
EFO	https://www.ebi.ac.uk/ols/ontologies/efo

§10 数据集声明卡

属性	值
数据集名称	CZ CELLxGENE Discover Census
当前版本	Census LTS 2025-11-08
Schema 版本	Census 2.4.0 / Dataset 7.0.0
总细胞数	217,767,936 (2.17 亿)
人类细胞	162,025,130 (1.62 亿)
小鼠细胞	46,299,127 (4,630 万)
数据集数	1,845
细胞类型	898 种 (人类)
组织覆盖	417 种 (人类)
Assay 类型	37 种 (人类)
物种	人类、小鼠、猕猴、绒猴、黑猩猩
数据格式	H5AD (AnnData) / TileDB-SOMA
存储引擎	TileDB-SOMA (列式稀疏数组)
许可	CC BY 4.0
维护方	Chan Zuckerberg Initiative (CZI)
策展方	Lattice Curation Team (Stanford)
核心论文	bioRxiv 2023.10.30.563174
DOI	10.1101/2023.10.30.563174
数据下载	AWS S3 (免签名) / Census API
预计算嵌入	scVI (30D) / TranscriptFormer (256D)
AI 模型	scGPT / Geneformer / UCE / CellFM / TF / scPRINT / AIDO.Cell
下一里程碑	Billion Cells Project (目标 5 亿+/年)
DAIMS 评分	17.0/24

返回 AI Ready 数据集