bemobil_mne.io.align_stream_to_timestamps#

bemobil_mne.io.align_stream_to_timestamps(data, src_ts, tgt_ts, method='pchip', fill_value=nan, nan_gap_method='linear', max_nan_gap_s=None)[source]#

Align a data stream to a set of target timestamps.

The core alignment primitive for multimodal XDF recordings. Rather than resampling by target length (which discards timing information), this function uses the actual LSL timestamps of both the source stream and the target grid to evaluate the signal at the correct instants.

pyxdf corrects clock offsets between devices before returning timestamps, so the src_ts values passed here are already on a shared reference clock.

Parameters:
data(n_samples, n_channels) or (n_samples,)

Source data array.

src_ts(n_samples,)

LSL timestamps of the source samples (clock-corrected by pyxdf).

tgt_ts(n_target,)

Target LSL timestamps at which to evaluate the stream. Typically a uniform grid derived from the primary stream’s time range.

method{‘linear’, ‘pchip’, ‘sinc’, ‘nearest’, ‘stim’}

Alignment strategy.

'linear'

Fast piecewise-linear interpolation. Sufficient when the source and target rates are similar and the signal is smooth.

'pchip'

Piecewise Cubic Hermite Interpolating Polynomial [Fritsch & Carlson 1980]. Preserves local monotonicity and avoids the overshoot of natural cubic splines. Preferred for slow physiological signals (EDA, pupil diameter) and for large up-sampling ratios.

'sinc'

Applies an 8th-order zero-phase Butterworth anti-aliasing filter [Butterworth 1930; Widmann et al. 2015] at 90 % of the target Nyquist frequency before PCHIP interpolation. Use whenever the source rate exceeds the target rate (e.g. ECG or EMG at 1000-2000 Hz aligned to a 500 Hz common grid) to prevent aliasing of high-frequency energy into the passband [Shannon 1949].

'nearest'

Zero-order hold: each output sample takes the value of the nearest source sample in time. No interpolation is performed. Appropriate for discrete-valued channels where intermediate values are meaningless (e.g. a button-box channel that only ever holds 0 or 1).

'stim'

Timestamp-aware trigger/stimulus resampling [Gramfort et al. 2013]. For each output window, selects the first non-zero source value within that window, falling back to the first value if all are zero. Preserves trigger pulses that might otherwise be averaged away or missed by nearest-neighbor selection. Use for trigger channels, button boxes, or any channel encoding sparse events as non-zero pulses in an otherwise-zero baseline.

fill_valuefloat

Value assigned to target timestamps outside the source time range. Defaults to np.nan so out-of-range regions are clearly marked rather than silently extrapolated. For 'stim' the effective fill defaults to 0 (no event).

nan_gap_method{‘linear’, ‘pchip’}

Interpolation method used to bridge NaN runs within the source data before alignment. Not applied for 'nearest' or 'stim'.

max_nan_gap_sfloat or None

NaN runs in the source data longer than this (seconds) are preserved as NaN in the output. Shorter gaps are filled by nan_gap_method. None fills all gaps. Not applied for 'nearest' or 'stim'.

Returns:
aligned(n_target, n_channels)

Data evaluated at tgt_ts.

Parameters:
Return type:

ndarray