nwb-conversion

検証済み NWB 変換

対応ストリーム

この実行可能なワークフローは、1 回のセッションで 2 つの明示的な入力ストリームを扱います：

入力	NWB 表現	検証済みの制約
二光子グレースケールマルチページ TIFF + フレームタイムスタンプ CSV	NeuroConv 経由の Imaging という名前の取得 TwoPhotonSeries	1 チャンネル、1 プレーン、1 ページにつき 1 つの 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 ファイルから解決されます。正確な CSV と メタデータの契約、およびパルスペアのバリアントについては references/input-contract.md をお読みください。TIFF ピクセルは 取得されたまま保持されます。生の任意単位の強度は、単位ラベルを変更しただけでは光子数には なりません。
3. 取得の証拠から共通のタイムベースを確立します。フレームタイムスタンプは、タイムゾーンを 考慮したセッション開始からの参照クロック秒でなければなりません。位置については、文書化 された共有クロックまたは一致する同期パルスのいずれかを提供してください。このヘルパーは 1 つのアフィンクロック変換をフィッティングし、その残差を指定された許容範囲と照合し、 パルス範囲を超える外挿を拒否します。一致して見える神経/行動信号から同期を推定することは 決してありません。クロックのリセットや非線形ドリフトには、明示的に検証された区分 マッピングが必要です。
4. コンバーターを実行します。入力は有限で厳密に増加するタイムスタンプと、一致する画像/ タイムスタンプ数を持たなければなりません。1 チャンネルと 1 プレーンを明示的に宣言して ください。既知の TIFF チャンネル/プレーンメタデータは一致しなければなりません。 グレースケールページだけでは、文書化されていないインターリーブを排除できません。 取得サンプルはそのまま維持されます。変換されるのは座標単位と、証拠がある場合は行動 タイムスタンプのみです。
5. NWB ファイルと一緒に .validation.json を読みます。スキーマ準拠、Inspector の検出事項、 およびデータの等価性は、それぞれ異なる問いに答えます。スクリプトはスキーマの失敗に対して エラーで終了し、重大な Inspector の検出事項をレポートでのレビュー用にフラグ付けします。 すべての検出事項を文脈の中でレビューしてください。検証の成功は、ユーザーが提供した解剖学的 ラベル、パルスペアリング、またはキャリブレーションが正しいことを立証できません。
6. NWB、検証 JSON、元の変換設定、および残っているメタデータのギャップや Inspector の検出 事項の説明を納品します。アップロードやアーカイブへの提出は、このワークフローの一部では ありません。

実行

スキルディレクトリから、実際の解析ファイルへのパスを指定して次を実行します:

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

nwb-env は上記で作成した環境を指している必要があります。絶対パスの例に入力パスを示していますが、これは説明用です。このコマンドは .nwb 出力を必要とし、既存の NWB や検証レポートへの上書きを拒否します。出力には、ソースとコンバーターのチェックサム、パッケージのバージョン、指定されたメタデータの全体、単位、クロックフィットの来歴が、スクラッチ記録と検証レポートの両方に含まれます。このコマンドを大規模データ向けに改変する場合、TIFF の書き込みは反復的で、等価性チェックは一度に 1 フレームずつ読み込みます。位置 CSV は現在、メモリに読み込まれます。ラウンドトリップチェックでは、dtype、単位スケーリング、光学チャネルのリンク、被験体メタデータ、位置の参照フレーム、共通の時間原点、埋め込まれた来歴も検証します。レビューが必要な Inspector の指摘は CLI のサマリーに表示されます。終了コードがゼロであることだけでは、そのファイルが科学的に正しいことを意味しません。書き込み中またはラウンドトリップチェック中に例外が発生すると、レポートのない不完全な NWB が残る可能性があります。エラーを保持し、原因を修正したうえで新しい出力パスを使用してください。

実際のライブラリを用いたテストでは、不規則なフレームタイミングを持つ 8 枚の非正方形 uint16 画像と 4 つの位置サンプルを変換し、ピクセルとタイムスタンプの正確なラウンドトリップを検証し、センチメートルからメートルへの変換をチェックします。2 つ目の統合テストでは、3 つの一致するパルスから既知の 1000 ppm のクロックドリフトと 50 ms のオフセットを復元します。重複したタイムスタンプ、一致しないフレーム数、クロックの証拠の欠如、非線形なパルスの不一致、タイムゾーンの欠落は拒否ケースです。マッピングは TIFF の (time,y,x) から NWB の (time,x,y) へであり、転置されたすべてのソースページに対して明示的にチェックされます。NWB Inspector は、幅がフレーム数を超えているため、短いフィクスチャに重大なオリエンテーションヒューリスティックのフラグを立てます。レポートはその指摘を保持しつつ、フレームとタイムスタンプの正確な等価性の証拠を追加します。最長軸のヒューリスティックを満たすためだけに転置が行われることはありません。

主な参照資料

• NeuroConv TIFF conversion
• NeuroConv temporal alignment
• PyNWB
• NWB Inspector とスキーマ検証との関係