Version 2.0 release and migration notes

Re-running an analysis may change its numeric output.
Version 2.0 adds consistent NaN omission and zero-denominator protection across the analysis stack. Results produced from masked data are therefore not bit-comparable with the previous release. These differences are expected corrections, but historical and new outputs should not be pooled without deliberate validation.

Before reusing an existing processed folder

Version 2.0 reads previous-release per-channel metadata sidecars as the authority for processed frame dimensions, frame count, and channel frame rate. If a legacy folder has no usable sidecar, umIT cross-checks the frame count inferred from AcqInfos.mat against the acquisition's recorded length. A binned or cropped folder whose geometry cannot be proved is blocked with a clear compatibility error instead of being processed with an incorrect frame count. Restore the original sidecars or reprocess from raw data when this occurs.

The pre-changeover implementation is preserved by the Git tag pre-dev-changeover.

Changes that affect scientific results

• Events and triggers: negative-polarity automatic thresholding, biphasic detection, unmatched-edge repair, and EdgeToggle handling were revised. Event timestamps can change, which shifts every event-locked result.
• Event baseline: events.mat baselinePeriod is authoritative. Its automatic value is 20% of the shortest onset interval. The previous split-data fallback used 20% of a rounded mean interval and could select a longer window.
• Retinotopy: non-average mode concatenates only stimulus ON-to-OFF epochs before the FFT; inter-stimulus gaps are excluded. The previous release transformed one contiguous span. Amplitude, phase, azimuth, elevation, and visual-sign maps can all change.
• Retinotopy visual angle and smoothing: when the screen geometry is given, the fixed phase range 0 to 2π (not the observed minimum and maximum of each map) is mapped linearly onto the visual-angle range, so degree maps no longer depend on which phase values a recording contains. In genVSM, radian phase maps are smoothed through exp(i·phase) instead of directly, which is correct across the 0/2π wrap. Degree maps, visual-sign maps, and ROIs from the previous release are not numerically comparable.
• Response features: the current path treats event-axis slices individually; the baseline statistic changed from mean to median, AUC is computed from the baseline-corrected response window, the all window reaches the end of the record, and latency starts at the first response frame.
• Amplitude maps: repetitions are pooled by condition, the response window is shifted by one frame, and the constant-value option was removed.
• Detrending: the terminal median window and event-baseline source changed.
• Temporal filtering: the clamped array-path low-pass cutoff was harmonized with the file-backed path.
• Trial splitting: trials are truncated to the shortest valid length; PadWith was removed and dimensions changed from {E,Y,X,T} to {Y,X,T,E}.
• Speckle mapping: the wrapper reads the named raw channel from the SaveFolder instead of consuming an upstream array. Until the next signature revision, standard and RAM-safe run_Ana_Speckle paths may still resolve different filenames and emit a warning.
• Speckle blood flow: Ana_Speckle now calculates one flow frame for every raw speckle frame. Its timeline therefore changes from T-1 to the full source length T; the added last sample can also affect the trailing temporal-median window and normalized output.
• Hemodynamics: Rig Store optical spectra and per-channel camera responses are preferred when available, which is required for dual-camera rigs and can change HbO/HbR scaling.

Breaking changes

Removed analysis functions

trim_movie, transformDat2Mat, normalizeCOND, SPCM, alignFrames, calculate_response_amplitude, getEventsFromCSV, MV_gen_SF_TF_matrix, MVcalculate_SF_TF_average, and mergeDirs_in_eventFile. Saved pipelines that reference these functions must be rebuilt.

Removed capabilities

• HemoCompute no longer accepts four-dimensional {E,Y,X,T} input.
• Two-output run_HemoCompute calls now return the backing filenames HbO.dat and HbR.dat in every RAM mode. Use loadData or call the lower-level HemoCompute directly when numeric arrays are required.
• SpeckleMapping no longer accepts numeric-array input.
• apply_aggregate_function no longer supports mode, a list of multiple dimensions, or the previous E semantics.
• normalizeBSLN no longer accepts numeric baseline_sec for event data.
• Legacy rChan/yChan/gChan channel resolution was removed from hemodynamic correction.
• The standalone system-optical-spectra editor and its TXT spectral-profile importer were retired. Manage illumination, camera, and filter spectra through the Rig Manager's Optical Library instead; it was verified to reproduce the retired editor's hemodynamic calculation exactly for the shipped spectrum library.

Files and metadata

• The run_HemoCorrection wrapper writes hemoCorr_fluo.dat in every file-returning mode; fluoHemoCorr.dat remains an internal legacy-core name.
• Ana_Speckle outputs Flow.dat instead of Flow.umt. Standard mode returns a single Y,X,T array; RAM-safe mode returns the full path to the raw Flow.dat file.
• tform.mat became tformDualCam.mat.
• Several previous .dat plus .mat result pairs are now self-describing .umt files.
• AcqInfoStream.Width/Height now describe processed frames, and BinningSpatial replaces the previous overloaded Binning field.
• New imports no longer write per-channel metadata sidecars.

Some invalid or ambiguous datasets now stop with an error instead of falling back silently, including retinotopy recordings whose first baseline cannot fit, out-of-range response windows, hemodynamic low-pass cutoffs at or above Nyquist, and unknown camera models used for optical pathlength calculation.

Corrections to previous-release results

Users should consider re-running affected analyses when any of the following applies:

• A drawn, non-square or non-symmetric import ROI was used. The previous preview could swap X and Y when applying the crop.
• A visual sign map was generated. The previous implementation could mask elevation phase with the azimuth NaN mask.
• HemoCompute processed a width not divisible by 16. The previous implementation could leave the rightmost columns zero-filled.

Three additional previous-release problems failed visibly rather than producing plausible results: masked unchunked GSR could return all NaNs, non-square normalized HemoCompute could stop with an error, and saved HemoCorrection output could be overwritten with incompatible MAT content.