/nwb-conversion

name: nwb-conversion
description: 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.
license: MIT
compatibility: 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.
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-10-01"
  upstream-neuroconv: "0.10.2"
  upstream-pynwb: "4.2.0"
  upstream-nwbinspector: "0.7.2"

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](references/upstream-review.md).

Workflow

1. 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. 2. Copy [assets/session-template.json](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](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. 3. 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. 4. 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. 5. 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. 6. 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 em