nwb-conversion

经验证的 NWB 转换

支持的流

可执行工作流在一次会话中覆盖两个明确的输入流：

输入	NWB 表示	已验证的约束
双光子灰度多页 TIFF + 帧时间戳 CSV	通过 NeuroConv 获取名为 Imaging 的 TwoPhotonSeries	单通道、单平面、每页一个 2D 图像、形状和 dtype 固定
已校准的位置 CSV（time_s,x,y）	通过 PyNWB 生成行为 Position / SpatialSeries	坐标单位为 m、cm 或 mm；转换为米，不进行时间重采样

其他采集读取器需要各自针对格式的测试。特别是，此辅助工具不解码 SpikeGLX、Open Ephys、多通道 TIFF、体 TIFF、压缩视频或像素到世界坐标校准。不要将任意数值表重命名为受支持的流。

安装已验证的环境

uv venv --python 3.12 nwb-env
uv pip install --python nwb-env/bin/python 'neuroconv[tiff]==0.10.2' pynwb==4.2.0 \
  nwbinspector==0.7.2 roiextractors==0.10.0 tifffile==2026.9.20 \
  zarr==2.18.7 hdmf-zarr==0.11.3

即使仅进行 HDF5 转换，也要保留两个 Zarr 版本固定：NeuroConv 0.10.2 在启动时导入其后端配置模块，而未加约束的 Zarr 3.4.0 已验证安装在 zarr.codec_registry 上失败。固定版本的环境在 macOS ARM64 上成功运行了真实转换、PyNWB 验证和 Inspector。依赖解析器提供 NumPy 和 HDF5 支持。这些是兼容性版本固定，并不表示 Zarr 2 和 hdmf-zarr 0.11.3 是最新版本。当前的接口检查和已验证的依赖例外记录在 references/upstream-review.md 中。

工作流

1. 清点实际输入和采集元数据。识别每个流的图像平面/通道、光学设置、受试者/会话标识符、时区、行为坐标系、单位和时间戳时钟。保留原始数据。不要用示例配置中看似合理的默认值替换缺失的元数据。
2. 将 assets/session-template.json 复制到原始数据旁边，并替换明确标注的合成值。路径从该 JSON 文件解析。阅读 references/input-contract.md 了解确切的 CSV 和元数据契约以及脉冲对变体。TIFF 像素按采集时的状态保留；原始任意单位强度不会仅因更改单位标签而变为光子计数。
3. 根据采集证据建立公共时基。帧时间戳必须已经是自时区感知会话开始以来的参考时钟秒数。对于位置，提供有文档说明的共享时钟或匹配的同步脉冲。辅助工具拟合一个仿射时钟变换，检查其残差是否在指定容差范围内，并拒绝超出脉冲范围的外推。它绝不会根据看似重合的神经/行为信号估计同步。时钟重置或非线性漂移需要明确验证的分段映射。
4. 执行转换器。输入必须具有有限且严格递增的时间戳，并且图像/时间戳计数匹配。明确声明一个通道和一个平面；已知的 TIFF 通道/平面元数据必须一致。仅凭灰度页无法排除未记录的交错。采集样本保持完整；仅转换坐标单位，以及在有必要证据时转换行为时间戳。
5. 阅读 NWB 文件旁边的 .validation.json。模式合规性、Inspector 发现和数据相等性回答的是不同问题。脚本在模式失败时以错误退出，并在报告中标记关键 Inspector 发现以供审查。在上下文中审查所有发现；成功验证无法确定用户提供的解剖标签、脉冲配对或校准是否正确。
6. 交付 NWB、验证 JSON、原始转换配置以及对剩余元数据缺口或 Inspector 发现的说明。此工作流不包含上传或归档提交。

执行

在 skill 目录下运行以下命令，并传入实际分析文件的路径：

nwb-env/bin/python scripts/convert_session.py /path/to/session.json --output /path/to/session.nwb

nwb-env 必须指向上文创建的环境；示例输入路径的绝对路径仅作说明之用。该命令要求输出 .nwb 文件，并拒绝覆盖已存在的 NWB 或验证报告。输出在暂存记录和验证报告中均包含源与转换器校验和、包版本、完整提供的元数据、单位以及时钟拟合溯源信息。在针对大数据调整此命令时，TIFF 写入是迭代式的，相等性检查一次加载一帧；位置 CSV 目前会加载到内存中。往返检查还会验证 dtype、单位缩放、光学通道链接、被试元数据、位置参考系、公共时间原点和嵌入的溯源信息。需要人工复核的 Inspector 发现会出现在命令行摘要中；仅退出码为零并不意味着文件在科学上是正确的。在写入或往返检查期间发生异常可能会留下没有报告的未完成 NWB；请保留错误，并在修正原因后使用新的输出路径。

真实库测试会转换八张非正方形 uint16 图像（帧时序不规则）以及四个位置样本，断言像素和时间戳的精确往返一致，并检查厘米到米的转换。第二个集成测试会从三个匹配脉冲中恢复已知的 1000-ppm 时钟漂移和 50-ms 偏移。重复时间戳、帧数不匹配、缺少时钟证据、非线性脉冲不一致以及缺少时区都属于拒绝情形。映射关系为 TIFF (time,y,x) 到 NWB (time,x,y)，并会针对每一页转置后的源数据显式检查。NWB Inspector 会因为宽度超过帧数而对短 fixture 标记一个严重的朝向启发式问题；报告会保留该发现，并加入精确的帧/时间戳相等性证据。不会仅仅为了满足最长轴启发式而执行转置。

主要参考

• NeuroConv TIFF conversion
• NeuroConv temporal alignment
• PyNWB
• NWB Inspector and its relation to schema validation