response_review_stats.analysisRun.alignSegments

Description

Shifts each segment's time axis to a common alignment origin, constructs a shared uniformly spaced grid, and linearly interpolates every trace onto that grid. Duplicate source timestamps retain their first sample. Values outside a segment's aligned source range remain NaN. An optional baseline subtraction is performed after interpolation.

Inputs

segments

Structure array with timeSec and values vectors of matching length and a name value for each segment. A segment-specific alignTimeSec may identify the source time that should become zero.

opts

Optional scalar structure containing the alignment options below.

Options

sampleIntervalSec

Positive output-grid interval in seconds. When omitted, the median of every finite positive source time difference is used. If no source supplies a usable difference, the fallback is 0.0001 seconds.

windowSec

Two-element [start end] output interval in aligned seconds. When omitted, the function uses the intersection of all source ranges after alignment-time shifts.

alignTimeSec

Global source time shifted to zero for segments without their own alignTimeSec field. Default: 0 seconds.

baselineWindowSec

Optional inclusive [start end] interval in aligned seconds. The finite mean in this output-grid interval is subtracted from the entire corresponding segment. Default: no subtraction.

Outputs

aligned

Scalar structure with these fields:

Aligned Fields

timeSec

G-by-1 uniformly spaced aligned time vector in seconds.

values

G-by-N double matrix with one interpolated segment per column.

segmentNames

N-by-1 string vector copied from segments.name.

status

"ok", or "empty" when segments is empty.

Failure Behavior

Empty segments returns stable empty arrays with status="empty". Nonempty elements must provide compatible timeSec, values, and name fields; invalid option intervals, disjoint derived ranges, or interpolation-incompatible data propagate the originating MATLAB field, colon, or interp1 error.

Example

segments = struct( ...
"timeSec", {[10; 11; 12], [20; 21; 22]}, ...
"values", {[1; 2; 3], [4; 5; 6]}, ...
"name", {"first", "second"}, ...
"alignTimeSec", {10, 20});
aligned = response_review_stats.analysisRun.alignSegments( ...
segments, struct("sampleIntervalSec", 1));
assert(isequal(aligned.timeSec, [0; 1; 2]))
assert(isequal(aligned.values, [1 4; 2 5; 3 6]))