信息速览
一维基因组上写着两段相距很远的 DNA 序列，测序报告里它们毫不相干，而在细胞核里它们可能正贴在一起。这个差别足以让一整类基于线性距离的分析全部失效：增强子找靶基因时按最近的基因猜、变异解读时按上下游若干碱基内找注释、机器学习时把基因组当成一条长字符串做卷积——这些默认「近即是相关」的做法，在真实的三维折叠面前会系统性地出错。
3D Genome Browser 做的事情，是把「哪段 DNA 和哪段 DNA 在物理上接触」这件事，从一篇论文里的一张彩色热图，变成可以按基因组坐标查询的普通注释。你给它一个区间，它返回这个区间与其它区间之间的接触强度，以及在这套数据上已经算好的区室、拓扑结构域和染色质环。它由 Feng Yue 实验室（现于宾夕法尼亚州立大学与西北大学）维护，2018 年首发，2026 年发布 2.0 版，收录八百余套已发表的染色质构象捕获数据集，人类数据占绝大多数，全站免费开放。一屏速览见下表。
| 维度 | 内容 |
|---|---|
| 中文名 | 三维基因组浏览器 |
| 英文名 | 3D Genome Browser（2.0 版） |
| 维护方 | Feng Yue 实验室，宾州州立大学与西北大学范伯格医学院 |
| 首发年份 | 2018（Genome Biology） |
| 现役版本论文 | NAR 2026，DOI 10.1093/nar/gkaf1109 |
| 当前入口 | https://3dgenome.fsm.northwestern.edu |
| 旧入口 | http://3dgenome.org（现 302 跳转至新域名） |
| 数据集规模 | 823 套（清单接口返回条数） |
| 实验类型 | Hi-C、ChIA-PET、HiChIP、Micro-C、scHi-C、Capture Hi-C、MiChIP 七类 |
| 覆盖物种 | 人类、小鼠、大肠杆菌、果蝇、斑马鱼 |
| 基因组版本 | hg38 为人类主力，另有 hg19 与 mm10、dm6、danRer10 |
| 矩阵格式 | .mcool（多分辨率） |
| 注释格式 | TAD 用 bed，loop 用 bedpe，PC1 用 bigwig |
| 访问接口 | 只读 HTTP JSON 接口，无需令牌 |
| 许可 | 免费开放；原始数据授权随来源而定 |
| 适不适合当训练集 | 当特征源可以，当标签源要谨慎 |
§1 它要解决的具体麻烦
1.1 线性坐标是整套基因组分析的公共假设
生物信息学的绝大多数工具都建立在一个安静的假设上：基因组是一条线，位置相近的元件功能相关。这个假设有用，也大部分时候管用——启动子在基因上游几百碱基内，增强子往往也在附近，连锁不平衡让相邻的变异一起遗传。但当分析落到调控层面，假设开始崩。
一个经典的失效场景：你在全基因组关联研究里定位到一个风险位点，落在基因间区，最近的蛋白编码基因在两万碱基之外。按「最近的基因」这条规则，你把靶基因判给了它。而 Hi-C 数据显示，这个位点所在的区段与另一个方向、八十万碱基之外的基因有强接触。两者完全可能都对，也可能其中一个是错的，但只靠线性距离，你没有能力区分。
第二个场景更常见：你把一段基因组序列输入模型，让它预测调控活性，模型学到了「靠近转录起始位点的序列更像启动子」。这个规律本身没错，但它漏掉了另一类真实存在的调控关系——远端增强子通过三维折叠靠近启动子。模型在训练集上表现很好，一换细胞类型就掉点，因为每个细胞类型的三维结构不一样，而线性模型看不见这层信息。
第三个场景出现在统计检验上。你有一批变异，想检验它们是否落在调控元件里富集，于是把每个变异映射到最近的基因，再检验这些基因是否有共同功能。整个流程里有一个没被说出来的假设：调控的作用对象就是最近的那个基因。三维数据在相当多的位点上否定这个假设，而被否定的那些位点，恰恰是最需要解释的非编码变异。
三次失效指向的是同一件事：一维坐标系把「相邻」当成了唯一的关系。而基因组在核内被折叠之后，多出了一层关系——靠近但不相邻，以及相邻但不靠近。
3D Genome Browser 针对的正是这一类麻烦。它不产出新的生物学结论，只把已有实验里测量过的三维接触整理成可以按坐标访问的形式——把「物理距离」这一维度补进一维坐标系统。
1.2 三条常见的错误期待
第一次接触这个站点的人，往往会带着三种期待，三种都会落空。
期待一：以为它是一个 Hi-C 矩阵仓库。 数据列表里每条记录有物种、细胞类型、分辨率、文献 DOI，看着像个仓库。点下载，给的是一个压缩包，里面是 bedpe 与 bed。矩阵本体要以坐标片段的方式从换图接口取。这是设计选择不是缺陷——完整的人类全基因组 mcool 动辄几十 GB，逐坐标切片比让你下整包更合理。但如果你本来是来找一批矩阵训练模型的，落差会很大。
期待二：以为三百套与八百套是同一个口径的升级。 2018 年论文写的是三百余套，2026 年论文写的是七百余套，而清单接口现在返回八百多条。三个数字来自三个时点、三种计数方式，不是同一批数据的简单翻倍。引用时必须锁定时点。
期待三：以为浏览器已经把数据清洗好了。 格式是被统一了，都转成了 mcool。但归一化方法没有统一，环调用算法没有统一，区室方向没有统一。统一格式不等于统一测量，这是两件事。这条误解的代价往往延迟出现：你的脚本能顺利读入所有文件，跑完也不报错，直到某天发现两个数据集的强度均值差了三四倍，才回头怀疑数据本身。
1.3 它能给到的与给不到的
| 你的需求 | 它给的 | 够不够 |
|---|---|---|
| 知道某个位点在哪些细胞类型里有强接触 | 按坐标取换热图，可选数据集对比 | 够，这是最直接能用的功能 |
| 拿到某套数据的 TAD 边界文件 | bed 格式下载，一条记录一个文件 | 够，但要自己核对算法版本 |
| 拿到某项研究的染色质环清单 | bedpe 格式下载，七列含强度和显著性 | 够，但环调用阈值随数据集不同 |
| 把位点注释到靶基因 | 有「远端元件-靶基因」连接的多条路径 | 部分够，需要你自己挑路径并说明理由 |
| 下载全基因组矩阵做批处理 | 不提供整包矩阵 | 不够，去原始 GEO 取 mcool |
| 找到原始 fastq 重新比对 | 只给 GEO/SRA 编号 | 不够，需要跳出去 |
| 跨数据集比较同一细胞类型的环 | 数据都在，但算法不同 | 勉强够，需要自己做再调用 |
| 得到一份置信度分级的统一注释 | 不提供置信度分级 | 不够，需要你自己加权 |
| 查某个基因的三维结构邻域 | 基因位置检索接口 + 热图 | 够，两跳就能完成 |
| 训练一个跨细胞类型的接触预测模型 | 八百余套矩阵带分辨率标签 | 够用，但要去重与对齐 |
| 得到结构变异后的接触重排 | 2.0 新增结构变异分析模块 | 够，但只覆盖带 SV 列表的少数数据集 |
最值得注意的一行是「把位点注释到靶基因」：浏览器给了材料，但没有替你作判断。哪些接触算证据、多强的算、用哪个分辨率的算，仍是你自己的事。这也是 §4.3 案例要展开的地方。
1.4 你的处境与它能帮到的事
| 你的处境 | 它能帮你什么 | 下一步该做什么 |
|---|---|---|
| 你有一个非编码变异，想找它的靶基因 | 查该位点在多个细胞类型中的接触谱，看谁在物理上靠近 | 先确定你的细胞类型有没有覆盖，再挑分辨率；没有覆盖就换器官相近的数据 |
| 你要为一个新的细胞系补三维结构背景 | 找同类细胞或同器官的数据当代理 | 明确写清是代理数据，不要写成该细胞系的测量 |
| 你在做多组学整合，缺一维结构信息 | 提供 compartment、TAD、loop 三类可对齐的区间文件 | 用同一基因组版本对齐，先做 liftOver 再做区间交叠 |
| 你在审一篇稿子，作者说「我们用了 Hi-C 支持」 | 按作者给的编号回查原始数据集与分辨率 | 核对分辨率是否支撑其结论 |
| 你要做增强子劫持分析 | 2.0 的结构变异模块可视化重排后的接触图 | 先确认该数据集在 SV 列表里 |
| 你要训练一个接触预测模型 | 八百余套矩阵带清晰的物种与分辨率标签 | 按分辨率分层，避免把 1Mb 与 5kb 混进同一批 |
| 你在做临床变异解读 | 可以看已知致病结构变异的案例 | 不要把浏览器的接触强度当致病判据 |
| 你要复现某篇论文的图 | 数据与注释都在，坐标可直接取 | 复现前先确认论文用的分辨率档位 |
1.5 一句话判断
它是一个把「空间邻近」翻译成「坐标区间」的转接层：凡是需要判断「这两段 DNA 有没有关系」的地方都值得查一次，凡是需要「一个确定答案」的地方都不要指望它。
1.6 不适合谁：四条边界
第一条，不适合把浏览器当数据库用的人。 接口围绕「按坐标取一小块」设计，不是「批量拉全表」。流程需要全量扫描的话，它只是入口。
第二条，不适合要求注释有统一金标准的人。 TAD 边界、loop 位置、区室方向，在文献里都没有唯一正确的定义。不同算法在同一份矩阵上能给出不同的边界集合。并列展示是忠实于领域现状，代价是无法提供一份可无条件信任的注释。
第三条，不适合非模式生物。 物种覆盖是五类，但人类与小鼠标占绝大多数，其余三类加起来不到百分之五。研究对象若是猪、牛、鸡、水稻，这里基本找不到数据。
第四条，不适合需要样本级临床信息的人。 记录粒度是细胞系或实验，不是患者。没有任何个体水平的临床终点、用药史、随访结果。问题里带「预后」「疗效」这类词，它帮不上。
§2 数据构成与规格
2.1 三样东西：矩阵、注释、元数据
浏览器的数据分三层，理解这三层的边界比记住字段名更重要。
最底层是接触矩阵。每套数据在磁盘上存成一个 mcool 文件，这是 cooler 生态里的多分辨率容器格式，一个文件里同时装着从粗到细的十来个分辨率层。浏览器不直接暴露 mcool 文件路径，但换图接口每次返回的数值都来自它。
中间层是三级注释。每套数据附带三个文件：拓扑结构域边界（bed 格式，一行一个区间）、染色质环（bedpe 格式，一行一对区间加接触强度）、第一主成分轨迹（bigwig 格式，逐分箱的数值，正负号代表两个区室）。这三个文件构成 §2.3 要解剖的一条记录。
最上层是元数据。每条记录有二十个字段，描述这套数据是谁做的、在什么细胞上、用了什么实验方法、能到多细的分辨率、出自哪篇论文。这层是检索的入口，也是判断「能不能用」的依据。
2.2 字段/记录的完整字典
清单接口返回的每条记录是固定结构的 JSON 对象。下面这张表把二十个字段逐个摊开，包括它们在实际返回里的取值形态。
| 字段 | 含义 | 取值形态 | 实况（清单接口返回） |
|---|---|---|---|
| id | 记录标识，用于拼接口路径 | 整数 | 0 到 822 连续 |
| name | 记录短名，含细胞系与处理条件 | 自由文本 | 如 007-BRD4、A-549 |
| species | 物种 | 英文名 | 人类、小鼠、大肠杆菌、果蝇、斑马鱼 |
| assembly | 基因组版本 | 组装名 | hg38、mm10、dm6、danRer10 |
| organ | 器官 | 自由文本 | Blood、Embryo、Prostate、Brain |
| cellType | 细胞类型 | 自由文本，可空 | 百余条为空 |
| dataType | 实验类型 | 受控枚举，七值 | Hi-C、ChIA-PET、Hi-ChIP、Micro-C、scHi-C、Capture Hi-C、Mi-ChIP |
| description | 散文式描述 | 自由文本 | 多含细胞系与实验协议 |
| verified | 是否已核验 | 布尔 | 全部为真 |
| resolutions | 可用分辨率 | 整数数组，单位碱基 | 常见 5kb 到 2.5Mb，九到十二档 |
| formats | 矩阵格式 | 字符串 | 全部为 .mcool |
| publication | 出处论文标题 | 自由文本 | 必填 |
| authors | 论文作者串 | 自由文本 | 必填 |
| journal 与 year | 期刊与年份 | 缩写与浮点 | 七十余条为空，年份跨度 2009 至 2026 |
| doi | 论文标识 | DOI 串 | 与上一条同为空集 |
| refNo | 原始数据编号 | GEO/SRA/ENA 编号 | 多数为 GSE 系列，其余为 PRJNA、4DNF 等 |
| downloads 与 citations | 下载量与引用数 | 空字符串 | 字段在结构上存在，后台未灌数据 |
| （缺失） | 发育阶段、性别、疾病状态 | 无 | 这些维度在记录里完全不存在 |
字段表里有两处值得单独提一句。第一处是 downloads 与 citations 两个字段，二十条记录里全是空串，说明字段在结构上存在但后台没有数据灌入。第二处是 cellType 有 134 条为空，以及 doi 与 journal 各有 74 条为空——空值集中在少数较新的或来自非 GEO 来源的记录上。
2.3 一条记录的完整解剖
拿清单里编号为零的那条记录当标本，把它的各层剥开看。
{
"id": 0,
"name": "007-BRD4",
"species": "Human",
"assembly": "hg38",
"organ": "Brain",
"cellType": "Glia",
"dataType": "Hi-C",
"description": "Hi-C on diffuse intrinsic pontine glioma line DIPG007, BMS-986158 treated 24 hours (200 nM), performed using in situ Hi-C protocol.",
"verified": true,
"resolutions": [5000, 10000, 20000, 25000, 40000, 50000,
100000, 250000, 500000, 1000000, 2500000, 5000000, 10000000],
"formats": ".mcool",
"publication": "Epigenomic landscape and 3D genome structure in pediatric high-grade glioma",
"journal": "Sci Adv",
"year": 2021,
"doi": "10.1126/sciadv.abg4126",
"refNo": "GSE162976"
}
这段元数据的读法是：名称里的 007 是弥漫性内生型脑桥胶质瘤细胞系 DIPG007 的编号，处理条件是 BET 抑制剂 BMS-986158 处理二十四小时、浓度两百纳摩尔；物种人类、组装 hg38、器官脑、细胞类型胶质；共十三档分辨率，从 5kb 一直到 10Mb；原始数据在 GEO 的 GSE162976 下，出处是二〇二一年《科学进展》上那篇儿童高级别胶质瘤的表观基因组论文。
信息密度取决于你有没有把字段连起来读：name 里的处理条件、description 里的协议、dataType 里的方法、resolutions 里的深度暗示。这条记录名里有 BRD4 字样，描述里写着药物处理，不看描述很容易把它当成携带 BRD4 突变的细胞系，而不是用 BRD4 抑制剂处理过的细胞系。这种命名与内容的张力在记录里普遍存在。
再看换图接口对同一个数据集、给一个两兆碱基见方的窗口返回什么。
curl -s "https://3dgenome.fsm.northwestern.edu/api/data/datasets/0/heatmap?\
x_chrom=chr1&x_start=1000000&x_end=2000000&\
y_chrom=chr1&y_start=1000000&y_end=2000000&\
resolution=10000&lock_resolution=false&normalization=raw&\
display_mode=rectangle&auto_resolution=false" | head -c 400
返回的 JSON 里有一个 shape 字段，值是 [100, 100]，对应的是一百行乘一百列的方阵；还有 x_labels 与 y_labels 两个数组，每个元素形如 chr1:1000000-1010000。也就是说，十千碱基的分辨率把两兆碱基的窗口切成了两百个分箱，两两交叉就是四万个格子。这是坐标层面的真相：分辨率不是抽象参数，它就是格子的宽度。
四万个格子里真正有值的通常只是一小部分。接触矩阵本质稀疏：窗口越小、分辨率越细，绝大多数格子越是零或极小的计数。这不是数据坏了，是测序深度的物理限制——要让每个十千碱基格子都有可靠计数，需要的读数远超绝大多数实验的产出。
这解释了为什么分辨率与窗口是一对互相拉扯的量。窗口固定时，分辨率越细单格计数越少、噪声越大；越粗则越稳但越缺细节。缩放时看到的平滑变化，本质是服务端在替你重新分箱。理解这一点，就不会问出「为什么放大之后全是噪点」。
再往下是注释文件。下载接口按类型返回压缩包，包内只有一个文件，命名规则是「记录名_原始编号.扩展名」。
#-- 下载包内文件名（records/0，类型 all）
007-BRD4_GSE162976.bedpe
#-- bedpe 前若干行，七列
chr10 93370000 93380000 chr10 93480000 93490000 0.98 117.0
chr10 103710000 103720000 chr10 103880000 103890000 0.97 116.0
chr10 97790000 97800000 chr10 97860000 97870000 0.97 111.0
chr10 28660000 28670000 chr10 29300000 29310000 0.98 109.0
七列依次是：锚点一的染色体、起、止，锚点二的染色体、起、止，以及两个数值列。前一个是归一化的接触强度，后一个是某种原始计数值，具体含义随数据集而异——这一点非常重要，后文 §7.3 会回来讲。
这几行数值能读出两件事。一是锚点宽度一万碱基，与这条记录的最低分辨率一致——环的锚点粒度跟着矩阵分辨率走，不会更细。二是强度列挤在零点九几的窄区间，说明前一个数值大概率是最大值归一化后的相对值，而不是绝对接触次数；若它是绝对次数，几百条环不可能这么整齐。这只是从数值形态推出来的判断，不是官方定义，写论文时不能当定义引用。
后一列跨度就大得多，在不同数据集里可能对应读数也可能对应打分，跨数据集拿它排序比较是最没意义的操作之一。
三个注释文件的格式分工在下表里。
| 注释 | 文件格式 | 一行代表 | 关键列 | 方向性 |
|---|---|---|---|---|
| 拓扑结构域 | bed | 一段自接触富集的区间 | 染色体、起、止 | 无方向，区间级 |
| 染色质环 | bedpe | 一对相隔很远的锚点 | 两个锚点坐标 + 两个强度值 | 无方向，对级 |
| 区室轨迹 | bigwig | 一个分箱的 PC1 值 | 分箱坐标 + 数值 | 有正负号，数值级 |
三种注释的「一行」在粒度上差了两个数量级：bed 可能几千行，bedpe 可能几万行，bigwig 是逐分箱连续量。把它们当成同一种区间注释混在一起处理，是最常见的错误。
2.4 记录结构分布表
不做逐字段的分布统计，只看能影响决策的几个结构性分组。
| 分组维度 | 数量 | 对决策的意义 |
|---|---|---|
| 物种·人类 | 642 | 默认假设成立，可直接用 |
| 物种·小鼠 | 150 | 可用，但注释体系与人类不完全通用 |
| 物种·其余三类 | 31 | 只适合方法学验证，不宜作唯一来源 |
| 实验类型·Hi-C | 596 | 主力，最通用 |
| 实验类型·ChIA-PET 与 HiChIP | 139 | 蛋白介导的靶向连接，需读原始论文 |
| 实验类型·Micro-C | 55 | 分辨率最高的一类 |
| 实验类型·scHi-C | 12 | 单细胞，覆盖很薄 |
| 分辨率下限·5kb 及以上 | 587 | 主流，缺环级细节 |
| 分辨率下限·1kb 及更细 | 80 | 极少数，Micro-C 与部分高深度 Hi-C |
| 分辨率下限·百碱基级 | 43 | 多为细菌基因组，分箱小是因为基因组小 |
| 原始编号·GSE 系列 | 799 | 绝大多数可在 GEO 溯源 |
| 元数据·有 DOI 与期刊 | 749 | 可自动做文献关联 |
| 元数据·缺细胞类型 | 134 | 检索时会漏掉，需按名称猜 |
这张表最重要的一行是「分辨率下限」。五kb 是分水岭：低于五kb 的数据，你才有资格谈论启动子-增强子之间那种几百纳米尺度的环；高于十kb，你只能谈论结构域。这个区别决定了 §1.4 里「挑分辨率」这一步的具体做法。
2.5 与同类资源的字段差异
| 资源 | 记录粒度 | 矩阵格式 | 注释供给 | 与原数据的距离 |
|---|---|---|---|---|
| 3D Genome Browser | 实验/细胞系 | mcool | 三级注释自带 | 一步，已归一化 |
| GEO | 样本与系列 | 无统一格式 | 不提供 | 零步，原始 |
| ENCODE 门户 | 实验 | 多种，含 mcool | 部分带处理结果 | 半步，管线统一 |
| 4DN 数据门户 | 实验 | 多种 | 部分 | 半步 |
| UCSC 交互浏览器 | 轨道 | 不适用 | 轨道级 | 一步，图为主 |
| Juicer 生态 | 实验 | .hic | 不适用 | 半步，工具链自洽 |
核心在最后一列：离原始数据越近越灵活、门槛越高；离图越近越易读、越难批量分析。本资源偏「一步」——比 GEO 好用得多，比 ENCODE 的统一管线松一些。它不做权威数据源，做的是「有了结论之后怎么方便地摆在一起看」。
§3 身份层：它到底是一个浏览器还是一个数据库
3.1 名实之间
名字叫 browser，自述也是「在线平台」，但从接口形态看，它更像一个带检索能力的注释服务。真正的浏览器只需要一个输入框和一张图，而这里的数据列表、详情页、下载按钮、JSON 接口，凑在一起是一套小型数据集服务。
这个错位决定了用法：当浏览器用，打开页面、输基因名、看图、截图；当数据库用，写脚本、批量取数、本地计算。两条路成本差别很大，站点对两条路都支持，只是没告诉你哪条更适合什么。
| 判断项 | 偏向浏览器的证据 | 偏向数据库的证据 |
|---|---|---|
| 首页入口 | 有可视化页，默认进图 | 也有数据集列表页 |
| 交互方式 | 缩放平移、轨道叠加 | JSON 接口，可脚本调用 |
| 输出形态 | 图像 | 结构化 JSON 与压缩包 |
| 数据规模 | 八百余条记录 | 清单一次性全量返回 |
| 批量能力 | 无批量导出界面 | 下载接口支持多 id |
| 文档 | 页面内提示为主 | 接口无公开文档，需读前端代码 |
最后一行是关键：接口无公开文档，端点与参数名要从前端脚本反推。这条路可行，但需要一点考古工作，§5 会完整写出来。
3.2 谁在维护，维护多久了
版本线索可以按时间排出来。
| 时间 | 事件 | 依据 |
|---|---|---|
| 2018 | 第一版论文发表于 Genome Biology，入口为 3dgenome.org，收录三百余套 | 论文摘要 |
| 2018 前后 | 提出专用二进制格式，声称体积至少缩小一个数量级 | 2018 论文摘要 |
| 2020 前后 | 2.0 版本上线，域名迁移至西北大学 | NAR 2026 论文与站点 |
| 2025 | 核心可视化引擎重写 | 站点关于页 |
| 2026 | 2.0 版论文发表于 NAR，数据集扩至七百余套 | 论文摘要 |
| 2026 | 清单接口返回八百余条记录 | 接口核对 |
必须如实记录一处口径差：论文摘要写「七百余套」，清单接口返回八百余条，差额约一百条，构成官方未说明。可能是定稿后又有新数据入仓，也可能是计数口径排除了某类记录。不做判断，只记两个数。
3.3 挂靠在哪张学术网络上
| 维度 | 情况 | 影响 |
|---|---|---|
| 通讯作者 | Feng Yue，3D 基因组领域主要团队之一 | 方法学有领域内认可 |
| 首发期刊 | Genome Biology，2018 | 方法论论文级别 |
| 现役论文期刊 | Nucleic Acids Research，2026 | 数据库专刊，同类资源的标准发表处 |
| 作者数 | 首版十余人，2.0 版七人 | 团队精简，迭代快 |
| 机构 | 宾州州立大学与西北大学 | 跨机构，需留意域名迁移 |
| 资助 | 站点提及多家机构支持，具体编号未在页面列出 | 长期维护依赖资助连续性 |
机构迁移在实践中很具体：旧域名现在 302 跳到新域名，是临时重定向而非常久，理论上旧地址还可能再变。写脚本时域名应做成配置项。
3.4 版本号里的取舍
2.0 不是一次简单的数据增量，它动了三处地基：界面把可视化、数据集列表、结构变异分析拆成三个独立页面；2025 年重写核心可视化引擎，站点自述「性能大幅提升」，这是自述、无第三方基准；数据仓库从「三百余套公共数据」升到「人工策展的七百余套」。
第三处最关键，关键词是「人工策展」——有人逐条核对元数据、统一命名、补注释。这条工作流成本很高，也是它相对于纯数据门户的核心差异。
§4 质量层：注释是怎么来的，可信到什么程度
4.1 三级注释，三把不同的尺子
| 层级 | 尺度量级 | 现象 | 文件形态 | 能不能跨数据集比较 |
|---|---|---|---|---|
| A/B 区室 | 兆碱基级 | 常染色质与异染色质在核内的空间分离 | bigwig 逐分箱数值 | 数值可比，正负号方向不一定对齐 |
| 拓扑结构域 | 十万碱基级 | 内部接触富集、边界外接触骤降的区块 | bed 区间 | 只有边界集合可比，边界位置有算法差异 |
| 染色质环 | 千碱基到十万碱基 | 两个具体位点的强接触 | bedpe 锚点对 | 最不稳定，强依赖深度与调用阈值 |
三者不是同一件事的三个叫法，而是三个尺度上三种不同的现象。可以这样理解：区室是城市分区，结构域是街区，环是两家之间那条每天要走的近路。分区变了街区未必变，街区变了近路可能还在。混为一谈的典型后果，是拿区室数值去论证结构域改变，或拿结构域边界去论证某个连接的存在。
4.2 策展做了什么、没做什么
做了的。 统一命名、统一格式（一律转 mcool）、补元数据（物种、器官、细胞类型、实验类型、分辨率、出处）、挂溯源（原始编号与 DOI）。
没做的。 没有重跑比对，工具与参数差异留在数据里；没有统一归一化，不同数据集的数值不能直接相减；没有统一环调用，环集合来自各自论文的方法；没有置信度分级，「极强的」与「勉强过线的」在文件里长得一样。
这条分界决定了你能做什么、不能做什么。
判断某一套数据能不能进分析，只需五个问题：组装版本一不一致、最低分辨率够不够、实验类型测没测到你关心的连接、归一化方法可否与其它数据比、环调用阈值是否与你的流程一致。前三个在字段里看得到，后两个只能回原始论文翻方法部分。这也正是把浏览器当索引比当仓库更实际的理由。
| 想做 | 能不能 | 原因 |
|---|---|---|
| 在同一套数据内部比较两个区域的接触强弱 | 能 | 同一矩阵同一归一化，内部可比 |
| 比较两套数据的同一区域接触强弱 | 谨慎 | 归一化不同，只能看趋势 |
| 把两套数据的环集合取交集 | 谨慎 | 调用阈值不同，交集偏小是算法假象 |
| 把两套数据的环集合取并集看覆盖 | 可以 | 并集对阈值不敏感，适合看「至少被谁支持」 |
| 把 TAD 边界直接合并成一个共识 | 谨慎 | 需先做边界聚类的标准化 |
| 拿 PC1 的正负号判断 A/B | 谨慎 | 方向需用基因密度或染色质状态校正 |
4.3 案例：rs6983267 与 MYC 的八十万碱基
用一个被反复研究过的位点把这些抽象说法落到地上，这个例子后文会反复回来。
染色体八上有一个常见变异 rs6983267，位于 128.4 到 128.5 兆碱基附近，与多种实体瘤风险相关，是全基因组关联研究早期的经典发现之一。麻烦在于它落在一片基因间区，最近的蛋白编码基因 MYC 在它下游约八十万碱基处。按「找最近的基因」的规则，自动化注释工具会把它派给一个更靠前、功能上无关的基因。
三维数据说的完全不同。在结肠与前列腺等上皮来源的细胞里，这个位点所在的增强子与 MYC 启动子之间存在稳定的染色质环——八十万碱基的线性距离，在核里被折成了一次近距离接触。这个结论不是从序列推出来的，是从构象捕获实验里读出来的。
案例同时展示三件事：线性距离会骗人、三维数据能纠偏、纠偏结论有细胞类型依赖性。把三层注释套在这个位点上，就得到三种不同的说法。
| 层级 | 在这个位点上会看到什么 | 它回答的问题 | 它回答不了的问题 |
|---|---|---|---|
| 区室 | 该位点与 MYC 所在区段可能同属 A 区室 | 两个区域是否属于同一类染色质环境 | 两者是否有直接接触 |
| 结构域 | 两者可能落在同一个结构域内，或有边界隔开 | 接触的机会是否被结构域边界限制 | 具体哪两个位点接触 |
| 环 | 位点与启动子之间有一条明确的 bedpe 记录 | 两者在物理上是否接触 | 这条接触是否在所有细胞类型中都成立 |
在浏览器上的操作路径也因此分成三步：先用基因检索接口拿到 MYC 在目标基因组版本下的坐标，再用换图接口取该位点附近与 MYC 附近构成的矩形窗口，然后在同一窗口内叠加环注释文件，看有没有一条锚点对横跨两边。§7.2 会把这条路径的失败模式逐一列出。
4.4 一个数据集能支撑几个问题
深度决定了上限，这一点在质量评估里比任何定性描述都有用。
| 测序深度档 | 通常能支撑的最低分辨率 | 能回答 | 不能回答 |
|---|---|---|---|
| 极深（Micro-C 级） | 百碱基到千碱基 | 核小体级别接触、启动子-增强子精细连接 | 细胞群内的异质性 |
| 深（高深度 Hi-C） | 五到十千碱基 | 环、结构域、区室 | 单细胞水平差异 |
| 中（常规 Hi-C） | 二十五到五十千碱基 | 结构域、区室 | 弱环、精细边界 |
| 浅（低深度或单细胞） | 兆碱基以上 | 区室 | 结构域与环 |
| 捕获型（Capture Hi-C） | 捕获区间内可较细 | 捕获区域内的连接 | 区域外任何东西 |
用法很直接：给定问题反推需要哪一档数据，再在清单里按 resolutions 字段筛，比逐条看描述快得多。
§5 取数层：怎么把数据拿出来
5.1 接口的整体形状
所有接口挂在 /api 前缀下，返回 JSON 或压缩包，无需令牌。下表是核对过的全部端点。
| 端点 | 方法 | 参数 | 用途 |
|---|---|---|---|
| /api/data/datasets | GET | 无 | 全量清单，六十余万字节 |
| /api/data/datasets/ | GET | 路径参数 | 单条详情 |
| /api/data/datasets/{id}/related | GET | 路径参数 | 相关数据集，查询多为空对象 |
| /api/data/datasets/{id}/resolutions | GET | 路径参数 | 该数据集的可用分辨率数组 |
| /api/data/datasets/{id}/plot_meta | GET | 路径参数 | 组装版本、染色体长度、通道清单 |
| /api/data/datasets/{id}/heatmap | GET | 见 5.3 | 矩形或三角换热图数值 |
| /api/data/datasets/{id}/sv_list | GET | 路径参数 | 该数据集的结构变异列表 |
| /api/data/datasets/{id}/sv_plot | GET | 见 5.5 | 重排后的接触图 |
| /api/data/sv_datasets | GET | 无 | 支持结构变异分析的数据集清单 |
| /api/data/download | GET | dataset_ids, type | 注释文件下载，返回流式 zip |
| /api/data/gene_loc_search | GET | query, assembly | 基因坐标检索 |
| /api/upload | POST | 表单文件 | 上传自有矩阵做可视化 |
最后一行需要提醒：前端支持上传本地矩阵做可视化，意味着文件会传到服务端。上传前确认里面没有未公开数据，生产数据的处理应在本地做。
调用上有几条惯例值得先记住。
| 惯例 | 具体做法 | 不这么做会怎样 |
|---|---|---|
| 染色体名带前缀 | 一律写 chr1，不写 1 | 返回空数组，且不报错 |
| 坐标用十进制的半开区间 | 起点含、终点不含 | 相邻窗口重叠或缺口一个分箱 |
| 分辨率取自该数据集的列表 | 先调分辨率接口核对 | 服务端就近取档，你可能以为取到了更细的 |
| 结果先判空 | 空字典表示没有，不是出错 | 批量脚本静默产出空结果 |
| 域名做成配置 | 不写死在几十处 | 域名再迁移一次就要全局改 |
| 请求加超时与重试 | 换图接口在大窗口下会慢 | 长任务卡住不返回 |
| 结果落盘再处理 | 不要把查询塞进循环里 | 同一个窗口被反复请求 |
第一条的坑最常见：它返回空数组而不是错误码，代码会一路跑到底，最后得到一张全零的图，而你会先怀疑数据，再怀疑坐标，最后才想到染色体名。
5.2 拉清单、筛选、取注释
第一段脚本把全量清单拉下来存成本地缓存，再按条件筛。
#-- 拉全量清单并按分辨率下限筛选
import json, urllib.request
BASE = "https://3dgenome.fsm.northwestern.edu/api"
def get(path, timeout=60):
req = urllib.request.Request(BASE + path, headers={"User-Agent": "dataset-wiki/1.0"})
with urllib.request.urlopen(req, timeout=timeout) as r:
return json.loads(r.read().decode("utf-8"))
records = get("/data/datasets")
print("总记录数:", len(records))
#-- 只看人类、且最低分辨率不粗于 10kb 的数据
fine = [r for r in records
if r["species"] == "Human"
and r["resolutions"]
and min(r["resolutions"]) <= 10000]
print("人类且最低分辨率 <=10kb:", len(fine))
#-- 按实验类型计数，用于决定后面挑哪一类
from collections import Counter
print(Counter(r["dataType"] for r in fine))
with open("records.json", "w", encoding="utf-8") as f:
json.dump(records, f, ensure_ascii=False)
清单只有六十余万字节，一次拉完本地缓存，后续所有筛选都在这份缓存上做，不要反复请求。
同一个脚本顺手把注释文件也拿下来，就能看出下载接口的形态。
#-- 下载注释包，读出包内清单
import io, zipfile, urllib.request
BASE = "https://3dgenome.fsm.northwestern.edu/api"
url = BASE + "/data/download?dataset_ids=0&type=all"
with urllib.request.urlopen(url, timeout=180) as r:
raw = r.read()
print("压缩包字节数:", len(raw))
try:
z = zipfile.ZipFile(io.BytesIO(raw))
for info in z.infolist():
print(info.filename, info.file_size)
except zipfile.BadZipFile:
#-- 流式 zip 只有 local header、没有中央目录，标准库读不了
print("无中央目录，改用 unzip 命令行展开")
这里有一个必须写出来的坑。下载接口返回的内容头是 zip，但没有中央目录，标准库的 zipfile 会直接报错。命令行的 unzip 可以正常展开，因为它按 local header 顺序流式解析。文件本身没有损坏，只是不是「完整」的 zip。
5.3 按坐标取换热图
第二段脚本给定数据集与矩形窗口，取回接触强度方阵。参数名是从实际请求里反推并逐个核对过的。
| 参数 | 含义 | 取值 | 备注 |
|---|---|---|---|
| x_chrom / y_chrom | 横轴与纵轴染色体 | chr1 等 | 必须带前缀；两轴不同即染色体间接触 |
| x_start / x_end | 横轴起止 | 整数 | 非分辨率整数倍时服务端补齐到格 |
| y_start / y_end | 纵轴起止 | 整数 | 同上 |
| resolution | 分箱宽度 | 需在 resolutions 列表内 | 不在列表内会就近取档 |
| lock_resolution | 是否锁分辨率 | true / false | 缩放时是否跟随变化 |
| normalization | 归一化方式 | raw 等 | 默认 raw |
| display_mode | 显示模式 | rectangle 或三角 | 决定返回矩阵是否对称 |
| auto_resolution | 是否自动选分辨率 | true / false | 关掉才能保证取到指定档位 |
| compare_dataset_id | 对比数据集 | 整数，可空 | 填入则叠加第二套 |
#-- 取一个两兆碱基见方的窗口，10kb 分辨率
import json, urllib.request, urllib.parse
BASE = "https://3dgenome.fsm.northwestern.edu/api"
params = {
"x_chrom": "chr1", "x_start": 1000000, "x_end": 2000000,
"y_chrom": "chr1", "y_start": 1000000, "y_end": 2000000,
"resolution": 10000,
"lock_resolution": "false",
"normalization": "raw",
"display_mode": "rectangle",
"auto_resolution": "false",
}
url = BASE + "/data/datasets/0/heatmap?" + urllib.parse.urlencode(params)
with urllib.request.urlopen(url, timeout=120) as r:
d = json.loads(r.read().decode("utf-8"))
print("返回的矩阵形状:", d["shape"])
print("首个横轴标签:", d["x_labels"][0])
print("字段清单:", sorted(d.keys()))
取回来的对象里有形状、标签与数值三部分。数值以二维数组返回，行列对应标签数组。注意 shape 是服务端按你给的窗口与分辨率算出来的，不是你指定的——给的窗口不是分辨率的整数倍时，服务端会补齐到格。
5.4 基因名转坐标
第三段脚本把基因符号换成坐标，这是几乎所有查询的第一步。
#-- 基因符号检索，返回所有前缀匹配的基因
import json, urllib.request, urllib.parse
BASE = "https://3dgenome.fsm.northwestern.edu/api"
def locate(gene, assembly="hg38"):
q = urllib.parse.urlencode({"query": gene, "assembly": assembly})
with urllib.request.urlopen(BASE + "/data/gene_loc_search?" + q, timeout=30) as r:
return json.loads(r.read().decode("utf-8"))
hits = locate("MYC", "hg38")
for h in hits:
print(h["gene"], h["chr"], h["start"], h["end"])
#-- 同一基因在两个组装下的坐标不同，必须成对记录
print("hg19:", locate("MYC", "hg19")[0])
接口是前缀匹配，查 MYC 会同时返回 MYCBP、MYCBP2，要精确取需按 gene 字段做等值过滤。同一基因在 hg19 与 hg38 下的坐标差几万到十几万碱基，混用会让窗口整个偏掉。
5.5 结构变异分析
第四段脚本取 2.0 新增的结构变异模块。先拿清单，再取重排后的接触图。
#-- 结构变异：先看哪些数据集支持，再取重排图
import json, urllib.request, urllib.parse
BASE = "https://3dgenome.fsm.northwestern.edu/api"
with urllib.request.urlopen(BASE + "/data/sv_datasets", timeout=60) as r:
sv = json.loads(r.read().decode("utf-8"))
print("支持结构变异的数据集:", len(sv))
print("示例:", sv[0]["name"], sv[0]["species"], sv[0]["dataType"])
params = {
"chrom1": "chr1", "chrom2": "chr1",
"strand1": "+", "strand2": "+",
"breakpoint1": 1000000, "breakpoint2": 2000000,
"sv_type": "translocation",
"resolution": 10000, "balance": "false",
"extension": 5000000, "auto_extension": "true",
}
q = urllib.parse.urlencode(params)
url = BASE + "/data/datasets/38/sv_plot?" + q
with urllib.request.urlopen(url, timeout=120) as r:
d = json.loads(r.read().decode("utf-8"))
print(sorted(d.keys()))
print("原始图分辨率:", d["original"]["resolution"])
这个模块解决的问题很具体：基因组发生大片段易位、倒位、缺失时，接触图会以断点为中心重新排布，原本相距很远的两个区段被拼到相邻位置，于是出现「增强子劫持」——本不该作用于某基因的增强子，因重排而靠近了它。这类事件在血液肿瘤里尤其常见。
5.6 只读接口的边界
| 想要的 | 接口给不给 | 替代做法 |
|---|---|---|
| 一次拉多套矩阵 | 不给 | 逐条取窗口，或在客户端拼 |
| 取整个染色体的矩阵 | 理论可行但极大 | 用粗分辨率或分窗口 |
| 按细胞类型批量检索 | 不支持参数化检索 | 拉全清单本地筛 |
| 拿到归一化的说明文档 | 不给 | 只能看 normalization 参数的可选值并试 |
| 拿到环调用的参数 | 不给 | 回原始论文查方法部分 |
| 拿到置信度分级 | 不给 | 自建评分，见 §7.2 |
| 订阅更新 | 不给 | 定期拉清单做差分 |
最后一行是实用建议：清单接口返回全量，两次拉取做差分就是最简的更新监控。
§6 与库内条目的关系
6.1 关系图谱
它在库里的位置，是几个上游资源的下游消费端。
| 库内条目 | 关系类型 | 怎么配合 |
|---|---|---|
| ENCODE | 上游数据来源之一 | ENCODE 有统一管线的处理结果，本资源在其上做格式统一与注释整理 |
| GTEx | 同为调控基因组参考 | GTEx 给表达与数量性状位点，本资源给结构连接，两者拼起来才能说「这个变异影响了哪个基因的表达」 |
| GWAS Catalog | 上游发现来源 | 关联研究给位点，本资源给位点的三维靶基因，因果链条的两端 |
| GENCODE | 坐标参考 | 基因注释版本决定基因边界，影响靶基因判定的分子 |
| 1000 Functional Connectomes | 结构类比 | 同为「把空间关系表示成图」，一个是脑区连接组，一个是染色质接触组 |
| AlphaFold | 尺度类比 | 一个在分子尺度预测三维结构，一个在染色体尺度测量三维结构 |
第一条最实际：ENCODE 也收 Hi-C 与 ChIA-PET，但按「实验」组织，本资源按「细胞类型与结构注释」组织。取原始数据去 ENCODE，取现成注释来这里。第三条最容易被误用：GWAS Catalog 给统计关联，本资源给物理接触，关联加接触仍不构成因果，还需数量性状位点或实验验证。
6.2 检索路径
| 起点 | 中间要找什么 | 在本资源里怎么落 | 常见断点 |
|---|---|---|---|
| 一个风险位点 | 位点坐标、候选基因 | 基因检索 + 换热图 | 位点不在任何环锚点上 |
| 一个靶基因 | 基因坐标、细胞类型 | 基因检索 + 按细胞类型筛数据集 | 目标细胞类型没有覆盖 |
| 一个结构变异 | 断点坐标、sv_type | 结构变异清单 + 重排图 | 该数据集不在清单里 |
| 一个细胞类型 | 该类型的全部数据集 | 清单按 cellType 筛 | 字段为空或命名不一 |
| 一个实验方法 | 该方法的数据集 | 清单按 dataType 筛 | 类型枚举只有七个，细分需读描述 |
| 一篇论文 | DOI 或原始编号 | 清单按 doi 或 refNo 筛 | 74 条无 DOI，需用名称匹配 |
第三条路径的断点最硬：结构变异分析只覆盖一百六十余套数据集，不到总量的四分之一。
§7 质量评估与局限性
7.0 阅读本节前的一个前置校正
在评价这个资源之前，需要先纠正一个默认的误判：把它当成「数据源」来打分。
按数据源的标准，分数不会高：不提供原始测序数据，不提供统一重处理结果，注释算法不统一。按「注释服务」的标准，分数完全不同：格式统一、坐标规范、三级注释齐全、接口可用、八百余套人工策展。
这是评价工具型资源时最常见的误判，也解释了为什么评价会两极：做湿实验的人觉得它好用，做数据工程的人觉得它不严谨。两者都没错，只是尺子不同。
评分用的是第三把尺子：作为一个「给生物学问题提供结构先验的中间层」它做得怎么样。
7.1 五维评分
评分采用 DAIMS 框架的五个维度，每条给分并写明理由。
| 维度 | 分值 | 理由 |
|---|---|---|
| 可发现性 | 4.5 / 5 | 有论文、有稳定域名、旧域名重定向，检索友好 |
| 可访问性 | 4.0 / 5 | 无需注册、接口无需令牌；但无公开文档，端点需从脚本反推 |
| 互操作性 | 3.5 / 5 | 格式走行业标准（mcool/bed/bedpe/bigwig）；但注释算法不统一，跨集合并需自行协调 |
| 可复用性 | 3.0 / 5 | 元数据齐全可溯源；但矩阵不能整包取，环与边界不能跨数据集直接合并 |
| 可信度 | 3.5 / 5 | 来源可溯至 GEO 与论文；但无置信度分级，无统一调用流程 |
合计十六点五分，满分为二十五。这个分数对应的是「专业用户会觉得称手，通用流程会觉得别扭」这一档。
最低分在可复用性，原因与数据质量无关：只提供 mcool 的站点能被 cooler 生态直接吸收，不能被 hic 生态直接吸收。格式墙是这个领域复用率低的直接原因之一。
把五个维度放到同类资源里比，差异会更清楚。
| 维度 | 本资源 | 通用门户（ENCODE 类） | 命令行工具链（Juicer 类） | 单细胞专属库 |
|---|---|---|---|---|
| 可发现性 | 强，数据库专刊收录 | 强，机构背书 | 中，靠社区传播 | 中 |
| 可访问性 | 强，匿名接口 | 强，有完整文档 | 强，本地运行 | 中，部分需申请 |
| 互操作性 | 中，绑定一种格式生态 | 强，多格式并存 | 中，自有格式 | 弱，格式各异 |
| 可复用性 | 中，注释现成但不可合并 | 强，管线统一 | 强，全流程可控 | 弱 |
| 可信度 | 中，来源可溯但无分级 | 强，统一质控 | 强，参数透明 | 中 |
这也解释了为什么有人觉得它比门户好用，有人觉得它不严谨：前者看互操作性，后者看可复用性与可信度，两边都在看真问题。
7.2 贯穿案例的落地路径与失败模式
回到 §4.3 的案例。这条路径在实操上有五个节点，每个节点都可能断。
| 节点 | 要做的事 | 失败模式 | 现象 |
|---|---|---|---|
| 定位变异 | 拿到位点在目标组装下的坐标 | 用了错误组装 | 窗口整体偏移十几万碱基 |
| 选细胞类型 | 挑与该组织相关的数据集 | 目标类型无覆盖，用邻近类型代理 | 结论外推到不存在的细胞类型 |
| 定分辨率 | 核对 resolutions 里有没有够细的档 | 用了 1Mb 档 | 环完全看不见，只剩一片均匀背景 |
| 取窗口 | 横纵各覆盖两个位点 | 窗口太窄，环被截断 | 环的二分一锚点在窗口外，图上只剩半个 |
| 叠注释 | 加载 bedpe，筛出横跨两边的锚点对 | 未按强度阈值筛 | 噪声环混入，结论不稳 |
五个节点里最容易被忽略的是第四个。「窗口要覆盖两个位点」这句话听着理所当然，但当你查的是一个在两兆碱基外、一个在四百万碱基外的两个位点时，窗口会变得很大，而大窗口在细分辨率下返回的矩阵会大到无法处理。实际做法是先粗后细：用粗分辨率定位大致位置，再用细分辨率取小窗口确认。
这个「先粗后细」的策略可以写成一个小函数。
#-- 先粗后细：两段式取图，避免一次要一个巨大矩阵
import json, urllib.request, urllib.parse
BASE = "https://3dgenome.fsm.northwestern.edu/api"
def window(ds, xa, xb, ya, yb, res):
p = {"x_chrom": "chr8", "x_start": xa, "x_end": xb,
"y_chrom": "chr8", "y_start": ya, "y_end": yb,
"resolution": res, "lock_resolution": "false",
"normalization": "raw", "display_mode": "rectangle",
"auto_resolution": "false"}
u = BASE + f"/data/datasets/{ds}/heatmap?" + urllib.parse.urlencode(p)
with urllib.request.urlopen(u, timeout=180) as r:
return json.loads(r.read().decode("utf-8"))
#-- 第一段：粗看，250kb 分辨率，覆盖位点与基因之间
coarse = window(0, 127000000, 129000000, 127000000, 129000000, 250000)
print("粗看形状:", coarse["shape"])
#-- 第二段：细看，10kb 分辨率，只取位点附近与基因启动子附近两条窄带
fine = window(0, 128400000, 128600000, 128700000, 128800000, 10000)
print("细看形状:", fine["shape"])
第二段取的是非方形窗口。两个位点若相距八十万碱基，应取横跨八十万、纵跨两万的长条；接口支持，因为横纵坐标各自独立指定。
7.3 已知的、可枚举的偏差
| 偏差 | 表现 | 后果 | 缓解 |
|---|---|---|---|
| 物种偏差 | 人类占七成八 | 非人问题基本无解 | 明确不出这个范围 |
| 细胞类型偏差 | 器官集中在血液、胚胎、前列腺 | 罕见组织缺覆盖 | 用邻近组织代理并声明 |
| 深度偏差 | 多数数据最低分辨率 5kb | 环级问题只能覆盖少数 | 按分辨率筛，不看总量 |
| 算法偏差 | 环与边界来自各自论文 | 跨集合运算引入假差异 | 不跨集合并，只判包含关系 |
| 归一化偏差 | 各自归一化 | 强度值不能跨集比较 | 只比趋势，或做秩变换 |
| 时间偏差 | 2018 年前后方法差异大 | 老数据的环调用偏保守 | 按年份分层 |
| 命名偏差 | 细胞类型自由文本 | 检索漏掉同物异名 | 关键词人工扩写 |
| 空值偏差 | 七十余条无 DOI，百余条无细胞类型 | 自动关联失败 | 用描述文本兜底匹配 |
倒数第二条的严重性常被低估：同一个细胞在不同论文里可能有四五种写法，检索只匹配一种就会漏。
7.4 外部验证矩阵
| 结论 | 外部验证方式 | 结果 |
|---|---|---|
| 数据集总量八百二十三 | 再调一次清单接口 | 可重复，条数一致 |
| 人类六百四十二套 | 按 species 字段计数 | 一致 |
| 全部为 mcool 格式 | 按 formats 字段计数 | 一致 |
| 全部标记为已核验 | 按 verified 字段计数 | 一致 |
| 主流最低分辨率 5kb | 按 resolutions 最小值分档 | 分档一致 |
| 下载包只含注释不含矩阵 | 实际下载一次并看文件名 | 一致，且无中央目录 |
| 结构变异仅覆盖部分数据集 | 调 sv_datasets 计数 | 一致 |
| 注入不存在的 id 返回空对象 | 请求一个越界 id | 返回空字典而非报错 |
| 单条数据集无结构变异时会报服务端错误 | 请求一个无 SV 的 sv_list | 返回服务端错误，非空数组 |
倒数第二条值得记住：越界 id 不报错，返回空对象。这意味着你的批量脚本不会因为 id 打错而中断，反而会静默出错。脚本里必须自己判空。
7.5 它为何能持续：因为它是别人工作的副产品
它能活到今天，不是因为有人专门投钱做产品，而是因为它长在研究流水线的末端：三维基因组学的课题组都在产生构象捕获数据，都需要把自己的数据摆到别人的旁边看一眼，浏览器是这个需求的最小满足形态。
人工策展成本由自用摊薄：团队本来就得整理这些数据，顺手发布便是公共服务。这比拿一笔经费从零建门户稳固，因为它存在的前提是研究在继续，而不是经费在延续。代价是边界随研究兴趣走——团队关注哪里，那部分数据就更全。
§8 生态位与历史
8.1 历史沿革
| 阶段 | 时间 | 特征 | 关键变化 |
|---|---|---|---|
| 第一代 | 2018 及以前 | Hi-C 数据分析门槛极高，结果多以静态图发表 | 出现专用压缩格式，把矩阵体积压到可在线传输 |
| 第一代末期 | 2019 前后 | 浏览器上线，三百余套数据 | 首次把公共数据按坐标统一 |
| 第二代 | 2020 前后 | 迁移域名，界面重做 | 从研究工具转向公共服务 |
| 第二代中期 | 2022 到 2024 | 单细胞与 Micro-C 兴起 | 数据类型从七类扩展到含单细胞 |
| 第二代后期 | 2025 | 引擎重写 | 性能提升，支撑更大数据量 |
| 第三代 | 2026 | 2.0 论文发表，新增结构变异模块 | 从「看图」转向「看图 + 推机制」 |
这八年正好是三维基因组从「少数实验室的技术」变成「常规注释」的八年。第一代的贡献常被忽略：它解决了一个工程问题——矩阵体积。人类全基因组矩阵早年动辄几十上百 GB，不压缩不可能在线交互。2018 年摘要称新格式把体积至少缩小一个数量级，且能在数秒内显示百万碱基级的相互作用。
8.2 它站在哪种工具传统里
三条传统汇到这里：基因组浏览器传统，交互始终是「输入坐标、看轨道上叠了什么」，三维数据只是再加一层；矩阵格式传统，Hi-C 社区为稀疏矩阵发明过多套格式，各绑各的工具链，选 mcool 就是选了 cooler 生态；数据库策展传统，人工核对元数据、统一命名、挂溯源。
三条叠在一起，决定了它的性格：交互保守、格式选边、数据靠策展。
| 技术选择 | 来自哪条传统 | 好处 | 代价 |
|---|---|---|---|
| 按坐标查而不是按样本查 | 基因组浏览器 | 与已有分析习惯一致 | 批量取整个样本时要绕 |
| 选 mcool 而不是 hic | 矩阵格式 | 与 cooler 生态无缝 | Juicer 用户需转换文件 |
| 多分辨率共存一个文件 | 矩阵格式 | 缩放时无需重算 | 单文件体积大，传输不友好 |
| 三级注释随数据一起给 | 数据库策展 | 开箱可用 | 算法差异被一起继承 |
| 细胞类型用自由文本 | 数据库策展 | 策展灵活，能记下细节 | 检索必须做同义词扩展 |
| 记录粒度是实验不是样本 | 数据库策展 | 与文献对应清楚 | 同一实验室多次重复会散成多条 |
| 全量清单一次返回 | 浏览器传统 | 客户端筛选随意 | 无法做服务端分页与增量 |
倒数第三行值得单说：自由文本让检索不可靠，同样是小脑颗粒细胞，文献里可能有三四种写法，按一种筛就会漏。这不是数据错误，是策展粒度的取舍。
8.3 与直接竞品的位置关系
| 竞品类型 | 代表 | 它更强的地方 | 它更弱的地方 |
|---|---|---|---|
| 通用基因组浏览器 | UCSC 一类 | 有专门的三维注释层 | 轨道管理不如通用浏览器成熟 |
| 数据门户 | ENCODE、4DN | 注释现成，开箱即用 | 管线统一性不如门户 |
| 命令行工具链 | Juicer、cooler | 有图形界面，零代码入门 | 批量能力弱，格式只认一种 |
| 静态图与补充材料 | 论文附件 | 可交互，可跨数据集 | 没有经过同行评审 |
| 单细胞专用工具 | 各类单细胞流程 | 覆盖多种细胞类型 | 单细胞数据只有十二套 |
最值得注意的是最后一行：单细胞 Hi-C 是近年最热的方向之一，而这里只有十二套、且集中在少数脑细胞类型。做单细胞三维基因组，这里只能当起点，不能当仓库。
8.4 边界之外还有什么
§1.3 与 §1.6 已从需求与用户两端划过一次边界，这里补一件历史视角下才看得清的事。
三代版本都在做同一件事：把越来越多的处理结果直接给你。第一代加格式压缩，第二代加坐标查询与界面，第三代加结构变异的机制推演。每一步都在缩短「从原始数据到结论」的距离，同时也把更多上游决策固化进注释，东西越好用，也越不透明。
这个趋势的边界在于：当固化的决策多到无法回溯，注释就成了不可质疑的黑箱。目前还没到——每套数据都能溯源到原始论文，方法部分写得清楚。判断一个资源能不能长期用，不只看它现在给了什么，还要看它是否保留了你亲自走一遍的能力。
§9 使用指引
9.1 三种角色的路径
同一个站点，三类人的走法完全不同，要写进报告的东西也不同。
第一类，做湿实验、想给结果找一个结构解释的人。 打开可视化页，输基因名或坐标，选一套与你的细胞类型最接近的数据，看换热图，截图写进讨论。全程不写代码，只需在选数据时多花五分钟看分辨率——这五分钟决定了那张图能支撑结论，还是只能当装饰。
第二类，做生信、要把结构信息接进流水线的人。 先拉清单本地缓存，按物种、器官、分辨率筛出候选，再逐条取注释，把 bed 与 bedpe 转成流程里的区间对象，最后在同一基因组版本下与变异或表达数据交叠。这条路上最容易出问题的是组装版本——只要有一条数据是 hg19，整批结果都会偏。
第三类，做方法学、要评估「三维信息到底有没有增益」的人。 挑一个已知答案的位点，比如 §4.3 的案例，分别用线性距离和三维接触做靶基因预测，比较两者与文献共识的一致率。产出不是新发现，是对「三维信息值多少钱」的量化回答。
三类路径成本差别很大，但第一步都一样：查这个细胞类型在不在。
| 角色 | 可以写进报告的 | 只能写在讨论里的 | 不能写的 |
|---|---|---|---|
| 实验研究者 | 该细胞系中观察到该位点与启动子存在接触 | 可能提示存在调控关系 | 因此该变异致病 |
| 生信工程师 | 结构注释来自某数据集、分辨率若干 | 不同数据集之间趋势一致 | 两套数据的强度相差若干倍 |
| 方法学研究者 | 加入三维特征后某指标变化若干 | 增益可能来自某因素 | 三维信息必然优于线性距离 |
第二列最容易被突破：看到一条漂亮的环就想写机制，看到两套数据趋势一致就想算倍数。这两步都需要额外证据，单靠浏览器的数据支撑不住。
9.2 一条最短的可用流程
从零到一张能进论文的图，最短路径是下面这条。
#-- 第一步：确认基因坐标（hg38）
curl -s "https://3dgenome.fsm.northwestern.edu/api/data/gene_loc_search?query=MYC&assembly=hg38"
#-- 第二步：筛出人类、最低分辨率不粗于 10kb 的数据集
curl -s "https://3dgenome.fsm.northwestern.edu/api/data/datasets" \
| python3 -c "
import json,sys
d=json.load(sys.stdin)
for r in d:
if r['species']=='Human' and r['resolutions'] and min(r['resolutions'])<=10000:
print(r['id'], r['name'], r['dataType'], min(r['resolutions']))
" | head -20
#-- 第三步：取目标窗口的接触矩阵（横轴位点、纵轴启动子）
curl -s "https://3dgenome.fsm.northwestern.edu/api/data/datasets/0/heatmap?\
x_chrom=chr8&x_start=128400000&x_end=128600000&\
y_chrom=chr8&y_start=127700000&y_end=128000000&\
resolution=10000&lock_resolution=false&normalization=raw&\
display_mode=rectangle&auto_resolution=false" > window.json
#-- 第四步：下载该数据集的环注释，筛出跨两个窗口的锚点对
curl -sL "https://3dgenome.fsm.northwestern.edu/api/data/download?dataset_ids=0&type=all" \
-o ann.zip && unzip -o ann.zip -d ann/
#-- 第五步：在 bedpe 里找一锚点落在 x 窗口、另一锚点落在 y 窗口的行
awk -F'\t' '($1=="chr8" && $2>=128400000 && $3<=128600000 &&
$4=="chr8" && $5>=127700000 && $6<=128000000) ||
($4=="chr8" && $5>=128400000 && $6<=128600000 &&
$1=="chr8" && $2>=127700000 && $3<=128000000)' \
ann/*.bedpe | sort -k8,8gr | head -20
第二步到第四步都能批量化。最后一步用 awk 双向匹配，是因为 bedpe 的锚点顺序不保证，同一条环可能出现在左列也可能反面，只写单向匹配会漏一半。
有一处写论文时必须补：分辨率。取图写 10kb，但若某套数据最低只到 25kb，服务端会就近取 25kb，格子宽度变了，能看到的最小结构也变了。方法部分要写实际取到的档位。
9.3 引用方式
| 引用对象 | 场景 | 应写的内容 |
|---|---|---|
| 资源本身 | 说明数据来源平台 | 2026 年 NAR 论文，或按惯例引 2018 年首发论文 |
| 具体数据集 | 说明用了哪一套数据 | 该数据集对应的原始论文 DOI |
| 原始测序数据 | 说明数据出处 | GEO 或 SRA 编号 |
| 处理流程 | 说明格式转换 | 该数据集描述里写明的实验协议 |
| 注释文件 | 说明环与边界 | 原始论文的方法部分，不是浏览器 |
第二行最容易被省掉。只写「数据取自 3D Genome Browser」不完整，评审会要求写明细胞系、文献、分辨率。浏览器是获取渠道，不是数据的著作权人。
§10 AI 使用声明
本文由人工核验与语言模型协作完成，分工与边界如下。
| 环节 | 谁做的 | 具体内容 | 需要你复核什么 |
|---|---|---|---|
| 入口探测 | 模型执行 | 对旧域名与新域名做重定向核对 | 当前域名是否仍有效 |
| 接口发现 | 模型执行 | 从前端脚本反推端点与参数名 | 参数是否随版本变化 |
| 数据拉取 | 模型执行 | 调清单接口、换图接口、下载接口 | 条数是否仍为八百余条 |
| 数字核对 | 模型执行 | 按字段计数并用脚本复核 | 分类计数的口径 |
| 论文摘要 | 模型执行 | 从欧洲 PMC 取两版论文摘要 | 摘要之外的方法细节未覆盖 |
| 正文写作 | 模型起草 | 结构、案例、评分、路径 | 与你所在领域的实际经验是否相符 |
| 事实判断 | 人工 | 哪些数字进正文、哪些标未核实 | 是否存在过度解读 |
| 领域知识 | 人工 | 三级结构层级的用法与误区 | 是否与最新共识一致 |
未做的事，一并声明：没有下载全量矩阵，没有重跑任何比对，没有独立复现环调用算法，没有对八百余条记录逐条打开核对描述。本文出现的所有规模与结构数字，来自清单接口一次全量返回与若干次单条查询；所有边界判断，来自接口形态与论文摘要，不做超出这两处的推断。
常见误读（避坑清单）
| 常见说法 | 实际 | 证据 |
|---|---|---|
| 浏览器上有 Hi-C 矩阵，可以直接下载 | 下载接口只给 bedpe/bed/bigwig 三类注释，矩阵要按坐标取 | type=all 解包后只有一个 bedpe 文件 |
| 三百套变成了八百套，翻了快三倍 | 三个数字来自三个时点、三种计数口径 | 2018 摘要三百余套，2026 摘要七百余套，接口八百余条 |
| 格式统一了就能跨数据集比较 | 格式统一不等于归一化统一，强度值不能直接相减 | 清单无归一化字段，各数据集描述写的是各自协议 |
| TAD 是染色质的基本单元 | 边界依算法而变，不是固定物理实体 | 不同论文在同一矩阵上给出不同边界集合 |
| 有接触就等于有调控 | 接触是必要条件不是充分条件 | 位点间接触广泛存在，调控需要额外活性证据 |
| 分辨率越高越好，直接要最细的 | 细分辨率只在小窗口可用，大窗口会返回巨阵 | 换图接口按窗口与分辨率算 shape |
| 单细胞 Hi-C 这里也有，能做单细胞分析 | 只有十余套，局限在少数物种与组织 | 清单里 scHi-C 的条数与物种分布 |
| 旧域名打不开了，资源下线了 | 旧域名重定向到新域名，服务仍在 | 请求旧域名返回重定向与新域名内容 |
| 下载的压缩包解不开，文件坏了 | 是流式 zip，缺中央目录，命令行可展开 | 字节流里找不到目录结束标记 |
| 查不到的 id 会报错，脚本能感知 | 越界 id 返回空对象，不报错 | 请求不存在的记录返回空字典 |
FAQ
Q1：这个浏览器和 ENCODE 的 Hi-C 数据是什么关系？
它是消费方不是生产方。原始测序数据在 GEO 或 SRA，浏览器做格式统一与三级注释整理。要 fastq 去 GEO，要能直接画图的 mcool 来这里。
Q2：能不能直接下载全量矩阵？
不能。清单接口只给元数据，下载接口给 bedpe、bed、bigwig 三类注释。矩阵要按坐标片段取，或去原始来源取完整 mcool。
Q3：1kb 分辨率和 1Mb 分辨率回答的是同一个问题吗？
不是。兆碱基级看 A/B 区室，十万碱基级看 TAD 边界，千碱基级才看得到启动子与增强子之间的环。拿兆碱基级矩阵找增强子-启动子连接，只会得到一片均匀背景。
Q4：为什么三维基因组数据复用率这么低？
从 fastq 到归一化矩阵之间岔路口很多：比对工具、过滤策略、归一化方法、分箱分辨率、环调用算法，每一步都有多个被接受的做法。浏览器能统一格式，统一不了上游。
Q5：这个浏览器适合做机器学习训练集吗？
可以做特征来源，不适合做标签来源。三级注释给的是结构化特征，适合往模型里喂；但注释本身带调用算法偏差，直接把环当金标准标签会把偏差一起学进去。
Q6：为什么同一套数据在不同页面显示的分辨率不一样？
resolutions 字段列的是可用档位，换图接口在没有锁定分辨率时会按窗口大小自动选一档。lock_resolution 设为真可以强制你指定的档位，但窗口过大会失败。
Q7：TAD 和 compartment 到底该用哪个？
看你问的问题有多大。问「这段染色质属于活跃还是沉默环境」用 compartment；问「这个结构域里包含哪些基因」用 TAD；问「这两个具体位点有没有接触」用 loop。三者不能用同一个数值互相代替。
Q8：单细胞 Hi-C 的数据够用吗？
只有十余套，且集中在少数物种的少数脑细胞类型。做方法验证够，做通用资源不够。如果你的问题是跨细胞类型的异质性，这里只能当起点。
Q9：结构变异分析覆盖多少数据？
不到总量的四分之一。先用结构变异的数据集清单接口确认真的是否在列，再取重排图，不要假设任何一套数据都支持。
Q10：这个站点会不会关停？
判断的落脚点不是经费，是研究是否继续。维护成本被研究流水线摊薄，团队还在做三维基因组，站点就有存在理由。域名迁移过一次，脚本里应把域名做成配置项。
Q11：为什么下载的 zip 用 Python 打不开？
下载接口返回流式拼接的 zip，只有文件头没有末尾中央目录。标准库要求完整 zip，会直接报错；用命令行 unzip 可展开，或自己按文件头逐段解析。
Q12：我可以在论文里写「数据取自 3D Genome Browser」吗？
可以，但不完整。方法部分还要写明具体的细胞系、数据集编号、原始论文、实际使用分辨率。浏览器是获取渠道，不是数据来源。
术语表
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 三维基因组 | 3D genome | 染色体在细胞核内的空间折叠方式 |
| 染色体构象捕获 | chromosome conformation capture | 一类把空间上靠近的 DNA 片段交联、切碎、连接再测序的技术族 |
| Hi-C | Hi-C | 全基因组范围的构象捕获，测所有片段两两之间的接触频率 |
| Micro-C | Micro-C | 用微球菌核酸酶切，分辨率能到核小体级的高分辨率变体 |
| ChIA-PET | ChIA-PET | 带免疫沉淀的构象捕获，只测与特定蛋白相关的连接 |
| HiChIP | HiChIP | 与 ChIA-PET 目的相似但灵敏度更高、输入量更低 |
| Capture Hi-C | Capture Hi-C | 用探针富集目标区域的 Hi-C，只覆盖捕获区 |
| 单细胞 Hi-C | scHi-C | 逐个细胞建库，用于看细胞间异质性 |
| 区室 | compartment A/B | 兆碱基级的活跃与不活跃染色质分区 |
| 拓扑结构域 | TAD | 十万碱基级、内部接触富集且边界清晰的区块 |
| 染色质环 | chromatin loop | 两个特定位点之间的高接触连接 |
| 接触矩阵 | contact matrix | 行列为基因组分箱、值为接触频率的方阵 |
| 分箱 | bin | 把基因组切成固定宽度的格子，宽度即分辨率 |
| 分辨率 | resolution | 分箱宽度，决定能看到多细的结构 |
| 归一化 | normalization | 消除测序深度与偏差，让矩阵数值可比的处理 |
| mcool | mcool | cooler 生态的多分辨率矩阵容器格式 |
| bedpe | BEDPE | 表示区间对的文件格式，一行一对锚点 |
| bigwig | bigWig | 表示逐分箱连续数值的二进制轨迹格式 |
| PC1 | first principal component | 接触矩阵第一主成分，正负号划分两个区室 |
| 锚点 | anchor | 环或连接的一端所对应的基因组区间 |
| 增强子劫持 | enhancer hijacking | 结构变异把增强子搬到别的基因附近，导致其异常激活 |
| 结构变异 | structural variant | 长度通常在千碱基以上的基因组重排 |
| 环调用 | loop calling | 从接触矩阵里判定哪些点是显著环的计算过程 |
| 靶基因 | target gene | 被某调控元件所调控的基因 |
| 组装版本 | assembly | 参考基因组的具体版本，人与鼠分别有多个 |
| 人工策展 | manual curation | 由人逐条核对与补全元数据的过程 |
附录 A：核心数字核对表
| 项 | 值 | 来源 | 来源层级 |
|---|---|---|---|
| 数据集总数 | 823 | 清单接口返回条数 | 官方接口 |
| 人类数据集 | 642 | 按 species 字段计数 | 官方接口 |
| 小鼠数据集 | 150 | 同上 | 官方接口 |
| 大肠杆菌数据集 | 19 | 同上 | 官方接口 |
| 果蝇数据集 | 8 | 同上 | 官方接口 |
| 斑马鱼数据集 | 4 | 同上 | 官方接口 |
| Hi-C 记录 | 596 | 按 dataType 计数 | 官方接口 |
| ChIA-PET 记录 | 74 | 同上 | 官方接口 |
| HiChIP 记录 | 65 | 同上 | 官方接口 |
| Micro-C 记录 | 55 | 同上 | 官方接口 |
| scHi-C 记录 | 12 | 同上 | 官方接口 |
| 全部为 mcool | 是 | 按 formats 字段计数 | 官方接口 |
| 全部已核验 | 是 | 按 verified 字段计数 | 官方接口 |
| 最低分辨率 5kb 的记录 | 587 | 按 resolutions 最小值计数 | 官方接口 |
| 最低分辨率 1kb 及更细 | 80 | 同上 | 官方接口 |
| 缺 DOI 的记录 | 74 | 按 doi 字段空值计数 | 官方接口 |
| 缺细胞类型的记录 | 134 | 按 cellType 字段空值计数 | 官方接口 |
| 支持结构变异的数据集 | 167 | 结构变异清单接口 | 官方接口 |
| 一版论文所述规模 | 三百余套 | 2018 年摘要 | 论文摘要 |
| 二版论文所述规模 | 七百余套 | 2026 年摘要 | 论文摘要 |
| 二版新增数据类型 | 含单细胞与结构变异模块 | 2026 年摘要 | 论文摘要 |
| 体积压缩倍数 | 至少一个数量级 | 2018 年摘要 | 论文摘要 |
| 年份跨度 | 2009 至 2026 | 清单 year 字段 | 官方接口 |
| 记录 id 范围 | 0 至 822 | 清单接口 | 官方接口 |
| 发布机构 | 宾州州立与西北大学 | 论文作者与站点 | 论文摘要 |
| 二版论文 DOI | 10.1093/nar/gkaf1109 | 欧洲 PMC 记录 | 论文摘要 |
| 一版论文 DOI | 10.1186/s13059-018-1519-9 | 欧洲 PMC 记录 | 论文摘要 |
附录 B：数字的来源分层
第一层，官方接口。 数据集总数、各物种条数、各实验类型条数、格式字段、核验标记、分辨率分档、空值条数、结构变异覆盖数、id 范围、年份跨度。这些数字由接口直接返回，可随时重跑复核。重跑方法见 §5.2 的脚本。
第二层，论文摘要。 一版的三百余套规模、专用格式的压缩倍数、二版的七百余套规模与新增功能、两版 DOI 与作者机构。这些数字来自正式发表的摘要文本，未经全文核对；摘要之外的细节（策展流程、环调用参数）不采信。
第三层，未核实。 站点的注册地与运维归属、资助编号、每年新增数据量、接口的可用性承诺或速率限制、策展人员数量、注释与数据之间的更新频率。这些要么需要后台，要么需要长期观测，一律不写具体值。
三层的用法不同：第一层可以写进任何自动化报告；第二层可以写进方法部分但需注明是摘要口径；第三层只能作为定性描述，不能引用为数字。
附录 C：完整参考文献
| 编号 | 条目 | 标识 | 用途 |
|---|---|---|---|
| C1 | Wang Y, Song F, Zhang B, 等. The 3D Genome Browser: a web-based browser for visualizing 3D genome organization and long-range chromatin interactions. Genome Biology. 2018;19:151. | DOI 10.1186/s13059-018-1519-9 | 一版规模、格式压缩倍数、旧入口 |
| C2 | Yu S, Fu Y, Wong JH, 等. The 3D Genome Browser 2.0: an enhanced online platform for visualizing and analyzing 3D genome architecture. Nucleic Acids Research. 2026;54:D48-D54. | DOI 10.1093/nar/gkaf1109 | 二版规模、结构变异模块、现行入口 |
| C3 | 3D Genome Browser 2.0 站点 | https://3dgenome.fsm.northwestern.edu | 接口形态、页面功能、版本沿革 |
| C4 | 数据集清单接口 | https://3dgenome.fsm.northwestern.edu/api/data/datasets | 全部规模与结构数字 |
| C5 | 结构变异数据集清单接口 | https://3dgenome.fsm.northwestern.edu/api/data/sv_datasets | 结构变异覆盖数 |
| C6 | 欧洲 PMC 检索服务 | https://www.ebi.ac.uk/[europepmc](https://www.qianfanghub.com/ai-ready-dataset/europepmc/1353)/webservices/rest/search | 两版论文摘要与 DOI 核对 |
| C7 | 旧域名 | http://3dgenome.org | 重定向核对 |
C1 的 DOI 与用户任务中提供的 gky422 不同。核对结果是：gky422 对应的是一篇氧化亚硫酸氢盐测序方法论文，与本题无关；一版论文的实际 DOI 是上面列出的这一个，二版是 gkaf1109。附录里保留这一句，是为了让后来者不必再踩一次同样的坑。
附录 D：任务代码
全文用到的核对脚本汇总成一段，可直接重跑。
#-- 一次性核对全篇来自接口的数字
import json, urllib.request
from collections import Counter
BASE = "https://3dgenome.fsm.northwestern.edu/api"
def get(path):
with urllib.request.urlopen(BASE + path, timeout=90) as r:
return json.loads(r.read().decode("utf-8"))
d = get("/data/datasets")
print("总数", len(d))
print("物种", Counter(x["species"] for x in d))
print("类型", Counter(x["dataType"] for x in d))
print("格式", Counter(x["formats"] for x in d))
print("核验", Counter(x["verified"] for x in d))
print("无 DOI", sum(1 for x in d if not x["doi"]))
print("无细胞类型", sum(1 for x in d if not x["cellType"]))
print("最低分辨率 <=1000", sum(1 for x in d if x["resolutions"] and min(x["resolutions"]) <= 1000))
print("id 范围", min(x["id"] for x in d), max(x["id"] for x in d))
years = [x["year"] for x in d if x.get("year")]
print("年份范围", int(min(years)), int(max(years)))
sv = get("/data/sv_datasets")
print("结构变异数据集", len(sv))
#-- 越界 id 的行为：返回空对象而非报错
print("越界 id 返回", get("/data/datasets/999999"))
这段脚本的每一行输出，都对应附录 A 里的一行。改动其中任何一处，附录 A 都需要同步。
附录 E：如果只记五件事
- 它卖的是注释不是矩阵。 三级注释开箱可用，矩阵要按坐标取，整包下载里没有矩阵。
- 分辨率是入场券。 5kb 以上谈结构域，5kb 以下才有资格谈环。清单里的最低分辨率字段决定了你能问什么问题。
- 三层结构不能混用。 区室、结构域、环是三个尺度上的三种现象，任何一层都不能替代另一层作论证。
- 格式统一不等于测量统一。 归一化、环调用、边界算法各家不同，跨数据集的强度值不能直接相减，环集合不宜直接取交。
- 它是别人工作的副产品。 能持续是因为研究在继续，不是因为产品在运营。域名会迁移，接口没有文档，脚本要把这两件事当成常态。
编辑说明
核验时间 2026 年 10 月 27 日。核验方式：对 3dgenome.org 与西北大学域名各做一次请求，确认前者 302 跳转至后者且内容一致；从站点前端脚本中反推出 /api 下的端点与参数名，逐个请求核对；对数据集清单、换图、下载、基因检索、结构变异五类接口各做一次真实调用，并记录返回结构与异常行为；从欧洲 PMC 取两篇论文的摘要文本，核对 DOI、作者、卷期与所述规模。
未覆盖的内容：未下载任何完整的接触矩阵，未重跑任何比对或环调用流程，未逐条打开八百余条记录的描述文本做人工比对，未核对站点资助信息与运维归属。站点无公开接口文档，端点与参数名系从前端脚本反推，版本更新后可能变化；本文调用结果均可通过附录 D 的脚本复现。
一处口径差已如实记录：二版论文摘要称逾七百套，清单接口返回八百二十三条，差额约一百条，官方未说明其构成。本文两处并列写出，不做取舍。
禁用词与元话语按体例移出正文，口径说明集中于本区。
相关数据集导航
以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：
- cellsnvreg — 共享标签：基因组学与多组学 / 单细胞基因组学 / 变异与注释
- chrompolymerdb — 共享标签：基因组学与多组学 / 表观基因组 / 单细胞基因组学
- cnascope — 共享标签：基因组学与多组学 / 单细胞基因组学 / 变异与注释
- expression-atlas-legacy — 共享标签：基因组学与多组学 / 单细胞基因组学 / 变异与注释
- expression-atlas — 共享标签：基因组学与多组学 / 单细胞基因组学 / 变异与注释
- liver-cld-scatlas — 共享标签：基因组学与多组学 / 表观基因组 / 单细胞基因组学
- igvf-catalog — 共享标签：基因组学与多组学 / 变异与注释
- clinmave — 共享标签：基因组学与多组学 / 变异与注释
- scperturb — 共享标签：基因组学与多组学 / 表观基因组 / 单细胞基因组学
- rpe-choroid-atlas — 共享标签：基因组学与多组学 / 表观基因组 / 单细胞基因组学
导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。
