Skip to content

README.zh-CN.md

Latest commit

 

History

History
224 lines (167 loc) · 9.25 KB

README.zh-CN.md

File metadata and controls

224 lines (167 loc) · 9.25 KB
Raw

Open Ephys Data Format Converter

English | 简体中文

Open Ephys Data Format Converter 是一个独立的 Windows x64 科研数据工具，用于在 Open Ephys GUI 支持的三种神经电生理数据格式之间转换：

  • Open Ephys Binary Format：structure.oebin、continuous.dat 和 NumPy 元数据；
  • legacy Open Ephys Format：.continuous、.timestamps、.events 和 .openephys；
  • NWB 2.x / HDF5：.nwb。

Release 中的 EXE 无需安装 Python，也没有必须配置的运行环境。程序以只读方式打开输入记录，不会修改、移动、删除或上传原始数据。

转换矩阵

输入 \ 输出 Binary legacy Open Ephys NWB 2.x / HDF5
Binary — ✓ ✓
legacy Open Ephys ✓ — ✓
NWB 2.x / HDF5 ✓ ✓ —

三种格式的定义见 Open Ephys GUI 官方数据格式说明。

主要功能

  • 双击 EXE 即可进入引导式设置：选择输入、确认自动识别的格式、选择输出格式与路径，然后核对转换方案；
  • 提供适合脚本和可重复工作流的显式命令行参数；
  • 进度条在同一行原位刷新，不再随每次更新不断滚屏；
  • 输出重定向到日志文件时自动切换为低频普通文本，不写入终端控制字符；
  • 显示总体百分比、已处理数据量、速度、耗时和预计剩余时间；
  • 自动发现 legacy 输入目录中的一个或多个 Record Node；
  • 支持 continuous signals、sample numbers、timestamps、通道元数据、缩放值和 TTL events；
  • 根据目标格式生成 structure.oebin、legacy XML、转换清单及必要的完成标记；
  • Windows x64 EXE 为单文件程序，构建时关闭 CGO。

快速开始

  1. 从 最新 Release 下载 Windows x64 EXE；
  2. 双击运行 EXE；
  3. 输入源文件/文件夹路径，也可以把路径拖入终端窗口；
  4. 选择目标格式和输出路径；
  5. 核对完整方案后确认开始。

交互界面示例：

----------------------------------------------------------------------
  Open Ephys Data Format Converter  vX.Y.Z
  legacy Open Ephys  <->  Binary  <->  NWB 2.x/HDF5
----------------------------------------------------------------------
Guided setup
Source path: D:\recordings\Record Node 101
  Detected: legacy Open Ephys Format
Destination format:
  1) Open Ephys Binary Format
  2) NWB 2.x / HDF5
Choose [1]:

方括号中的内容是默认值，直接按 Enter 即可接受。若目标已存在，程序会明确询问是否覆盖；正式开始前还会再次显示输入、输出、转换方向和覆盖模式。

下文为了便于阅读统一使用 OpenEphysDataFormatConverter.exe。可以将下载的文件重命名为该名称，也可以在命令中使用 Release 文件的完整名称。

命令行使用

脚本或正式数据流程建议使用显式参数：

OpenEphysDataFormatConverter.exe `
  --from open-ephys `
  --to binary `
  --input "D:\recordings\legacy" `
  --output "E:\converted\binary"

其他示例：

# Binary -> legacy Open Ephys
OpenEphysDataFormatConverter.exe --from binary --to open-ephys -i "D:\binary" -o "E:\legacy"

# Binary -> NWB
OpenEphysDataFormatConverter.exe --from binary --to nwb -i "D:\binary" -o "E:\recording.nwb"

# 自动识别 NWB 输入并转换为 Binary
OpenEphysDataFormatConverter.exe --from auto --to binary -i "D:\recording.nwb" -o "E:\binary"

# 显式打开交互向导
OpenEphysDataFormatConverter.exe --interactive
参数 作用
--from <format> auto、binary、open-ephys 或 nwb
--to <format> binary、open-ephys 或 nwb
--input、-i 输入文件或目录
--output、-o 输出文件或目录
--overwrite、-f 覆盖已有目标
--interactive、-I 打开引导式设置
--help、-h 显示帮助
--version、-v 显示程序版本

--from auto 可以识别普通 Binary recording 目录、legacy Record Node，以及 .nwb、.h5 和 .hdf5 文件。可重复脚本中建议明确填写 --from。

识别的数据结构

legacy Open Ephys Format

Record Node 101/
├── structure.openephys
├── 100_CH1.continuous
├── 100_CH1.timestamps
├── 100_CH2.continuous
├── 100_CH2.timestamps
├── 100_ADC1.events
├── settings.xml          （可选）
└── messages.events       （可选）

Open Ephys Binary Format

recording1/
├── structure.oebin
├── continuous/
│   └── <stream>/
│       ├── continuous.dat
│       ├── sample_numbers.npy
│       └── timestamps.npy
└── events/
    └── <event-stream>/TTL/
        ├── states.npy
        ├── sample_numbers.npy
        ├── timestamps.npy
        └── full_words.npy

NWB 2.x / HDF5

recording.nwb
└── acquisition/
    ├── <ElectricalSeries>/data
    ├── <ElectricalSeries>/timestamps
    ├── <ElectricalSeries>/sync
    └── <stream>.TTL/

NWB 读取器面向 Open Ephys 风格的 ElectricalSeries 和 TTL TimeSeries 对象。

数据支持范围

数据 状态 说明
continuous signals 支持 16 位有符号样本；Binary 为 sample-major、channel-interleaved
sample numbers 支持 存在时保留，目标格式需要时重建
timestamps 支持 保留，或根据 sample number 和 sample rate 重建
通道元数据 支持 名称、采样率、source-node 信息、bit_volts/conversion
TTL events 支持 states、sample numbers、timestamps、full TTL words（存在时）
structure.oebin 自动生成 用于 Binary 输出
legacy .spikes 不支持 不转换 spike waveform 文件
message events 部分支持 见“已知限制”

性能与数据安全

  • 原始数据安全： 输入文件只读，转换结果写入独立目标位置；
  • 大规模记录： legacy Open Ephys ↔ Binary 的 continuous 路径采用有界流式 I/O，适用于几十 GB 甚至更大的记录，实际速度取决于磁盘；
  • NWB 内存占用： 当前纯 Go HDF5 写入器会把单个 continuous dataset 载入内存，因此 Binary → NWB 限制约为每个 dataset 1.5 GiB；
  • 已有输出： CLI 默认拒绝覆盖，必须显式添加 --overwrite；交互向导会询问确认；
  • 中断恢复： 转换失败或被中断可能留下不完整目标。检查或删除该目标后再使用 --overwrite 重试。

常见问题

无法识别输入格式

确认输入指向 Record Node、包含 structure.oebin 的 recording，或有效的 .nwb/.h5/.hdf5 文件。脚本中可使用 --from 明确指定格式。

提示输出已存在

更换输出路径；如果确定原目标可以被替换，再使用 --overwrite。覆盖操作只针对输出目标，不会修改输入。

进度长时间不变化

大型 HDF5 数据集的单次读写可能耗时较长；同时检查剩余磁盘空间、存储设备速度和杀毒软件实时扫描。不要在确认失败前强制终止进程。

转换后下游软件无法正确读取

先核对通道数、通道顺序、sample count、sample rate、bit_volts、timestamps 和 TTL 极性，并在 GitHub Issue 中提供最小可复现目录结构和错误信息。不要上传含隐私或未公开实验数据的文件。

已知限制

  • Release 暂时只提供 Windows x64 EXE；
  • legacy .spikes 不会转换；
  • messages.events 在 legacy → Binary 批量输出中可能保留为 legacy_messages.events，但不会转换为 Binary MessageCenter arrays 或 NWB annotations；
  • NWB messages 和无法识别的 processing objects 不会复制到 Binary 或 legacy 输出；
  • legacy ↔ NWB 适合一次处理一个 Record Node/recording，多 recording 输入应拆分任务；
  • 定制或非常旧的 legacy XML/header 可能需要额外适配；
  • 结构验证不能证明科学意义完全等价。用于分析前必须核对通道顺序、缩放、timestamps、事件极性、样本数和下游读取结果。

源码构建与检查

需要 Go 1.25 或更高版本：

go test ./...
go vet ./...
go build -trimpath -ldflags="-s -w" -o OpenEphysDataFormatConverter.exe .

Windows 下也可以运行 build_windows.bat，它会以 CGO_ENABLED=0 构建 x64 EXE。

项目文件

问题和可复现的错误报告可提交到 GitHub Issues。请勿提交原始实验数据、个人信息、私有目录、密码、访问令牌或其他敏感内容。

许可证与免责声明

本项目采用 MIT License，作为科研软件按现状提供，不附带任何担保。请始终保留未经修改的原始记录，并按照实验要求对转换结果进行质量控制。