feat: wire imaging (behavior-clock synced) into the NWB export handler

[tabedzki]

Closes the imaging half of #111: an imaging-raw export now runs through the handler's validation and conversion flow and produces an NWB file whose TwoPhotonSeries is on the ViRMEn behavior clock, instead of raising "imaging export not yet wired".

Targets feat/nwb-export-handler-completion. This branch already merges that backend, so the diff here is the imaging work on top of it.

Depends on tabedzki/tank-lab-to-nwb#1, which adds the per-interface timestamp support this calls into. That should land first.

What changed

nwb_production_utils — validate_imaging_data_exists referenced imaging_element.Scan and imaging_element.FieldOfView, neither of which exists (imaging_element is element_calcium_imaging.imaging_preprocess). It now walks the real chain, ImagingPipelineSession → AcquiredTiff → TiffSplit → TiffSplit.File, and takes a recording key so callers do the session → recording hop the way the ephys validator already does.

An empty fov_numbers list now requires at least one TiffSplit to exist rather than passing vacuously — an empty DataJoint restriction matches every row, which is what made the old code report success for sessions with no imaging at all.

estimate_imaging_size_gb computed 0.05 GB/FOV, >10x short for raw stacks. It now derives bytes from fov_pixel_resolution_xy and the frame counts in TiffSplit.File at 2 bytes/pixel for ScanImage int16. estimate_total_size's imaging branch no longer skips: the linkage its TODO was waiting on is the same recording_ids_for_session hop the ephys branch above it already uses.

nwb_export/conversion.py — resolve_imaging_paths maps a session or recording key through TiffSplit/TiffSplit.File to absolute paths, in acquisition order (the ScanImage interface treats a multi-file list as one continuous recording, so unordered paths would give unordered frames). imaging_timestamps_for_session runs the I2C sync, applies the clock offset below, and strides the per-frame array down to the interface's sample count; a frame count that isn't a whole multiple of that raises instead of silently misaligning. build_source_data gains an imaging branch, and run_conversion_to_file passes imaging timestamps through the converter's new aligned_timestamps rather than the shared sync_timestamps array.

nwb_export_handler — the imaging branch takes the same session → recording hop as ephys and calls the validator.

Docs — new docs/nwb_export.md (stage flow, the recipe for wiring a modality, the dependency story) and a new section 6 in docs/imaging_behavior_sync.md deriving the clock convention.

The clock convention

Worth reading before review, because it's easy to mistake for jitter.

trial.start is vr.timeElapsed (ExperimentLog.m:501), never corrected by blockStart — that variable is only ever read to compute block.duration. The engine zeroes timeElapsed at firstTic (virmenEngine.m:124), which runs after vr.code.initialization(vr) (line 105) — and it's inside that initialization that the ExperimentLog constructor stamps session.start and then newBlock() stamps block.start. So the trial clock starts at block start, while NWB zeroes at session.start.

The gap between those two clock calls is the constructor tail — version bookkeeping, makeOrContinueLog file I/O — plus repmat(obj.trialInfo, 1, totalTrials) allocating the whole trial array. That's allocation and I/O cost, not drift and not a physical delay, so it scales with totalTrials and varies per session. The code reads it from each log; it is never hardcoded.

Skip it and trial 1's first imaging frame lands 4.7 ms before trial 1 starts instead of 22.3 ms after — wrong by a frame period, and small enough to pass for ordinary jitter.

Reconstructing the zero through the imaging PC's absolute epoch stamp instead lands 958 ms out. That rules out initialTimestamp as the zero (it misses by 6.35 s), but the residual is inter-machine wall-clock skew — which is exactly why the sync is content-based through the I2C [block, trial, iteration] packets. Wall clocks should never be used to align these streams.

Verification

End-to-end on the sample session, through the shipped code path:

source_data: ['ScanImageImaging', 'VirmenData']
diagnostics: slope 1.000027891, residual 10.4 ms, epoch_offset 27.0 ms,
             2000 frames -> 400 volumes
nwb:         TwoPhotonSeries + 179 trials, 0.420 GB
frame 644 (trial 1's first imaging frame) = +22.3 ms after trial 1 start

29 imaging tests pass (validation, sizing, path resolution, source-data wiring). tests/nwb_export/test_nwb_export_handler.py has 10 failures and 9 errors that predate this branch — they fail at import on dj.config["custom"] with no DB configured.

What is not verified

resolve_imaging_paths and the handler's imaging branch have mocked coverage only. No DataJoint instance was reachable, so the session → recording → TiffSplit hop is untested against a real database, and the end-to-end run above supplied TIFF paths directly to bypass it. That hop is the most likely place for this to break in production and deserves a run against a real session before this is relied on.

Still open (tracked on #111)

• Mixed ephys+imaging clock rule. Ephys aligns behavior onto the ephys clock; imaging-only sessions use the ViRMEn clock. A session with both has no rule yet. This hardens at the first DANDI upload, so it wants sign-off before then.
• Pinning tank-lab-to-nwb. Still path-installed and unpinned, so the two repos move in lockstep by hand.

🤖 Generated with Claude Code

https://claude.ai/code/session_017dzDXz6d8TiLLvgsA38P1V