references/input-contract.md
Input contract and clock evidence
Use assets/session-template.json as a shape template only. Every experimental field is synthetic.
The helper requires timezone-aware ISO 8601 session_start_time, a stable unique identifier,
session description, experimenter list, lab, institution and a PyNWB Subject mapping. Keep subject
IDs pseudonymous where the dataset requires it. Do not confuse wall-clock time with elapsed sample
seconds or infer a timezone from the computer running the conversion.
imaging.modality must explicitly equal two-photon; other or missing modalities are rejected.
imaging supplies device name/description, series/plane description, indicator, anatomical location,
intensity unit, excitation and emission wavelengths in nanometers, and optical-channel description.
The helper implements a two-photon series; optical metadata must describe that actual acquisition.
Subject fields are passed through to PyNWB and retained in the full provenance config.
The optional subject.date_of_birth uses timezone-aware ISO 8601 text, converted to a datetime for
PyNWB. Session and position descriptions, optical text fields, and every experimenter name must be
nonempty. The position reference frame must describe the calibrated coordinates actually supplied.
Set integer imaging.num_channels: 1 and imaging.num_planes: 1 only after checking the acquisition
layout. The helper rejects multiple TIFF series, color/palette samples, or explicit non-singleton
channel/depth axes. Missing TIFF layout metadata does not prove a single channel or plane: a stack
of interleaved grayscale pages can look identical to a time sequence. Resolve that from microscope
metadata before conversion. OME multi-channel or volumetric input needs a separately tested reader.
Image timestamps CSV has exactly one column:
time_s
0.0
0.1
0.203
There must be one row per grayscale TIFF page. Dropped frames are represented by gaps in the actual timestamps, not by silently reindexing to a nominal rate. The nominal rate supplied internally to NeuroConv is only an initial reader parameter; every recorded frame receives its explicit timestamp. A reordered TIFF must be paired with correspondingly reordered acquisition timestamps before use.
Position CSV has exactly these columns:
time_s,x,y
0.0,10.0,20.0
0.2,10.3,20.2
0.4,10.8,20.1
Every CSV row must have exactly the header's number of fields. Extra values, missing fields, nonfinite values and nonincreasing time values are rejected rather than silently discarded.
position_unit is m, cm or mm; position_reference_frame describes origin and axis directions,
and position_description records measurement/calibration context. Pixel inputs are rejected because
a scale, lens correction and coordinate transform cannot be inferred from the CSV alone. Coordinates
are converted once to meters and written with unit="meters" and default conversion 1.0.
For a real shared clock, record the acquisition evidence, for example a shared DAQ counter that actually timestamps both streams. Similar nominal sampling rates and matching file creation dates are not evidence of shared timing.
"synchronization": {
"shared_clock_evidence": "Both vectors are acquisition DAQ counter timestamps, converted with its recorded tick rate"
}
For separate clocks, provide already matched pulse pairs; this helper does not discover
correspondences or correct missing pulses. The CSV columns are device_time_s,reference_time_s.
At least three distinct, increasing pairs must span the entire behavior interval. Specify the
maximum acceptable residual in seconds from the experiment's timing precision requirement:
"synchronization": {
"pulse_pairs_csv": "sync.csv",
"max_residual_s": 0.001
}
The fitted map is reference_seconds = slope * device_seconds + offset_seconds.
Evaluation centers device times at the first pulse to reduce loss of numerical precision. The
report preserves that origin, the centered intercept, each pulse residual and both clocks' support
intervals. All reference seconds use the explicit NWB timestamps_reference_time, equal to this
converter's session_start_time; device seconds must use the same device origin in behavior and
pulse CSVs. A shared clock requires a shared epoch as well as a shared tick rate.
Inspect residuals and drift over the session before choosing the tolerance. A small least-squares
residual from only three pulses does not rule out unobserved clock jumps between them; record pulse
coverage and acquisition interruptions. Pulse extrapolation is rejected even when a linear fit is
excellent. If pulses fail the model, segment on evidence or use dense event timestamps with an
independently tested converter; do not loosen the tolerance just to make validation pass.