Validated NWB conversion
Supported streams
The executable workflow covers two explicit input streams in one session:
| Input |
NWB representation |
Tested constraints |
| Two-photon grayscale multi-page TIFF + frame timestamps CSV |
Acquisition TwoPhotonSeries named Imaging through NeuroConv |
One channel, one plane, one 2D image per page, fixed shape and dtype |
Calibrated position CSV (time_s,x,y) |
Behavior Position / SpatialSeries through PyNWB |
Coordinates in m, cm or mm; converted to meters without temporal resampling |
Other acquisition readers require their own format-specific tests. In particular, this helper does
not decode SpikeGLX, Open Ephys, multichannel TIFF, volumetric TIFF, compressed video, or pixel-to-world
calibration. Do not rename an arbitrary numeric table to a supported stream.
Install the tested environment
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
Keep both Zarr pins even for an HDF5-only conversion: NeuroConv 0.10.2 imports its backend
configuration modules at startup, and the tested unconstrained Zarr 3.4.0 installation failed on
zarr.codec_registry. The pinned environment ran the real conversion, PyNWB validation and
Inspector successfully on macOS ARM64. The dependency resolver supplies NumPy and HDF5 support.
These are compatibility pins, not claims that Zarr 2 and hdmf-zarr 0.11.3 are the latest releases.
Current interface checks and the tested dependency exception are recorded in
references/upstream-review.md.
Workflow
- Inventory the actual inputs and acquisition metadata. Identify image plane/channel, optical
settings, subject/session identifiers, timezone, behavior coordinate system, units and the
timestamp clock for every stream. Preserve originals. Do not replace missing metadata with
plausible defaults from a sample config.
- Copy assets/session-template.json beside the raw data and
replace the explicitly synthetic values. Paths resolve from that JSON file. Read
references/input-contract.md for the exact CSV and metadata
contract and the pulse-pair variant. TIFF pixels are retained as acquired; a raw arbitrary-unit
intensity does not become a photon count merely by changing its unit label.
- Establish the common timebase from acquisition evidence. Frame timestamps must already be
reference-clock seconds since the timezone-aware session start. For position, provide either
a documented shared clock or matched synchronization pulses. The helper fits one affine clock
transform, checks its residual against a specified tolerance, and refuses extrapolation beyond
the pulse range. It never estimates synchronization from coincident-looking neural/behavioral
signals. Clock resets or nonlinear drift require an explicitly validated piecewise mapping.
- Execute the converter. Inputs must have finite, strictly increasing timestamps and matching
image/timestamp counts. Explicitly declare one channel and one plane; known TIFF channel/plane
metadata must agree. Grayscale pages alone cannot exclude undocumented interleaving.
The acquisition samples stay intact; only coordinate units and, when
evidenced, behavior timestamps are transformed.
- Read the
.validation.json alongside the NWB file. Schema compliance, Inspector findings and
data equality answer different questions. The script exits with an error for schema failures
and flags critical Inspector findings for review in the report. Review all findings in context;
successful validation cannot establish that anatomical labels, pulse pairing or calibration
supplied by the user are correct.
- Deliver the NWB, validation JSON, original conversion config and an explanation of remaining
metadata gaps or Inspector findings. No upload or archive submission is part of this workflow.
Execute
Run the following from the skill directory, with paths to the actual analysis files:
nwb-env/bin/python scripts/convert_session.py /path/to/session.json --output /path/to/session.nwb
nwb-env must point to the environment created above; the absolute example input paths are
illustrative. The command requires a .nwb output and refuses to overwrite an existing NWB or
validation report. Output contains source and converter checksums,
package versions, full supplied metadata, units and clock-fit provenance in both a scratch record
and the validation report. When adapting this command for large data, TIFF writes are iterative
and equality checking loads one frame at a time; position CSV currently loads into memory.
Round-trip checks also verify dtype, unit scaling, optical-channel links, subject metadata,
position reference frame, common time origin and embedded provenance. Inspector findings requiring
review appear in the CLI summary; exit zero alone does not mean the file is scientifically correct.
An exception during writing or round-trip checks can leave an incomplete NWB without a report;
retain the error and use a fresh output path after correcting the cause.
The real-library test converts eight non-square uint16 images with irregular frame timing plus
four position samples, asserts exact pixel and timestamp round trips, and checks centimeter-to-meter
conversion. A second integration test recovers a known 1000-ppm clock drift and 50-ms offset from
three matched pulses. Duplicate timestamps, mismatched frame counts, absent clock evidence,
nonlinear pulse disagreement and missing timezone are rejection cases. The mapping is
TIFF (time,y,x) to NWB (time,x,y), explicitly checked against every transposed source page. NWB Inspector flags the short fixture
with a critical orientation heuristic because width exceeds frame count; the report retains that
finding and adds the exact frame/timestamp equality evidence. No transpose is performed merely to
satisfy a longest-axis heuristic.
Primary references
1---2name: nwb-conversion3description: Converts neuroscience acquisition data to Neurodata Without Borders files with NeuroConv and PyNWB, preserves metadata and timebases, checks evidence-based clock alignment, and produces schema validation, NWB Inspector findings and round-trip checks. Use for NWB conversion and synchronization of planar single-channel two-photon TIFF imaging plus timestamped behavioral position CSV; this skill does not perform spike sorting or claim tested support for arbitrary acquisition formats.4license: MIT5compatibility: Requires Python 3.12 with neuroconv[tiff] 0.10.2, PyNWB 4.2.0, NWB Inspector 0.7.2, roiextractors 0.10.0, tifffile 2026.9.20, zarr 2.18.7 and hdmf-zarr 0.11.3. Local HDF5 file access is required. Network is needed only for installation; no credentials.6metadata:7 source: https://skillmd.com/skills/k-dense-ai/nwb-conversion8 version: "1.1"9 skill-author: K-Dense Inc.10 last-reviewed: "2026-10-01"11 upstream-neuroconv: "0.10.2"12 upstream-pynwb: "4.2.0"13 upstream-nwbinspector: "0.7.2"14---1516# Validated NWB conversion1718## Supported streams1920The executable workflow covers two explicit input streams in one session:2122| Input | NWB representation | Tested constraints |23| --- | --- | --- |24| Two-photon grayscale multi-page TIFF + frame timestamps CSV | Acquisition `TwoPhotonSeries` named `Imaging` through NeuroConv | One channel, one plane, one 2D image per page, fixed shape and dtype |25| Calibrated position CSV (`time_s,x,y`) | Behavior `Position` / `SpatialSeries` through PyNWB | Coordinates in m, cm or mm; converted to meters without temporal resampling |2627Other acquisition readers require their own format-specific tests. In particular, this helper does28not decode SpikeGLX, Open Ephys, multichannel TIFF, volumetric TIFF, compressed video, or pixel-to-world29calibration. Do not rename an arbitrary numeric table to a supported stream.3031## Install the tested environment3233```bash34uv venv --python 3.12 nwb-env35uv pip install --python nwb-env/bin/python 'neuroconv[tiff]==0.10.2' pynwb==4.2.0 \36 nwbinspector==0.7.2 roiextractors==0.10.0 tifffile==2026.9.20 \37 zarr==2.18.7 hdmf-zarr==0.11.338```3940Keep both Zarr pins even for an HDF5-only conversion: NeuroConv 0.10.2 imports its backend41configuration modules at startup, and the tested unconstrained Zarr 3.4.0 installation failed on42`zarr.codec_registry`. The pinned environment ran the real conversion, PyNWB validation and43Inspector successfully on macOS ARM64. The dependency resolver supplies NumPy and HDF5 support.44These are compatibility pins, not claims that Zarr 2 and hdmf-zarr 0.11.3 are the latest releases.45Current interface checks and the tested dependency exception are recorded in46[references/upstream-review.md](references/upstream-review.md).4748## Workflow49501. Inventory the actual inputs and acquisition metadata. Identify image plane/channel, optical51 settings, subject/session identifiers, timezone, behavior coordinate system, units and the52 timestamp clock for every stream. Preserve originals. Do not replace missing metadata with53 plausible defaults from a sample config.542. Copy [assets/session-template.json](assets/session-template.json) beside the raw data and55 replace the explicitly synthetic values. Paths resolve from that JSON file. Read56 [references/input-contract.md](references/input-contract.md) for the exact CSV and metadata57 contract and the pulse-pair variant. TIFF pixels are retained as acquired; a raw arbitrary-unit58 intensity does not become a photon count merely by changing its unit label.593. Establish the common timebase from acquisition evidence. Frame timestamps must already be60 reference-clock seconds since the timezone-aware session start. For position, provide either61 a documented shared clock or matched synchronization pulses. The helper fits one affine clock62 transform, checks its residual against a specified tolerance, and refuses extrapolation beyond63 the pulse range. It never estimates synchronization from coincident-looking neural/behavioral64 signals. Clock resets or nonlinear drift require an explicitly validated piecewise mapping.654. Execute the converter. Inputs must have finite, strictly increasing timestamps and matching66 image/timestamp counts. Explicitly declare one channel and one plane; known TIFF channel/plane67 metadata must agree. Grayscale pages alone cannot exclude undocumented interleaving.68 The acquisition samples stay intact; only coordinate units and, when69 evidenced, behavior timestamps are transformed.705. Read the `.validation.json` alongside the NWB file. Schema compliance, Inspector findings and71 data equality answer different questions. The script exits with an error for schema failures72 and flags critical Inspector findings for review in the report. Review all findings in context;73 successful validation cannot establish that anatomical labels, pulse pairing or calibration74 supplied by the user are correct.756. Deliver the NWB, validation JSON, original conversion config and an explanation of remaining76 metadata gaps or Inspector findings. No upload or archive submission is part of this workflow.7778## Execute7980Run the following from the skill directory, with paths to the actual analysis files:8182```bash83nwb-env/bin/python scripts/convert_session.py /path/to/session.json --output /path/to/session.nwb84```8586`nwb-env` must point to the environment created above; the absolute example input paths are87illustrative. The command requires a `.nwb` output and refuses to overwrite an existing NWB or88validation report. Output contains source and converter checksums,89package versions, full supplied metadata, units and clock-fit provenance in both a scratch record90and the validation report. When adapting this command for large data, TIFF writes are iterative91and equality checking loads one frame at a time; position CSV currently loads into memory.92Round-trip checks also verify dtype, unit scaling, optical-channel links, subject metadata,93position reference frame, common time origin and embedded provenance. Inspector findings requiring94review appear in the CLI summary; exit zero alone does not mean the file is scientifically correct.95An exception during writing or round-trip checks can leave an incomplete NWB without a report;96retain the error and use a fresh output path after correcting the cause.9798The real-library test converts eight non-square uint16 images with irregular frame timing plus99four position samples, asserts exact pixel and timestamp round trips, and checks centimeter-to-meter100conversion. A second integration test recovers a known 1000-ppm clock drift and 50-ms offset from101three matched pulses. Duplicate timestamps, mismatched frame counts, absent clock evidence,102nonlinear pulse disagreement and missing timezone are rejection cases. The mapping is103TIFF `(time,y,x)` to NWB `(time,x,y)`, explicitly checked against every transposed source page. NWB Inspector flags the short fixture104with a critical orientation heuristic because width exceeds frame count; the report retains that105finding and adds the exact frame/timestamp equality evidence. No transpose is performed merely to106satisfy a longest-axis heuristic.107108## Primary references109110- [NeuroConv TIFF conversion](https://neuroconv.readthedocs.io/en/stable/conversion_examples_gallery/imaging/tiff.html)111- [NeuroConv temporal alignment](https://neuroconv.readthedocs.io/en/stable/user_guide/temporal_alignment.html)112- [PyNWB](https://github.com/NeurodataWithoutBorders/pynwb)113- [NWB Inspector and its relation to schema validation](https://github.com/NeurodataWithoutBorders/nwbinspector)