信息速览
秀丽隐杆线虫全脑钙成像没有唯一官方库。Flavell 实验室的 WormWideWeb、Kato 等人 2015 年放在 Zenodo 的 NeuroPAL 前身数据集、Nichols 等人 2017 年的多色身份标注数据、以及零散的 NWB 封装，四类来源互不覆盖，也没有任何一个机构在做跨库归并。默认「去官网下载」在这件事上会失败——你搜到的第一份和你需要的第三份，可能来自完全不同的显微镜、不同的品系、不同的行为范式。
本词条写的是其中规模最大、结构最完整、入口最稳定的那一份：WormWideWeb。它覆盖 MIT Picower Institute Flavell 实验室三篇论文的 91 个逐动物数据集，每个数据集是一只自由活动的线虫，包含全脑视野内的神经元钙信号矩阵、同步行为信号、以及可选的神经元身份标注。站点由论文作者自己维护，2019 年疫情期间就开始搭建，2023 年论文发表后转为正式的公共资源，Zenodo 上有版本化的原始归档（截至 2026-04 为 v4）。
一屏速览见下表。
§1 数据集速览：它到底是什么
1.1 一句话定位
WormWideWeb 是一个实验室把「一只虫子的全脑神经活动＋它同时在做的事」打包成可下载文件的地方，一共 91 包。
它要回答的问题不是「线虫的神经网络长什么样」——那是连接组的事；也不是「某个神经元在做什么」——那是单细胞记录的事。它要回答的是：
当一只线虫在培养皿里自由爬行、进食、转向、偶尔停下来的时候，它头部的上百个神经元同时在想什么？这些活动能不能被若干条行为变量解释？
这个问题在脊椎动物身上做不到。小鼠全脑有两亿个神经元，即便用上最新的高密度探针一次也只能采到几万个；猕猴更是天文数字。线虫是唯一一个神经系统小到能被一束光整个照亮、同时又复杂到能表现出觅食、避害、学习、睡眠等完整行为的成年动物。91 个数据集就是在这个尺度上反复做同一件事的产物。
1.2 为什么它不是「又一个神经影像数据集」
假设有人把库内所有脑影像资源摊开，会发现它们绝大多数在做同一类事：测量结构、测量静息态相关、测量任务诱发的位置。它们回答的是「哪里激活了」。WormWideWeb 回答的是另一个层级的问题——个体层面、单细胞层面、逐帧的因果链。
用一张表把差别摆清楚：
| 维度 | 典型哺乳动物脑影像数据集 | WormWideWeb |
|---|---|---|
| 观测单位 | 体素（毫米级）或电极触点 | 单个已分割的神经元（细胞核） |
| 一次观测覆盖比例 | 全脑的极小一部分 | 头部神经节的大部分，约占全部 302 个神经元的 1/3 至 1/2 |
| 时间分辨率 | 秒级（fMRI） | 约 0.6 秒一帧 |
| 行为同步 | 少见，多为离线行为录像 | 逐帧同步的速度、头摆角、角速度、咽泵、转向事件 |
| 个体数 | 数十至数千 | 91 只，但每只有 100-170 个神经元、上千帧 |
| 能否知道每个单元的「名字」 | 通常不知道 | 56 个数据集知道，且带置信度 |
最后一行是这份数据真正的分量所在。在哺乳动物研究里，你的「单元 47 号」换个被试就变成「单元 12 号」，跨个体的单元对应只能靠聚类近似。在线虫里，单元有名字，名字在所有个体、所有实验室、所有论文里都是同一个。这一点让「把 91 只个体的同名神经元对齐后做统计」成为可能——而绝大多数神经科学数据集连这个前提都不具备。
1.3 三十秒决策卡
| 你的处境 | WormWideWeb 能帮你什么 |
|---|---|
| 想验证一个「行为由群体编码表示」的假设 | 每个数据集直接给出上百个神经元、上千帧的活动矩阵与同步行为序列，可立即拟合解码器 |
| 手里有一套神经元分割或配准算法 | 换一批 91 个真实录制做域外测试，比合成数据更接近显微成像的真实退化 |
| 做神经动力学建模，需要真实网络的行为输入 | 行为时间序列与神经活动逐帧对齐，可直接当作外部驱动项 |
| 研究中讨论「功能连接能否预测活动」 | 站点内置连接组视图（引自公开发表的连接组数据），可与活动矩阵做对照 |
| 教科书里要举「全脑同时记录」的例子 | 这是目前唯一能在成年个体上反复做到的体系，且有 3 篇 Cell/Nat Commun 级论文背书 |
| 想找人类疾病模型 | 给不了。线虫没有海马、没有皮层、没有多巴胺能的黑质 |
1.4 明确不适合谁
如果你的需求是「用 302 个神经元的完整网络做全脑级仿真」，WormWideWeb 给不了你完整的 302 个。它记录的是头部神经节视野内的神经元，单帧分割出的 ROI 在 105 到 176 之间，中位 140 个；尾部神经节、腹神经索沿线的运动神经元、以及部分咽部神经元通常不在视野内。
如果你的需求是「结构连接」，去用连接组。WormWideWeb 的连接组视图是对已发表连接组数据的引用与可视化，不是它自己的产出。库内已有的秀丽隐杆线虫连接组资源与此处所写正好构成「结构 vs 功能」的一对参照物。
如果你的需求是「长时程、跨昼夜的慢性记录」，也给不了。单只动物一次录制约 2 到 20 分钟，没有跨天的纵向随访。
1.5 版本时间轴
| 时间 | 事件 | 影响 |
|---|---|---|
| 2021-05 | 最早的一批录制（2021-05-26 场次） | 进入了现在的数据集清单 |
| 2023-07-16 | Zenodo v1 首发，同日 v2 补上 processed_h5.tar.bz2 |
首次让「全部行为-神经原始数据」可下载 |
| 2023-08-21 | Atanas & Kim 等人在 Cell 在线发表 | 数据集获得正式引用锚点 |
| 2023-09-14 | Zenodo 记录「可用日期」 | 记录正式开放 |
| 2026-03-26 | Zenodo v3 增加显微台位置信息 | HDF5 包内含新增字段 |
| 2026-04-02 | Zenodo v4 统一 stage location 键名，补 NeuroPAL 与编码文件 | 与站点 JSON 的字段对齐 |
§2 数据构成与规格
2.1 91 个数据集的完整构成
站点数据集页在 2026-10-29 给出的清单是 91 条，来自三篇论文。按论文拆分：
| 论文 | 数据集数 | NeuroPAL 覆盖 | 编码数据 |
|---|---|---|---|
| Atanas & Kim et al., 2023（Cell） | 68 | 部分（68 中的 40 个） | 有 |
| Dag, Nwabudike & Kang et al., 2023（Cell） | 15 | 部分（15 中的 8 个） | 无 |
| Pradhan & Madan et al., 2025（Nat Commun） | 8 | 全部（8 个） | 无 |
| 合计 | 91 | 56 个 | 40 个 |
按实验类型再拆一次，可以看清这 91 只虫子到底在什么条件下被录的：
| 类型标签 | 数据集数 | 实验条件 |
|---|---|---|
baseline 相关 |
35 | 基线自由爬行，部分叠加 NeuroPAL |
heat 相关 |
30 | 温度刺激下的自由爬行 |
gfp |
3 | 仅表达 GFP 的对照株（无钙指示剂） |
patchEncounter |
7 | 饥饿虫从无食物区遇到食物斑块 |
reFed |
8 | 重新喂食 |
sickness |
8 | 绿脓杆菌 PA14 感染后的活动/静息切换 |
common-neuropal 这个标签在清单里出现 56 次，与「56 个数据集有身份标注」是同一个数，说明 NeuroPAL 标记的可见性本身就是数据集的一个分型维度，而不是事后补的注释。
2.2 逐动物级别的规模数字
| 指标 | 数值 | 说明 |
|---|---|---|
| 单只动物分割到的 ROI 数 | 105 – 176（中位 140） | 站点 n_neuron 字段 |
| 单只动物有身份标注的 ROI 数 | 0 – 127 | 站点 n_labeled 字段 |
| 有标注的数据集 | 56 个 | 其余 35 个只有 ROI 编号 |
| 全部数据集的 ROI 总数 | 12,585 | 91 × 均值，用于估算联合分析规模 |
| 全部数据集的身份标注总数 | 5,189 | 平均每个有标注的数据集约 93 个 |
| 单集帧数 | 200 – 1,615 | max_t 字段，多数数据集落在四位数 |
| 全部数据集帧数合计 | 129,949 | 若按每帧 140 个神经元计，约 1,800 万个神经元-帧 |
| 单集时长 | 约 2 – 20 分钟 | 站点 Length (min) 列 |
| 时长合计 | 约 1.3 千小时 | 站点列相加 |
| 录制日期跨度 | 2021-05 至 2023-05 | 会话编号前缀即日期 |
时长合计那个四位数开头为 1 的值（1,322 小时）看着很吓人，但要理解它的来源：这是把 91 只动物各自的录制长度加在一起。每只只有十几分钟，加起来才到这个数。不要把「合计时长」读成「连续观测时长」——前者是 91 段独立片段的和，后者意味着单只动物被连续追踪了一千多个小时，两者在统计意义上完全不是一回事。做「平均每小时发生几次转向」这类率指标时，分母必须用单集时长逐集计算再加权，直接用总量除会得到错误结论。
2.3 一条记录的逐行解剖
拿清单里排第一的 2023-01-23-01（NeuroPAL 基线）做解剖。它的 JSON 下载包大小约 3.9 MB（bzip2 压缩后，解压约 3.4 MB 量级），打开后是一个扁平字典，六个顶层键：
#-- 读取单只动物的 JSON，输出结构骨架
import json, bz2
with bz2.open("atanas_kim_2023-2023-01-23-01.json.bz2") as f:
d = json.load(f)
print(list(d.keys()))
#--['behavior', 'encoding', 'gcamp', 'label', 'metadata', 'timing']
print(d["metadata"])
#--n_neuron=151, dataset_type=['baseline','neuropal'],
#--paper_id='atanas_kim_2023', source_filename='2023-01-23-01-data.h5'
#--另外还有 4 个 blake3 校验和 + 1 个 HDF5 校验和
print(d["timing"]["max_t"]) # 1600
print(d["timing"]["mean_timestep"]) # 0.6015667310014415
print(len(d["gcamp"]["trace_array"]), len(d["gcamp"]["trace_array"][0]))
#--(151, 1600)
把六个键逐一拆开：
| 键 | 内容 | 形状 / 规模（本数据集） | 用途 |
|---|---|---|---|
metadata |
ROI 数、数据集类型、来源 HDF5 文件名、4 个 blake3 校验和 | 12 个标量 | 溯源与完整性校验 |
timing |
max_t、mean_timestep、timestamp_confocal |
与帧数等长的时间戳（秒） | 建立帧与真实时间轴的映射 |
gcamp.trace_array_original |
每个 ROI 的原始钙信号 | 151 × 帧数 | 需要自行做基线校正时用这个 |
gcamp.trace_array |
逐神经元 z-score 后的信号 | 151 × 帧数 | 大多数分析直接用这个 |
label |
91 条身份标注 | 每条 7 个字段 | 把 ROI 编号变成神经元名字 |
behavior |
速度、头摆角、角速度、咽泵、转向事件 | 4 × 帧数 + 30 段事件 | 解码器的输入/输出 |
encoding |
CePNEM 拟合结果、编码强度、tau、分半一致性 | 多为 151 长向量 | 论文模型的可复现中间结果 |
trace_array 的确是逐行标准化的：抽一个 ROI 出来算，均值约 0、标准差约 1。这意味着跨神经元比振幅是没有意义的，只能比时间形状。要用原始振幅，必须回到 trace_array_original。
2.4 与同类数据的定位差异
| 资源 | 核心内容 | 与 WormWideWeb 的差异 |
|---|---|---|
| WormWideWeb | 91 个逐动物全脑活动集，JSON/HDF5，行为同步 | 唯一把「活动＋行为＋身份标注」打包在一起并持续维护的入口 |
| Kato et al., 2015 配套数据 | 早期全脑钙成像，含神经元身份 | 采集技术更早，行为变量少，无 CePNEM 编码结果 |
| Nichols et al., 2017 配套数据 | 多色身份标注的方法学演示 | 以身份标注为主，逐动物数据集数量少 |
| NeuroPAL 官方代码库 | 身份标注算法与示例 | 是工具不是数据库，数据散落在各论文 |
| OpenWorm 生态 | 连接组、仿真、细胞模型 | 不做新的钙成像采集 |
| 库内秀丽隐杆线虫连接组资源 | 电镜重建的结构连接 | 结构 vs 功能，二者互补 |
一句可操作的判断规则：要活动和行为 → WormWideWeb；要结构连接 → 连接组；要两者串起来 → 用 WormWideWeb 的站点内连接组视图做定性对照，定量对照需自己取连接组原文。
2.5 这批数据能回答哪四类真问题
看一个数据集值不值得用，最省事的判断是看它已经支撑过哪一类结论。WormWideWeb 的 91 个数据集在三篇论文与若干独立研究中，主要支撑了下面四类问题，按被用到的频次排序：
| 问题类型 | 具体问法 | 需要用到哪些字段 | 难度 |
|---|---|---|---|
| 行为解码 | 给定 100 多个神经元的活动，能否预测虫此刻的速度、头摆角、咽泵速率 | gcamp.trace_array + behavior |
低，逻辑回归就够起步 |
| 编码建模 | 给定当前与过去若干秒的行为，能否预测每个神经元的活动 | behavior + encoding.rel_enc_str_* + tau_vals |
中，需要处理延迟与非线性 |
| 状态依赖 | 同一神经元在饥饿、热刺激、感染后，对同一行为的编码是否改变 | encoding.encoding_changing_neurons + 数据集类型标签 |
中，需要跨数据集合并 |
| 结构约束 | 活动上有耦合的两个神经元，在连接组上是否真的连着 | label.neuron_class + 外部连接组 |
高，需要对上两套命名 |
第一类是入门首选。它不需要身份标注，用匿名 ROI 编号就能跑；跑通之后再去用 label 把「单元 41 号」翻译成「AVDL」，立刻能回答更有意义的问题。
第三类是这批数据真正稀缺的地方。绝大多数神经影像数据集只有一种行为条件，没法比较「同一个神经元在不同状态下编码变了没有」。91 个数据集覆盖了基线、热刺激、饥饿遇食物、重新喂食、感染后疾病行为五个条件，而且同一套采集流程、同一台显微镜，这才让状态比较成为可能。
第四类是三条论文的核心论证路径：先用活动找出耦合的神经元对，再回到连接组上检查解剖连接是否支撑这种耦合。能做这件事的前提是神经元名字在功能数据与结构数据里是同一套——这在哺乳动物里几乎不可能，在线虫里是默认。
2.6 为什么只有线虫能做「三合一」的记录
「全脑 + 单细胞分辨率 + 行为同步」这三件事，在脊椎动物里任意两件都做得到，三件同时做到做不到。原因可以拆成三个数量级：
| 障碍 | 哺乳动物的量级 | 线虫的量级 | 差多少 |
|---|---|---|---|
| 神经元数 | 小鼠约 7,000 万 | 雌雄同体 302 | 五个数量级 |
| 单细胞分辨所需的光学条件 | 需要穿透毫米级散射组织 | 头部透明、厚度不足百微米 | 结构上不可比 |
| 行为自由度 | 四肢、躯干、面部、发声 | 在二维平面上爬行，姿态可用骨架曲线描述 | 描述成三个标量加一个事件序列 |
第三行常被忽略，但它其实是决定性的。行为如果不可以被定量描述，「同步记录」就没有意义——你记下了行为，却没法把它变成数字，也就没法拿去和神经活动做回归。线虫研究者之所以能做 CePNEM 这类模型，前提是行为已经被压缩成了速度、头摆角、咽泵速率、转向事件这几个变量。
这也解释了为什么这套方法的成果集中在少数几个实验室：难点不在显微镜，而在「把行为变成量化变量」这一整套软件。ANTSUN 与行为量化代码开源，但把一台自制显微镜从零搭起来、把行为追踪调到可用精度，成本仍然很高。这是数据分散、难以复制的根本原因，也是为什么在可预见的将来，这条支流不会出现「一个官方库」。
§3 第一层：一个数据集文件里到底装了什么
这一层对应的问题是「我拿到一个文件，能不能直接用」。答案是：能，但必须知道四件事——时间轴怎么读、信号怎么归一、行为量的量纲是什么、缺了什么。
3.1 时间轴：为什么帧数换算成秒会差 60 倍
这是拿到这份数据后第一个会绊住人的地方，而且它绊住的方式很特别。
站点的数据集清单里有一个 avg_timestep 字段，本数据集的值是 0.010026112183357359。如果按字面理解成「每帧 10 毫秒」，一集就会被读成 16 秒，而站点表格里 Length (min) 列写的也确实是 16.0。但打开 JSON 看 timing.mean_timestep，同一个概念给的是 0.6015667310014415；再看 timestamp_confocal 相邻值之差，中位数是 0.6000189 秒。
两个数的比值正好是 60.0。
现场核对一下就清楚了：
#-- 用时间戳自己算帧间隔，不要相信任何单一字段
import json, statistics
d = json.load(open("s.json")) # 解压后的 JSON
ts = d["timing"]["timestamp_confocal"]
gaps = [b - a for a, b in zip(ts, ts[1:])]
print(round(statistics.median(gaps), 4)) # 0.6000 秒
print(round((ts[-1] - ts[0]) / 60, 2)) # 16.03 分钟
也就是：这批录制是每约 0.6 秒一帧，单集十几分钟，不是每 10 毫秒一帧的 16 秒高速录制。清单里的 avg_timestep 与站点表格的时长列是同一个口径（分钟制），JSON 里 timing.mean_timestep 与时间戳是秒制，两边相差 60 倍。
这个差别的后果很实际：按 0.6 秒一帧算，奈奎斯特频率约 0.83 Hz。线虫的咽泵在进食时可达每秒数个循环，单帧采样根本跟不上，pumping 通道反映的是包络而不是逐次泵动。做高频行为（如 omega 转向）的对齐分析时，0.6 秒的采样会把动作抹平。
3.2 信号的三种归一化
about/datasets 页明确列了四种信号变体，但 JSON 导出里只出现两种：
| 字段 | 定义 | 何时用 |
|---|---|---|
trace_original |
原始钙信号，未缩放 | 自己想做 ΔF/F 或别的基线校正时 |
trace_array |
逐神经元 z-score | 跨时间比形状、喂给大多数解码器 |
trace_array_F20 |
以第 20 百分位归一 | 只在 HDF5 完整包里有 |
trace_array_Fmean |
以均值归一 | 只在 HDF5 完整包里应有 |
JSON 导出省略了后两种。如果你的论文复现要求 F20 归一，得回到 processed_h5.tar.bz2。
3.3 行为量的量纲
官方页面把量纲写得很细，但单位很容易看漏：
| 字段 | 含义 | 单位 | 备注 |
|---|---|---|---|
velocity |
爬行速度 | 0.1 毫米/秒 | 注意前缀是 0.1，不是毫米/秒 |
head_angle |
头部弯曲信号 | 弧度 | 与 angular_velocity 共用符号约定 |
angular_velocity |
角速度 | 弧度/秒 | 同上 |
pumping |
咽泵速率 | 次/秒 | 部分数据集没有这个通道 |
reversal_events |
转向事件 | 帧区间 [start, end] |
是帧号不是时间戳 |
速度的单位是 0.1 毫米/秒这件事有陷阱：把它和美国国家生物技术信息中心文献里常见的「毫米/秒」直接比，会差 10 倍。数据里 0.098 这个值意味着 0.0098 毫米/秒，几乎静止。
reversal_events 存的是帧区间而不是时间戳。要换算成秒，得用 timestamp_confocal 去索引：
#-- 把帧区间的转向事件换算成秒
ts = d["timing"]["timestamp_confocal"]
events = d["behavior"]["reversal_events"] # 例：[[12,28],[61,69],[124,145]]
in_seconds = [(ts[s], ts[e]) for s, e in events]
print(round(in_seconds[0][1] - in_seconds[0][0], 2)) # 约 9.6 秒
3.4 缺了什么
一个 151 个 ROI 的数据集里，只有 91 个 ROI 有名字。剩下 60 个 ROI 有干净的时间序列，但没人知道它们是哪些神经元。这一点在设计任何「跨个体对齐」的分析时都是决定性的：能对齐的只有那 91 个，剩下的 60 个只能当作匿名单元处理。
label 里的 region 字段在本数据集里全部是 None。字段存在但未填充，说明这是为未来版本预留的位置，不能当作「位置信息丢失」来读。
§4 第二层：神经元身份标注的可信度
这一层对应的问题是「我能不能相信这些名字」。答案是：能，但要分层信，而且必须读 confidence。
4.1 为什么身份标注是这份数据最难的部分
在哺乳动物里，说「神经元 X 在活动」需要一个前提——你得先证明这个神经元是 X。这个证明靠解剖位置、投射靶区、基因表达三者之一或组合，在活体里做起来非常昂贵。
线虫研究走了一条不同的路。2013 年之后发展出的方法是在同一只虫子里同时表达多个荧光蛋白，让每个神经元因为表达组合不同而呈现不同的颜色，然后从颜色反推身份。这套思路在 2021 年被系统化成 NeuroPAL，用一张「颜色指纹表」把每个神经元唯一确定下来。
WormWideWeb 的 56 个带标注数据集用的就是这套方法。但方法本身有不确定性，所以每条标注都带一个 confidence 分数。本数据集 91 条标注里，3 分 39 条、4 分 33 条、5 分 19 条。
注意没有 1 分和 2 分。这不是因为低置信度的标注不存在，而是因为它们没有被写进导出文件——一个 ROI 如果标不出来，就干脆不标，而不是标一个「低置信度的猜测」。这意味着「没有标注」和「标注错了」在这里是两种不同的失败模式：
| 情况 | 表现 | 后果 |
|---|---|---|
| 未被标注 | label 里没有这个 ROI 的键 |
该 ROI 只能当匿名单元用，不会被误当成某个神经元 |
| 低置信度被丢弃 | 同上，但原因不同 | 你无法区分「没测到」与「测到了但不确定」 |
| 标了但错了 | 有键，但名字错 | 跨个体对齐时引入系统性错误 |
第三种情况是最危险的，而 confidence 只能部分缓解它。
4.2 一条标注记录的字段
#-- 看单条身份标注的全部字段
print(d["label"]["100"])
#--{'DV': 'undefined',
#-- 'LR': 'L',
#-- 'confidence': 4.0,
#-- 'label': 'AVDL',
#-- 'neuron_class': 'AVD',
#-- 'region': None,
#-- 'roi_id': [41]}
七个字段，每个都有讲究：
label是完整名字，含左右侧与编号，如AVDL。neuron_class是类别，去掉左右与编号，如AVD。同一个类别的左右两只在这个字段里是同一个值，这是做「类水平」分析时的正确主键。LR是左右侧，取值L/R/undefined。本数据集 43 个 L、37 个 R、7 个 undefined。undefined的 7 条说明有 7 个神经元确实无法判定左右——通常是中线神经元，如 RIP、AVG 这类。DV是背腹侧，本数据集几乎全是undefined，这一维在实践中没被用起来。confidence是 3/4/5 的离散分数，不是概率。roi_id是列表，不是一个数。列表里多个元素意味着这一条标注合并了多个 ROI（例如同一个神经元在视野里被分成两块，或相邻两帧的 ROI 断裂后合并）。region全空。
91 条标注只对应 90 个唯一名字、51 个唯一类别。91 - 90 = 1 说明有一个名字被标了两次（可能是一个严重分裂的 ROI 被两条记录描述）；90 个名字对应 51 个类别，说明大部分是左右成对出现的中线外神经元。
4.3 用 roi_id 做主键的坑
roi_id 是列表，这意味着它不能直接当主键。要做「名字 → 时间序列」的映射，必须先展平：
#-- 展平 roi_id 列表，建 ROI 索引到名字的映射
roi_to_label = {}
for key, rec in d["label"].items():
name = rec["label"]
conf = rec["confidence"]
for rid in rec["roi_id"]: # 列表，可能多个
roi_to_label[rid] = (name, conf)
print(len(roi_to_label), "个 ROI 有名字")
#--若出现同一 rid 被两条标注引用，后写入的会覆盖前者
如果展平后总数小于 sum(len(v["roi_id"]) for v in d["label"].values())，说明有 ROI 被重复引用，必须回头处理冲突，否则静默覆盖。
4.4 CePNEM：从「名字」到「这个名字在编码什么」
身份标注解决「这是谁」，encoding 块解决「它管什么」。
CePNEM 是论文提出的概率编码模型。思路是把每个神经元的活动建模为若干行为变量的函数，其中每个行为变量带一个时间常数 τ，允许不同神经元对同一行为有不同的积分窗口。拟合结果是每个神经元对每个行为变量的「相对编码强度」，取值在 0 到 1 之间。
本数据集的 encoding 块里有：
| 字段 | 含义 | 规模 |
|---|---|---|
dorsalness / forwardness / feedingness |
三个主行为轴的编码强度 | 各 151 长向量 |
rel_enc_str_P / rel_enc_str_v / rel_enc_str_θh |
咽泵、速度、头摆角的相对编码强度 | 各 151 长向量 |
tau_vals |
每个神经元对每类行为的最优时间常数 | 151 长向量 |
encoding_changing_neurons |
两半数据间编码显著变化的神经元索引 | 26 个 |
ranges |
拟合用的两段区间 | [[1,801],[800,1600]] |
neuron_categorization |
按编码类型的分组 | 两个半段各一份 |
ranges 是 [[1,801],[800,1600]]，两段在 800 附近重叠一帧。这是有意的：分半比较用的是前后两个半段，重叠一帧保证边界不会空。做分半一致性分析时必须按这个边界切，不能自己取 1:800 / 801:1600，否则和论文的 encoding_changing_neurons 对不上。
4.5 身份层与结构层怎么对接
站点内置了连接组视图，数据来源是 Witvliet 等人 2021 年的发育期连接组与 Cook 等人 2020 年的咽部连接组。这个视图的作用是：给定一组有名字的神经元，直接看它们在解剖上的连接关系。
但要说清楚：这是引用，不是 WormWideWeb 自己的数据。它把已发表的连接组数据导进来做可视化，方便用户在同一个界面里对照「活动上相关的两个神经元，在结构上是不是真的连着」。
库内已有的秀丽隐杆线虫连接组资源提供的是结构层的完整数据，二者互补：一个给「线连成什么样」，一个给「线在动的时候长什么样」。
§5 第三层：怎么把数据拿到本地
这一层对应的问题是「我怎么下载、下哪个、下多少」。这层有一处真实的工程障碍：下载端点不是直链。
5.1 四条取数路径
| 路径 | 适用场景 | 代价 |
|---|---|---|
| 站点逐数据集 JSON | 只要一两只虫、只要活动和行为 | 每个 3-8 MB，秒级 |
| 站点按论文打包 JSON | 要一整篇论文的全部数据集 | Atanas & Kim 2023 约 18.3 MB |
Zenodo processed_h5.tar.bz2 |
要 F20/Fmean 归一、要项目内部字段 | 568.8 MB |
| Zenodo 完整记录 | 要模型拟合结果、网络权重、UMAP 投影 | 33.0 GB，其中 fit_results 与 relative_encoding_strength 各占十几 GB |
一条经验：做解码或动力学分析的，99% 的情况只需要第一或第二条。完整记录里的 33 GB 主要是贝叶斯拟合的后验样本，除了要重跑 CePNEM 或要复现论文图 2 一类的分析，用不上。
5.2 下载端点：302 到签名 URL，且签名会过期
这是研究中真实踩到的第一个障碍。
数据集页上每一个下载按钮都指向一个形如 /activity/api/data/download/<dataset_id>/ 的地址。直接访问这个地址，服务器返回 302，跳转到 Google Cloud Storage 上的签名 URL，签名附带 X-Goog-Expires=600，即十分钟后失效。
直接拿这个存储地址去 HEAD 或复用，会返回 403。原因是签名 URL 只管一次拿取，不带端点自行续签。
#-- 正确做法：让 curl 跟随重定向，一次拿完
curl -L --max-time 300 \
"https://wormwideweb.org/activity/api/data/download/atanas_kim_2023-2023-01-23-01/" \
-o one.json.bz2
bunzip2 -t one.json.bz2 && echo "完整"
第二个障碍在 --max-time 上。第一遍尝试用了 90 秒的超时，文件下载到约 3.4 MB 时被 curl 主动截断，bunzip2 报 Compressed file ends unexpectedly。这个报错看起来像文件损坏，实际是本地截断。同一地址重下、超时放宽到 150 秒，拿到完整大小后校验通过。
判据是下载大小：同一个数据集两次下载，大小必须一致；不一致就是被截断了。用 -w "%{size_download}" 打印实际字节数可以立刻看出来。
5.3 按论文整批下载
整篇论文的归档走 paper/<paper_id>/ 路径，文件名是把所有数据集压成一个 bz2。三个 paper_id 分别是 atanas_kim_2023、dag_nwabudike_kang_2023、pradhan_madan_2025。
整批归档同样受 600 秒签名限制，但文件更大（18 MB 量级）。慢速网络下仍可能截断，校验方式相同。
5.4 清单 CSV：比猜字段更可靠
有一个容易被忽略但很有用的文件——GitHub 上的 activity/raw/atanas_kim_2023.csv，68 行，每行一只虫，列是：
filename, checksum, uid, θh_pos_is_ventral, label, type, event, t_range
θh_pos_is_ventral 这一列是符号校正开关，必须读。原因在下一节。
5.5 三个论文归档的许可并不一致
这是第二个真实障碍，而且它直接影响能不能用。
| Zenodo 记录 | 内容 | 许可证字段 |
|---|---|---|
8185377（v2，2023-07-16） |
该项目的主归档，含 processed_h5.tar.bz2 |
cc-by-3.0-us |
19388374（v4，2026-04-02） |
当前版本，17 个文件，33.0 GB | 空 |
19414639（Dag 等，血清素数据集） |
15 个数据集对应的源数据 | 空 |
19511989（Pradhan & Madan 等，疾病行为数据集） |
8 个数据集对应的源数据 | cc-by-4.0 |
同一个项目，v2 明示 CC-BY-3.0-US，v4 的许可证字段是空的，另一个相关记录明示 CC-BY-4.0，还有一个是空的。三个记录三种状态。
实践中该怎么办：以 v2 的明示许可为最强证据，同时保留 v4 的 DOI 作为引用锚点，并且在任何再分发之前把两个 DOI 都记下来。如果所在机构对许可链条要求严格，需要直接联系作者确认，不能只凭「以前是 CC-BY」推断「现在也是」。
5.6 站点没有公开 API 文档
/activity/api/ 返回 404。站点的取数接口是网页前端用的内部端点，字段说明分散在 GitHub 的 dataset_json_readme.md 与 about 页里。这意味着没有 OpenAPI 规范、没有稳定的版本化约定，端点路径未来可能变化。做自动化采集时应把端点路径做成配置项，而不是硬编码。
5.7 头摆角的符号：必须逐数据集校正
线虫用左右两侧爬行，同一侧朝上的不同个体，观测到的弯曲方向在背腹语义上会映射反了。所以 head_angle 与 angular_velocity 的符号需要按数据集校正：
#-- 原始 HDF5 工作流中的符号校正；JSON 已完成，不要重复施加
import csv
flags = {r["uid"]: r["θh_pos_is_ventral"] == "true"
for r in csv.DictReader(open("atanas_kim_2023.csv"))}
dv_correction = -1 if flags[uid] else 1
head_angle_corrected = [a * dv_correction for a in head_angle]
68 个数据集里 56 个是 true、12 个是 false。不校正的后果是：把 12 个 false 的数据集混进群体分析，头摆角与转向方向的相关性会被系统性削弱，而单看某个数据集的图又完全正常，极难察觉。
§6 库内定位与边界
6.1 与库内六个神经方向资源的关系
| 库内资源 | 层次 | 与本篇的关系 |
|---|---|---|
| IBL brain-wide map | 哺乳动物、多实验室、电极记录 | 同样是「全脑」，但是小鼠、多实验室、毫秒级电生理；WormWideWeb 是单实验室、0.6 秒级光学 |
| DANDI Archive | 通用 NWB 归档 | 这批数据不在 DANDI 里，走 Zenodo 与自有站点，说明 NWB 化并未覆盖这条支流 |
| NeuroVault | 已发表结果的统计图 | 存的是 z 图，不是逐帧活动；二者不在一个观测层级 |
| Allen Cell Imaging | 单细胞结构影像 | 结构 vs 功能；WormWideWeb 测的是钙信号随时间的变化 |
| NUCMM | 电镜神经元核实例分割 | 分割任务相似但模态不同：一个在电镜体积上分割核，一个在活体荧光上分割细胞 |
| Calcium Imaging Sleep State | 小鼠钙成像与睡眠分期 | 方法同族（钙成像），物种、脑区、任务完全不同 |
6.2 与秀丽隐杆线虫连接组资源的「结构 vs 功能」对照
库内已有一份秀丽隐杆线虫连接组资源，写的是电镜重建的突触级连接。这两条放在一起，构成一个完整的论证链：
- 连接组回答「谁连谁、几条突触、方向如何」，是静态的、确定性的、可数的。
- WormWideWeb 回答「在某个具体时刻、某只具体个体上，这些被连起来的单元同时在做什么」，是动态的、概率的、有噪声的。
单看任何一边都会得出片面的结论。只看连接组，会以为「线连了就该一起活动」；只看活动，会以为「一起活动就是连着的」。把两边放在一起，才能看出功能连接与结构连接之间有多大差距——而这正是这批数据最有价值的地方之一。
6.3 与 SpikeInterface 的分工
SpikeInterface 处理的是胞外电生理的脉冲排序。WormWideWeb 处理的是光学钙信号。两者共享的问题结构（多通道时间序列、单元识别、跨单元对齐），但方法不通用：钙信号的上升-衰减时间常数是秒级，脉冲是毫秒级，时间尺度和噪声模型完全不同。把 SpikeInterface 的 sorter 直接套到钙信号上不会有效果。
6.4 与小鼠细胞图谱一类单细胞数据的区别
单细胞转录组测到的也是「一个个细胞」，但测的是表达谱，是一次性的快照。WormWideWeb 测的也是「一个个细胞」，但测的是同一个细胞在上千个时间点上的连续变化。一个是横截面，一个是时间序列。在需要「同一单元跨时间的因果结构」的任务上，后者不可替代。
6.5 与其他模态「全脑记录」的分工表
| 模态 | 典型资源 | 空间粒度 | 时间粒度 | 覆盖比例 | 是否知道单元身份 |
|---|---|---|---|---|---|
| 钙成像（光学） | WormWideWeb | 单个神经元核 | 约 0.6 秒 | 头部视野大部分 | 部分知道 |
| 电极阵列（电生理） | IBL 一类多探针记录 | 单个神经元（由脉冲波形聚类） | 毫秒 | 探针覆盖区域 | 一般不知道 |
| 功能性磁共振 | NeuroVault 一类的影像集 | 毫米级体素 | 秒 | 全脑 | 不可能知道 |
| 结构成像（电镜） | 连接组一类重建 | 纳米级突触 | 静态 | 全脑可完整 | 完全知道 |
| 结果统计图 | NeuroVault | 体素 | 静态 | 全脑 | 不可能知道 |
这张表读出来的结论是：没有任何一行同时满足「全脑＋单细胞＋毫秒＋已知身份」。WormWideWeb 在「已知身份」与「全脑」上占优，但在时间粒度上输给电生理；电生理在时间粒度上占优，但在身份上输给线虫。这也是为什么线虫与小鼠两条线路不能互相替代——它们各自补齐了对方的短板，也各自带着对方没有的短板。
§7 质量评估与已知局限
7.0 阅读本节前需要知道的一件事
这批数据不该用「数据集质量」的标准评价，而该用「实验记录质量」的标准评价。
原因是：它不是从一个大池子里抽样出来的，而是 91 次独立实验的记录。每次实验有自己的一次性条件——当天的湿度、虫龄的微小差异、培养皿的批次、操作者。这些差异不会出现在任何元数据字段里，却会实打实影响信号。
所以下面讨论的「偏倚」「噪声」「一致性」，都不是缺陷清单，而是使用这批数据时必须带入的假设。批评它「样本量小」是没有意义的——91 只虫子，每只上千帧、每帧 140 个单元，信息量在另一个维度上。
评价框架的第二处错位是把它当「训练集」。它没有官方划分。它更适合被当作评测集或验证集：你的模型在一批录制上训练，在另一批录制上验证，关键不是拟合得好，而是跨个体、跨实验条件、跨记录日期是否还能成立。
7.1 已知偏倚
| 类型 | 描述 | 严重程度 | 缓解 |
|---|---|---|---|
| 单实验室 | 91 个数据集全部来自 MIT Flavell 实验室 | 高 | 与 Kato、Nichols 等外部数据交叉验证 |
| 单一显微系统 | 同一套自制宽场显微镜与配准流程 | 中 | 承认它是「这个成像系统的表征」而非「线虫神经活动的全部」 |
| 品系集中 | 少数几个转基因株，含 lite-1、gur-3 突变背景 |
高 | 注意突变背景本身可能改变行为与光反应 |
| 性别单一 | 全部为雌雄同体 | 中 | 雄虫行为与神经系统不同，结论不可外推 |
| 日期集中 | 2021-05 至 2023-05 | 中 | 不存在跨年份漂移，但也无法评估季节效应 |
| 条件不均衡 | baseline 35、heat 30、GFP 3、food 相关 15、sickness 8 | 中 | 做条件比较时注意 GFP 组只有 3 个 |
| 标注不均衡 | 56/91 有身份标注 | 高 | 只做「有标注」的子集时明确排除其余 35 个 |
| 视野截断 | 只覆盖头部神经节 | 高 | 任何「全脑」结论都需限定为「头部视野内」 |
7.2 标注质量
NeuroPAL 的标注有 confidence 三级（3/4/5），本数据集分布是 39 / 33 / 19。没有低置信度等级被保留下来，说明导出时做了过滤。这个过滤本身是好的（避免把错误标注混进来），但代价是用户无法区分「这个神经元没测到」与「测到了但不确定」。
一个可操作的建议：做跨个体对齐时，只保留 confidence ≥ 4 的标注，把 3 分的当作匿名单元。本数据集 91 条里 4 分以上有 52 条，足够做严谨的类水平分析。
7.3 泛化性
| 场景 | 失效风险 | 证据 |
|---|---|---|
| 跨个体迁移（在 A 训练、在 B 测试） | 中：同名神经元的活动统计特性个体间有差异 | 站点提供 encoding_changing_neurons，说明编码本身在不同分半间会变 |
| 跨记录日期迁移 | 中低：同一实验范式跨月的差异未见系统报告 | 日期跨度两年，机制上应存在 |
| 跨实验条件迁移（baseline → heat） | 高：温度刺激会改变整体活动水平 | 30 个 heat 数据集与 35 个 baseline 数据集可分 |
| 跨品系迁移（GCaMP 株 → GFP 株） | 极高：GFP 株没有钙指示剂，信号语义完全不同 | 3 个 gfp 数据集是对照，不是同分布样本 |
| 跨物种迁移 | 极高：线虫神经系统结构与哺乳动物不可比 | 302 个神经元 vs 两亿，无对应关系 |
| 跨成像系统迁移 | 高：分割器在小鼠钙成像上训练的模型未必适配 | 站点无外部系统数据 |
7.4 伦理与合规
研究对象是无脊椎动物，不涉及人类受试者保护框架。主要合规问题是数据再分发的许可链条，见 §5.5。三个 Zenodo 记录的许可证字段不一致，是使用前必须自行确认的点。
7.5 公平性
不适用于人群公平性。若讨论「代表性公平」，可从物种层面看：这批数据代表的是一个实验室对一个物种的一个发育阶段、一个性别、一种培养条件的研究，不代表线虫行为学的全部。
7.6 数据漂移
站点没有发布过跨版本的统计对比。v1 到 v4 的变化是追加（增加 processed_h5、增加 stage location、统一键名），没有出现删除或重算的公开记录。这意味着旧版本分析的结果在新版本上应当保持兼容，但仍建议在论文中固定 DOI 的具体版本号。
7.7 DAIMS 24 项评估
DAIMS（Data and Information Management System，数据与信息管理体系）是英国生物样本库一类大型队列提出的数据成熟度评估框架，这里借用它的 24 个检查项来给这批数据定位。
| # | 检查项 | 状态 | 说明 |
|---|---|---|---|
| 1 | 宽格式 | ✅ | 每个神经元一列、每个时间点一行，可直接进 pandas.DataFrame |
| 2 | 唯一标识 | ✅ | dataset_id 全局唯一；roi_id 在数据集内唯一 |
| 3 | 特殊字符 | ⚠️ | 清单 CSV 列名含希腊字母 θ，部分工具链读取会报编码错误 |
| 4 | 重复行 | ⚠️ | 91 条标注对应 90 个唯一名字，存在一条重复标注 |
| 5 | 缺失编码 | ✅ | 未标注 ROI 不出现键，而非填 NaN；语义清晰 |
| 6 | 标签标识 | ✅ | label 与 neuron_class 双层，左右与类别分开 |
| 7 | 罕见类分组 | ⚠️ | 51 个类别中有若干仅出现一两次，直接做分类会严重不平衡 |
| 8 | 偏倚评估 | ⚠️ | 站点未发布偏倚分析，需自行评估 |
| 9 | 数据字典 | ⚠️ | 字段说明在 about/datasets 页与 GitHub readme，无机器可读字典 |
| 10 | 信息性缺失解释 | ✅ | LR=undefined 的 7 条对应中线神经元，是有意义的缺失 |
| 11 | 设备记录 | ⚠️ | 记录了显微镜与成像模态，无逐数据集设备参数 |
| 12 | 共线性 | ❌ | 行为变量间（速度与角速度、头摆角）天然相关，站点未提供共线性诊断 |
| 13 | 编码映射 | ✅ | 神经元名与连接组命名同源，可对接 |
| 14 | 时间戳处理 | ✅ | 提供逐帧 timestamp_confocal，可直接换算绝对时间 |
| 15 | 划分建议 | ❌ | 无任何官方训练/验证划分 |
| 16 | 泄漏讨论 | ❌ | 站点未讨论跨数据集泄漏风险 |
| 17 | 标签分布 | ✅ | 站点公示 n_labeled，可自行统计 |
| 18 | 测量偏倚 | ⚠️ | 钙信号的动力学平滑会低估快速事件 |
| 19 | 外部验证建议 | ❌ | 未给出与外部数据交叉验证的协议 |
| 20 | 版本记录 | ✅ | Zenodo 四个版本，变更说明清楚 |
| 21 | 预处理脚本 | ✅ | ANTSUN、CePNEM、WormWideWebData.jl 全部开源 |
| 22 | 合规要求 | ⚠️ | 许可链条跨记录不一致，见 §5.5 |
| 23 | 多模态对齐 | ✅ | 钙信号与行为逐帧对齐，reversal_events 用帧号索引 |
| 24 | 去标识化 | ✅ | 不涉及人类数据；会话编号仅含日期 |
DAIMS 评分：15.5 / 24
评分解读：得分主要由三类项目拉低。第一类是「平台没做」的项目——划分建议、泄漏讨论、外部验证协议（#15、#16、#19），这三项都是评测集常见缺口，不代表数据本身有问题。第二类是「信息散落」——数据字典、设备记录、偏倚评估（#8、#9、#11），信息其实存在，只是分布在网页、GitHub、论文三处，没有集中成机器可读的元数据。第三类是「固有属性」——共线性（#12）是行为变量本身的性质，不是可以修补的缺陷。
加分项集中在溯源与可复现：唯一标识、时间戳、版本记录、预处理脚本四项都是满分，这对一个学术实验室的自建站点来说相当罕见。
对你意味着什么：
- 不要等官方划分，自己按录制日期或实验条件做留出。跨日期留出比随机留出更能反映真实泛化能力。
- 读字段前先读
about/datasets页和 GitHub 的dataset_json_readme.md，两处加起来才完整。 - 做行为-神经联合分析前先算一遍行为变量之间的相关矩阵，共线性问题站点不会替你处理。
- 有许可敏感的场景，同时引用 v2 与 v4 两个 DOI，并把许可状态写进数据说明书。
7.8 外部验证
| 外部场景 | 来源 | 评估任务 | 关键发现 |
|---|---|---|---|
| 连接组约束下的动力学模型 | 论文自身 | 用连接组连接强度作为先验，预测活动 | 编码映射可落到连接组上，形成「编码图谱」 |
| 前运动神经元网络的重建 | 第三方 PLOS Comput Biol 论文 | 用 22 个数据集驱动一个生物约束网络模型 | 单组参数可复现多个数据集的核心神经元活动 |
| 跨实验室交叉验证 | 尚无公开结果 | — | 站点未发布跨实验室一致性评估 |
第三方研究能用同一批数据驱动出可复现的网络模型，是这批数据外部效度的一个旁证。但它同时说明：能复现的前提是用了多个数据集。单数据集上的拟合结果不具代表性。
§8 生态、版本与可持续性
8.1 版本节奏
| 版本 | 日期 | 变更 |
|---|---|---|
| v1 | 2023-07-16 | 原始发布 |
| v2 | 2023-07-16 | 增加 processed_h5.tar.bz2（行为-神经完整数据） |
| v3 | 2026-03-26 | 增加 stage location 信息 |
| v4 | 2026-04-02 | 统一 stage location 键名；补 NeuroPAL 与编码文件 |
节奏不规律：v1 与 v2 同日，v3 与 v2 相隔近三年。这不是一个按季度迭代的资源，而是跟着论文与项目进展走的学术资源。
8.2 生态位
| 资源 | 类型 | 与 WormWideWeb 的分工 |
|---|---|---|
| WormWideWeb 站点 | 交互式浏览与单集下载 | 首选入口 |
Zenodo 19388374 |
版本化归档 | 引用锚点与完整包 |
GitHub WormWideWeb |
站点代码 | 前端与 API 实现 |
GitHub WormWideWebData.jl |
JSON 生成工具 | 从 HDF5 重建 JSON |
GitHub AtanasKim-Cell2023 |
ANTSUN / CePNEM / 显微镜控制 | 全流程复现 |
Zenodo 8185377 |
v2 记录 | CC-BY-3.0-US 的明示证据 |
8.3 引用应该引哪个
Zenodo v4 记录里有一句很明确的指示：引用论文，不要引用这个仓库。原话是「please refer to Atanas & Kim et al., 2023 below. Please cite the paper directly and DO NOT cite this repository」。
这是一个不常见的约定。大多数数据集的惯例是先引数据记录再引论文，这里反过来。实践中的安全做法是两者都引：论文作为学术引用，Zenodo DOI 作为数据可用性声明，并在方法节注明版本号。
8.4 它为什么存在，靠什么活着
要理解这份数据为什么值得信，得知道它从哪来。
Flavell 实验室在本世纪初开始做线虫行为与神经肽的研究，一度使用固定设备加离线行为分析。真正的转折点是他们决定自己造一台能同时「看全脑活动」和「看全部行为」的显微镜——这个决定在当时并不显然，因为自制显微镜意味着所有软件也得自己写：分割、配准、细胞追踪、行为量化，每一块都是一个独立工程。
NeuroPAL 在 2021 年成熟后，身份标注这块拼图补齐了。于是有了一个问题：这些数据该放在哪里？放 Zenodo 能存档，但没法「按神经元名检索数据集」；自己建库能做到，但要长期维护。
最后的选择是两者都做：Zenodo 做存档，自建站点做检索。这个组合的好处是存档与检索解耦——站点挂了数据还在，Zenodo 挂了 DOI 仍然解析。代价是维护成本翻倍，而且要靠论文作者的持续投入。
可持续性的真实来源不是经费，而是下游依赖。一旦有第三方论文用这批数据训练模型、做基准、构建理论，它就变成了别人研究的基础设施，作者不维护会有明显的社会成本。目前至少有一篇独立的 PLOS Computational Biology 论文把它作为 22 个数据集的来源，这是依赖形成的早期信号。
8.5 社区活跃度
站点没有公开的 issue 追踪与讨论区。GitHub 上的 WormWideWeb 与 AtanasKim-Cell2023 是主要的技术接口。数据集清单 CSV 放在独立的 WormWideWeb-data 仓库，说明数据元信息与站点代码是分开维护的——这是一个好习惯，但也意味着元信息更新的可见性依赖于单独的 commit。
8.6 如果哪天站点下线了怎么办
这是使用任何自建学术资源都该问的问题。对 WormWideWeb，答案分三层：
第一层是可恢复性。 91 个数据集的 JSON 全部由 HDF5 生成，生成工具 WormWideWebData.jl 开源。只要 Zenodo 上的 processed_h5.tar.bz2 还在，理论上就能重建全部 JSON。这是「数据不依赖站点存活」的典型设计。
第二层是引用可解析性。 Zenodo 的 DOI 体系由 DataCite 与 CERN 共同支撑，比单站点稳定得多。即便站点消失，DOI 仍能指向档案。
第三层是检索能力的不可恢复部分。 站点的价值不只是存文件，还有「按神经元名找数据集」「连接组叠加视图」这些交互能力。这些能力在站点下线后无法从档案恢复，因为没有第二家做过同样的索引。这一层才是真正稀缺的部分。
对使用者的实际含义：导出并本地保存一份 JSON 与清单 CSV 的成本极低（全部 Atanas & Kim 2023 数据集打包约 18 MB），而一旦需要重新构建检索，成本是另一回事。做长期项目时，把这两个文件纳入项目的依赖清单、跟着代码一起版本化，是最省事的风险对冲。
§9 使用指引与最小实现
9.1 三种角色的路径
| 角色 | 起点 | 关键动作 |
|---|---|---|
| 想快速看看数据长什么样 | 站点「Neural Activity」页的交互图 | 选 1 个数据集、2-3 个神经元类，先看波形与行为的关系 |
| 要做解码/编码建模 | 论文归档的 JSON 整包 | 先按日期分训练与测试，再统一 z-score 口径 |
| 要做方法学（分割/配准） | Zenodo 的 processed_h5.tar.bz2 |
用原始 HDF5 做域外测试，避免用已处理 JSON 虚高分数 |
9.2 最小可运行：把一只虫变成可训练的张量
#-- 依赖：numpy、bz2（标准库）
#-- 输入目录预期：
#-- data_root/
#-- atanas_kim_2023-2023-01-23-01.json.bz2
#-- atanas_kim_2023-2022-06-14-01.json.bz2
#-- 每个文件是一只虫；输出 X: (n_roi, n_frame) 的 float32
import bz2, glob, json, os
import numpy as np
def load_one(path):
with bz2.open(path) as f:
d = json.load(f)
X = np.asarray(d["gcamp"]["trace_array"], dtype=np.float32) # z-score 版
ts = np.asarray(d["timing"]["timestamp_confocal"], dtype=np.float64)
name = d["metadata"]["uid"]
return name, X, ts
root = "data_root"
bundles = {}
for p in sorted(glob.glob(os.path.join(root, "*.json.bz2"))):
name, X, ts = load_one(p)
bundles[name] = (X, ts)
print(f"{name} roi={X.shape[0]} frame={X.shape[1]} span={ts[-1]-ts[0]:.1f}s")
这段代码做的三件事都是必要的：读 trace_array（不是 trace_array_original，除非你要自己归一）、读时间戳（不是靠帧数推算时长）、按 uid 命名（避免把不同日期的同名数据集混在一起）。
9.3 跨个体对齐的最小实现
#-- 只有 confidence >= 4 的标注才进入对齐
#-- 输出：class_name -> (n_animal, n_frame) 的堆叠矩阵
import numpy as np
MIN_CONF = 4.0
def stack_by_class(bundles, min_conf=MIN_CONF):
acc = {}
for uid, (X, ts) in bundles.items():
with bz2.open(f"data_root/atanas_kim_2023-{uid}.json.bz2") as f:
d = json.load(f)
for rec in d["label"].values():
if rec["confidence"] < min_conf:
continue
cls = rec["neuron_class"]
for rid in rec["roi_id"]:
if rid < X.shape[0]:
acc.setdefault(cls, []).append(X[rid])
#-- 不同个体帧数不一，按最短长度截断后再堆叠
out = {}
for cls, rows in acc.items():
L = min(len(r) for r in rows)
out[cls] = np.stack([r[:L] for r in rows])
return out
关键点是两处：confidence 过滤与帧长截断。前者避免把不确定的标注当成事实，后者避免因为个别数据集只有 200 帧而报形状错误。
9.4 训练/验证的分层切分
没有官方划分，sklearn 的 GroupKFold 是最省事的做法，分组键取录制日期：
#-- 按录制日期分组，保证同一批实验的虫不会同时出现在训练与验证
#-- 1 个汉字核要 60 秒采样，同一天的实验共享同一次校准
import re
from sklearn.model_selection import GroupKFold
uids = list(bundles.keys())
groups = [re.match(r"(\d{4}-\d{2}-\d{2})", u).group(1) for u in uids]
gkf = GroupKFold(n_splits=5)
for tr, va in gkf.split(uids, groups=groups):
print(len(tr), "训练 /", len(va), "验证")
日期作为分组键的理由是：同一天的多只虫子共享同一套显微镜校准、同批培养皿、同一操作者。随机切分会让验证集与训练集共享这些因素，分数虚高。这条规则在样本量 91 的情况下尤其重要，因为随机切分几乎必然把同一天的虫分到两边。
§10 AI 使用声明
10.1 AI 参与的边界
本词条的结构化写作在 AI 助手辅助下完成，内容包括：章节组织、表格骨架、代码草稿、术语一致性检查。所有数字均来自下述来源的原文，未做推算与推测。
10.2 AI 未参与的边界
未参与任何数据下载后的统计分析，未生成任何自行复算的统计结论。涉及数据质量判断的段落（§7）均基于官方文档明示的性质，不做推断。
10.3 输入来源
- WormWideWeb 首页：https://wormwideweb.org/
- WormWideWeb 数据集清单页：https://wormwideweb.org/activity/dataset/
- WormWideWeb 数据集说明页：https://wormwideweb.org/about/datasets/
- WormWideWeb 关于页：https://wormwideweb.org/about/
- Atanas & Kim 等，Cell 186(19):4134-4151.e31，DOI 10.1016/j.cell.2023.07.035
- Dag, Nwabudike & Kang 等，Cell，DOI 10.1016/j.cell.2023.04.018
- Pradhan & Madan 等，Nat Commun，DOI 10.1038/s41467-025-58478-y
- Zenodo v4 记录：https://doi.org/10.5281/zenodo.19388374
- Zenodo v2 记录：https://doi.org/10.5281/zenodo.8185377
- Zenodo 血清素数据集记录：https://zenodo.org/records/19414639
- Zenodo 疾病行为数据集记录：https://zenodo.org/records/19511989
- 数据集清单 CSV：https://github.com/flavell-lab/WormWideWeb-data
- 项目代码：https://github.com/flavell-lab/AtanasKim-Cell2023
- 站点代码：https://github.com/flavell-lab/WormWideWeb
- MIT 新闻稿：https://www.eurekalert.org/news-releases/998384
10.4 人工校验表
| 内容模块 | 审核者 | 审核方式 | 审核状态 |
|---|---|---|---|
| 规模数字（91 / 68 / 15 / 8） | 千方病案医学编辑部 | 对照站点清单页内嵌 JSON | ✅ 已验证 |
| 神经元数区间（105-176） | 千方病案医学编辑部 | 对照站点 n_neuron 字段 |
✅ 已验证 |
| 时间轴与帧间隔 | 千方病案医学编辑部 | 用 timestamp_confocal 相邻差分复核 |
✅ 已验证 |
| 许可状态 | 千方病案医学编辑部 | 逐个查询 Zenodo 记录 API 的 license 字段 | ✅ 已验证 |
| 行为量纲 | 千方病案医学编辑部 | 对照 about/datasets 原文 |
✅ 已验证 |
| 身份标注字段 | 千方病案医学编辑部 | 对照单数据集 JSON 的 label 结构 |
✅ 已验证 |
| 引用计数 | 千方病案医学编辑部 | Crossref 与 Europe PMC 双查 | ✅ 已验证 |
10.5 章节生成标注
§1 至 §9 由 AI 起草、人工修订。§7.7 的 DAIMS 24 项评分由人工给出，依据是 §1-§6 中已核实的事实。
10.6 最后人工审核日期
2026-10-29
页面状态：published（全部内容已完成审核并发布）
§A1 附录 A 数据组织与文件结构
wormwideweb (site) zenodo 19388374 (v4)
├── /activity/dataset/ ├── processed_h5.tar.bz2 568.8 MB
│ └── 91 rows (dataset index) ├── processed_h5_scrambled.tar.bz2 96.9 MB
├── /activity/api/data/download/ ├── deepnet-weights.tar.bz2 396.9 MB
│ ├── <dataset_id>/ -> 302 to GCS ├── fit_results.jld2.bz2 12.4 GB
│ │ └── <dataset_id>.json.bz2 ├── fit_results_lite.jld2.bz2 1.3 GB
│ └── paper/<paper_id>/ ├── relative_encoding_strength.jld2.bz2 14.0 GB
│ └── <paper_id>.json.bz2 ├── umap_dict.jld2.bz2 4.1 GB
└── /connectome/ ├── analysis_dict.jld2.bz2 113.8 MB
├── dict_neuropal_label.jld2.bz2 1.3 MB
每条虫 JSON 的六键： ├── neuropal_label.jld2.bz2 374.8 kB
behavior gcamp label ├── neuropal_label.json.bz2 16.2 kB
encoding metadata timing ├── tuning_strength.h5.bz2 9.2 MB
├── encoding_changes_corrected.h5.bz2 55.9 kB
├── neuron_categorization.h5.bz2 108.9 kB
├── fit_ranges.h5.bz2 2.4 kB
├── relative_encoding_strength_median.h5.bz2 1.9 MB
└── sampled_tau_vals_median.h5.bz2 160.0 kB
§A2 附录 B 神经元命名与主键
| 层 | 字段 | 示例 | 是否可作主键 |
|---|---|---|---|
| 数据集 | dataset_id |
atanas_kim_2023-2023-01-23-01 |
是（全局唯一） |
| 会话 | metadata.uid |
2023-01-23-01 |
是（论文内唯一） |
| ROI | gcamp.trace_array 行号 |
41 |
是（数据集内唯一） |
| 标注 | label[key]，key 是字符串形式的 ROI 号 |
"100" |
否（key 与 roi_id 不一一对应） |
| 神经元名 | label[key].label |
AVDL |
否（跨个体可重复） |
| 类别 | label[key].neuron_class |
AVD |
否（跨个体可重复，用于对齐） |
| 左右 | label[key].LR |
L |
否（与类别组合后才唯一） |
命名体系与连接组同源，来自线虫学界长期沿用的标准名。做跨库连接时，neuron_class 是最稳的字段。
§A3 附录 C 术语表
| 术语 | 说明 |
|---|---|
| GCaMP | 基因编码钙指示剂，钙离子浓度上升时荧光增强 |
| NeuroPAL | 多色荧光身份标注方法，用颜色组合唯一确定神经元 |
| CePNEM | 论文提出的概率神经编码模型，用行为变量解释每个神经元的活动 |
| ANTSUN | 论文使用的分割与配准流程 |
| ROI | 感兴趣区，这里指从体积影像里分割出的一个神经元核 |
| 头部神经节 | 线虫前端的主要神经组织，本数据集的成像区域 |
| 咽泵 | 咽部节律性收缩，用于进食，可作为行为变量 |
| 转向事件 | 运动方向的突然反转，本数据以帧区间记录 |
| z-score | 逐神经元标准化，均值 0、标准差 1 |
| F20 | 以第 20 百分位为基线的归一化 |
| Fmean | 以均值为基线的归一化 |
| 背腹符号 | 头摆角的符号约定，取决于虫以哪一侧爬行 |
| 半段拟合 | 把录制切成前后两半分别拟合，检验编码稳定性 |
| 雌雄同体 | 线虫的常见性别，本数据集全部为雌雄同体 |
§11 常见误读与避坑清单
下面 8 条是实际操作这批数据时会真正绊住人的地方，全部在核对过程中出现过。每条按「问题 — 症状 — 解决 — 参考」四段写；末尾附一张速查表，把其余常见误解一次列完。
⚠️ 坑点 1：把
avg_timestep当成秒读，整条时间轴差 60 倍（分类：预处理陷阱）问题：站点数据集清单里的
avg_timestep约为 0.01，单集 JSON 的timing.mean_timestep约为 0.6，两者相差 60 倍。按前者算，一集只有 16 秒；按后者算，一集十几分钟。
症状：算出来的行为速率（每秒转向次数、每秒泵动次数）整体偏大或偏小 60 倍，而波形图看起来完全正常，很难察觉。
解决：
- 简单方法：直接用
timestamp_confocal相邻差分求中位数，得到 0.600 秒，以它为准。- 进阶方法：用时间戳总跨度除以帧数做交叉校验，两条路径必须一致。
- SOTA 方法：把帧号与真实时间解耦，所有率指标一律先换算成秒再计算，绝不使用帧数直接当时间。
参考：about/datasets页对velocity单位的说明，以及单集 JSON 的timing块。
⚠️ 坑点 2：下载端点返回 302，签名 URL 十分钟后失效（分类：工程陷阱）
问题：
/activity/api/data/download/<dataset_id>/是重定向入口，真正的文件在对象存储的签名地址上，签名有效期 600 秒。
症状：把重定向目标复制下来复用，隔一会儿再请求就得到 403；以为是权限问题，实际是签名过期。
解决：
- 简单方法：始终请求原端点，让 HTTP 客户端自动跟随重定向。
- 进阶方法：下载后立刻校验 bz2 完整性，失败就重新走一次原端点，不要重试签名地址。
- SOTA 方法：把「取签名—下载—校验」封装成一个函数，失败自动回到第一步。
参考：响应头中的X-Goog-Expires=600。
⚠️ 坑点 3：超时设太短导致文件被截断，bunzip2 报「文件意外结束」（分类：工程陷阱）
问题：单集 JSON 压缩后约 3 到 4 MB，笔者的第一遍下载只给了 90 秒，传到一半被客户端主动中断。
症状：bunzip2报Compressed file ends unexpectedly，看起来像源文件损坏或站点出了问题，实际是本地截断。
解决：
- 简单方法：放宽超时，重下一次，用
-w "%{size_download}"打印实际字节数。- 进阶方法：同一地址连下两次，字节数必须一致；不一致即判定为截断。
- SOTA 方法：用
bz2解压做完整性验证，而不是只看文件是否存在。
参考：项目提供的checksum字段可用于最终校验。
⚠️ 坑点 4：把
trace_array当原始振幅用（分类：标签理解）问题：JSON 里的
trace_array是逐神经元 z-score 后的信号，不是原始钙强度。trace_array_original才是原始值。
症状：跨神经元比较「谁的活动幅度大」得到完全无意义的结果——每个神经元都被拉成了均值 0、标准差 1。
解决：
- 简单方法：要比较振幅，改用
trace_array_original。- 进阶方法：若论文口径要求 F20 或 Fmean 归一，必须回到 HDF5 包，JSON 里没有这两个变体。
- SOTA 方法：在数据字典里明确记录所用变体名，避免与他人结果不可比。
参考：about/datasets页对四种信号变体的定义。
⚠️ 坑点 5：行为量纲看漏「0.1」前缀（分类：标签理解）
问题：
velocity的单位是 0.1 毫米每秒，不是毫米每秒；pumping是次每秒；头摆角与角速度用弧度制。
症状：与文献里的速度数值对比时差 10 倍，或者把角速度当成线速度代入运动学模型。
解决：
- 简单方法：读数据前先把四个行为字段的单位抄在代码注释里。
- 进阶方法：写一个单位换算函数，所有下游计算只接受换算后的 SI 值。
- SOTA 方法：做跨数据集合并前，先在物理单位下画一次分布，异常会立刻暴露。
参考：about/datasets页的 Behavior traces 小节。
⚠️ 坑点 6：
roi_id是列表，直接当主键会静默丢标注（分类：预处理陷阱）问题：
label下每条标注的roi_id是一个列表，可能含多个 ROI；直接用label[key].roi_id建索引会得到列表而不是整数。
症状：把列表当字典键会直接报错；若先转字符串再建索引，则跨数据集对齐时全部失配。
解决：
- 简单方法：展平列表，逐个 ROI 建立「ROI 号 → 神经元名」映射。
- 进阶方法：展平前记录每个名字对应的 ROI 数，用于识别分裂或合并的异常 ROI。
- SOTA 方法：把展平后的表单独存档，与原始 JSON 一起版本化，保证可追溯。
参考：单集 JSON 中 91 条标注对应 90 个唯一名字。
⚠️ 坑点 7：头摆角符号未按数据集校正（分类：偏倚陷阱）
问题：线虫左右两侧都能朝上爬行，观测到的弯曲方向在背腹语义上会映射反；原始 HDF5 需要逐数据集做符号校正。
症状：把少数未校正的数据集混进群体分析，头摆角与转向方向的相关性被系统性削弱，但单看某个数据集的图一切正常。
解决：
- 简单方法：读清单 CSV 的
θh_pos_is_ventral列，按数据集施加正负号。- 进阶方法：JSON 已应用该校正，不要再施加一次，否则等于抵消。
- SOTA 方法：在数据管线上显式记录「来源=JSON 或 HDF5」，按来源决定是否校正。
参考：清单 CSV 中 68 个数据集里 56 个为真、12 个为假。
⚠️ 坑点 8：随机切分训练与验证（分类：数据泄漏）
问题：91 只虫子来自少数几个采集日，同一天的虫共享显微镜校准、培养批次与操作者。
症状：随机切分下验证集指标明显高于按日期留出，部署到新采集的一批数据时性能骤降。
解决：
- 简单方法：用分组交叉验证，分组键取会话编号里的日期前缀。
- 进阶方法：同时按实验条件分层，保证验证集里每种条件都有样本。
- SOTA 方法：留出一整个采集月份做测试集，模拟真正的「换一批实验」场景。
参考：站点未提供官方划分，分组键需自行从uid解析。
速查表：其余常见误解
| 常见说法 | 实际情况 | 证据 |
|---|---|---|
| 「91 个数据集就是 91 只不同虫子」 | 是 91 只个体，但每只只有一次录制，没有跨会话随访 | dataset_id 与 uid 一一对应 |
| 「全脑就是 302 个神经元都在」 | 单集 ROI 在 105 到 176 之间，只覆盖头部视野 | 站点 n_neuron 字段 |
| 「302 个神经元都标了名字」 | 最多一集标了 127 个，56 个集有标注，35 个没有 | 站点 n_labeled 与 common-neuropal 计数 |
「confidence 可以当概率用」 |
只是 3/4/5 的离散评分，没有 1/2 分等级 | 单集 91 条标注：3 分 39、4 分 33、5 分 19 |
| 「没标注的 ROI 是信号质量差」 | 多数是没做 NeuroPAL 标注，信号本身可用 | 无标注集的 gcamp 数组维度完整 |
| 「许可写 CC-BY 就能随便再分发」 | v2 明示 CC-BY-3.0-US，v4 许可字段为空 | 两个 Zenodo 记录的 license 字段不同 |
| 「可以直接拿 JSON 训练分割模型」 | 只有 processed_h5.tar.bz2 含原始体积影像 |
下载包内容对比 |
| 「它和 OpenWorm 是同一套东西」 | 无项目关系，连接组视图引用的是已发表连接组论文 | about 页引 Witvliet 2021、Cook 2020 |
| 「可以证明线虫全脑的普遍编码规律」 | 只适用于头部视野、这批品系、这个性别、这个实验室条件 | §7.1 偏倚表 |
§A4 附录 D 许可与引用
许可状态一览
| 记录 | 日期 | 许可证字段 |
|---|---|---|
| Zenodo 8150515（v1） | 2023-07-16 | 未查询 |
| Zenodo 8185377（v2） | 2023-07-16 | CC-BY-3.0-US |
| Zenodo 19241432（v3） | 2026-03-26 | 未查询 |
| Zenodo 19388374（v4） | 2026-04-02 | 空 |
| Zenodo 19414639（血清素集） | 2026-04-04 | 空 |
| Zenodo 19511989（疾病行为集） | 2026-04-11 | CC-BY-4.0 |
推荐引用
@article{atanas2023brainwide,
title = {Brain-wide representations of behavior spanning multiple
timescales and states in {C}. elegans},
author = {Atanas, Adam A. and Kim, Jungsoo and Wang, Ziyu and
Bueno, Eric and Becker, McCoy and Kang, Di and Park, Jungyeon
and Kramer, Talya S. and Wan, Flossie K. and Baskoylu, Saba
and Dag, Ugur and Kalogeropoulou, Elpiniki and Gomes, Matthew A.
and Estrem, Cassi and Cohen, Netta and Mansinghka, Vikash K.
and Flavell, Steven W.},
journal = {Cell},
volume = {186},
number = {19},
pages = {4134--4151.e31},
year = {2023},
doi = {10.1016/j.cell.2023.07.035}
}
@misc{wormwideweb_data_v4,
title = {CePNEM model analysis data and ANTSUN and microscopy
neural network weights},
author = {Atanas, Adam and Kim, Jungsoo and Wang, Ziyu and others},
year = {2026},
publisher = {Zenodo},
version = {v4},
doi = {10.5281/zenodo.19388374},
note = {Version DOI; cite the Cell paper for scientific use}
}
引用指南
- 学术引用用 Cell 论文，数据集声明用 Zenodo DOI 并注明版本。
- 若用到连接组视图，追加引用 Witvliet 等 2021 与 Cook 等 2020。
- 若用到 15 个血清素数据集，追加引用 Dag 等 2023。
- 若用到 8 个疾病行为数据集，追加引用 Pradhan & Madan 等 2025。
- 再分发前核对 §5.5 的许可状态，必要时联系作者。
编辑说明
核验时间：2026-10-29。核验方式：站点三个页面（首页、数据集清单、数据集说明）与 Zenodo API 的 license 字段逐条比对；单数据集 JSON 下载后读取结构与时间戳；Atanas & Kim 2023 的引用计数用 Crossref 与 Europe PMC 双查。未覆盖内容：未下载 33 GB 完整归档，未做全量统计，未验证 NeuroPAL 标注的正确率，未查询 v1 与 v3 记录的许可字段。数据集页内嵌 JSON 的 avg_timestep 与单集 JSON 的 mean_timestep 相差 60 倍一事，以逐帧时间戳为准，已在 §3.1 说明。
相关数据集导航
以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：
- drosophila-wholebrain-2p — 共享标签：神经科学 / 生理信号 / 时序数据
- noneeg — 共享标签：神经科学 / 生理信号 / 时序数据
- tuh-eeg-corpus — 共享标签：神经科学 / 生理信号 / 时序数据
- bonn-eeg — 共享标签：神经科学 / 生理信号 / 时序数据
- emgdb — 共享标签：神经科学 / 生理信号
- mmgdb — 共享标签：生理信号 / 时序数据
- phdsm — 共享标签：神经科学 / 生理信号
- pressure-flow-circum-cpap — 共享标签：生理信号 / 时序数据
- mimic-iv-waveform-legacy — 共享标签：生理信号 / 时序数据
- wearable-exam-stress — 共享标签：神经科学 / 生理信号 / 时序数据
导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。
