Skip to main content
skill CX Codex

nwb-conversion — Claude Code skill: convert two-photon imaging to NWB

nwb-conversion transforms two-photon microscopy frames and behavioral position data into Neurodata Without Borders format with clock alignment verification and schema validation. Requires Python 3.12 and pinned scientific libraries.

MIT 462 installs ★ 58,036 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add K-Dense-AI/scientific-agent-skills --skill nwb-conversion -a claude-code
Open on GitHub

What nwb-conversion does

This skill orchestrates conversion of neuroscience acquisition data to NWB via NeuroConv and PyNWB. It takes grayscale two-photon TIFF stacks with frame timestamps and a position CSV file, transforms them into a standardized format while preserving session metadata, optical parameters and subject information.

Under the hood: clock synchronization between streams. The skill expects timestamps already in seconds from session start and computes a single affine clock transform with residual checks. It produces NWB schema validation, an NWB Inspector report (which may flag critical issues for manual review), and round-trip verification: confirms that pixels, timestamps, coordinate units and channel linkages round-trip correctly.

Requires Python 3.12 with pinned versions: 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, and hdmf-zarr==0.11.3. Covers only single-channel single-plane two-photon imaging and position data in meters; does not decode SpikeGLX, Open Ephys, multichannel TIFF or video, and does not perform spike sorting.

What it helps with

  • align two-photon frames and behavioral position to a shared timebase
  • convert raw microscopy data into standard NWB format
  • validate NWB schema and flag compliance issues early
  • verify data integrity after conversion via round-trip checks
  • generate a full report on metadata, clock corrections and remaining gaps

Example prompts for the agent

  • Convert two-photon imaging imaging.tif and position position.csv to NWB with pulse-based clock synchronization
  • Check that nwb-conversion passed schema validation and round-trip tests on my dataset
  • Prepare a session-template.json with microscopy metadata and subject parameters

How to install nwb-conversion

1Skills CLI (Vercel)

npx skills add K-Dense-AI/scientific-agent-skills --skill nwb-conversion -a claude-code

2Manually: put the files in place

~/.claude/skills/nwb-conversion/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nwb-conversion/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nwb-conversion

How do I install nwb-conversion in Claude Code?

Run npx skills add K-Dense-AI/scientific-agent-skills --skill nwb-conversion -a claude-code, then open ~/.claude/skills/nwb-conversion/SKILL.md to verify.

What does nwb-conversion do?

Converts two-photon TIFF stacks and behavioral position CSV into an NWB file, aligns the data streams to a common timebase, validates the NWB schema and runs round-trip tests to confirm data integrity.

What data formats does it support?

Single-channel single-plane two-photon grayscale TIFF with frame timestamps and position data in meters, centimeters or millimeters. Does not support multichannel TIFF, SpikeGLX, Open Ephys, spike sorting or arbitrary formats.

Source text

SKILL.md · MIT
---
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

```bash
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:

```bash
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

- [NeuroConv TIFF conversion](https://neuroconv.readthedocs.io/en/stable/conversion_examples_gallery/imaging/tiff.html)
- [NeuroConv temporal alignment](https://neuroconv.readthedocs.io/en/stable/user_guide/temporal_alignment.html)
- [PyNWB](https://github.com/NeurodataWithoutBorders/pynwb)
- [NWB Inspector and its relation to schema validation](https://github.com/NeurodataWithoutBorders/nwbinspector)

© K-Dense-AI · MIT · K-Dense-AI/scientific-agent-skills

Similar skills

All skills for Science and research →

From the same set176

The whole set →
qiime2-amplicon qiime2-amplicon — a skill that turns paired-end 16S reads into QIIME 2 ASV tables and taxonomy, preserving the full transformation record. Validates manifests, primer orientation, read overlap, and classifier compatibility before execution. CX Codex +1 465installs cellprofiler Runs CellProfiler to count nuclei and measure fluorescence in 2D microscopy images. Use it for repeatable analysis of grayscale TIFF fields. CX Codex +1 464installs pycalphad pycalphad computes thermodynamic CALPHAD phase equilibria and compositions from TDB files. Useful for alloy phase fraction modeling across temperature ranges. CX Codex +1 463installs relion Validates STAR files, runs gold-standard particle refinement, and postprocesses independent half maps in RELION 5.0.1. Built for single-particle cryo-EM projects. CX Codex +1 463installs marine-carbonate-chemistry marine-carbonate-chemistry turns two measured carbonate parameters into a speciation table: pH, pCO2, aragonite and calcite saturation, with the assumptions written down. CX Codex +1 ★ 58,036repo stars 13c-metabolic-flux 13c-metabolic-flux estimates intracellular metabolic fluxes from steady-state carbon-13 tracing data using mfapy and SciPy. CX Codex +1 ★ 58,036repo stars fictiv This skill runs Fictiv workflows in a browser, from CAD upload and manufacturing setup to quotes, checkout, and order tracking. CX Codex +1 ★ 58,036repo stars primer-design primer-design is a Claude Code skill that designs and checks PCR and RT-qPCR primer pairs with Primer3, screening for off-target amplification against a reference. CX Codex +1 ★ 58,036repo stars

Project sponsors

Companies that keep this analytics open