cedalion.sigproc.motion_correct

Various algorithms for motion correction of fNIRS data.

Functions

`compute_window`(SegLength, dtShort, dtLong, fs)	Computes the window size.
`mad`(x)	Compute Median Absolute Deviation.
`motion_correct_PCA`(fNIRSdata, tInc[, nSV])
`motion_correct_PCA_recurse`(fNIRSdata[, ...])
`motion_correct_spline`(fNIRSdata, tIncCh, p)
`motion_correct_splineSG`(fNIRSdata, p[, ...])
`motion_correct_wavelet`(od[, iqr, wavelet, level])
`normalize_signal`(signal[, wavelet])	Normalize signal by its noise level using MAD of downsampled coefficients.
`pca`(ts, t_inc[, n_sv])	Apply motion correction using PCA filter identified as motion artefact segments.
`pca_recurse`(ts[, t_motion, t_mask, ...])	Identify motion artefacts in input time series ts.
`spline`(ts, t_inc_ch, p)	Apply motion correction using spline interpolation to fNIRS data.
`spline_sg`(ts, p[, frame_size])	Apply motion correction using spline interpolation and Savitzky-Golay filter.
`tddr`(ts)	Implementation of the TDDR algorithm for motion correction.
`wavelet`(od[, iqr, wavelet, level])	Wavelet-based motion correction, specializing in spike correction.

cedalion.sigproc.motion_correct.motion_correct_spline( fNIRSdata: cdt.NDTimeSeries, tIncCh: cdt.NDTimeSeries, p: float, ) → cdt.NDTimeSeries[source]

cedalion.sigproc.motion_correct.spline(ts: cdt.NDTimeSeries, t_inc_ch: cdt.NDTimeSeries, p: float) → cdt.NDTimeSeries[source]

Apply motion correction using spline interpolation to fNIRS data.

Based on Homer3 [1] v1.80.2 “hmrR_tInc_baselineshift_Ch_Nirs.m” Boston University Neurophotonics Center https://github.com/BUNPC/Homer3

Parameters:

ts – The time series to be motion corrected.
t_inc_ch – The time series indicating the presence of motion artifacts.
p – smoothing factor

Returns:

The motion-corrected fNIRS data.

Return type:

dodSpline (cdt.NDTimeSeries)

cedalion.sigproc.motion_correct.compute_window( SegLength: cdt.NDTimeSeries, dtShort: Quantity, dtLong: Quantity, fs: Quantity, )[source]

Computes the window size.

Window size is based on the segment length, short time interval, long time interval, and sampling frequency.

Parameters:

SegLength (cdt.NDTimeSeries) – The length of the segment.
dtShort (Quantity) – The short time interval.
dtLong (Quantity) – The long time interval.
fs (Quantity) – The sampling frequency.

Returns:

The computed window size.

Return type:

wind

cedalion.sigproc.motion_correct.motion_correct_splineSG( fNIRSdata: cdt.NDTimeSeries, p: float, frame_size: Quantity = <Quantity(10, 'second')>, )[source]

cedalion.sigproc.motion_correct.spline_sg( ts: cdt.NDTimeSeries, p: float, frame_size: cdt.QTime = <Quantity(10, 'second')>, )[source]

Apply motion correction using spline interpolation and Savitzky-Golay filter.

Parameters:

ts – The time series to be motion corrected.
frame_size (Quantity) – The size of the sliding window in seconds for the Savitzky-Golay filter. Default is 10 seconds.
p – smoothing factor

Returns:

The motion-corrected fNIRS data after applying spline interpolation and Savitzky-Golay filter.

Return type:

dodSplineSG (cdt.NDTimeSeries)

References

Paper: [JSBY18]

cedalion.sigproc.motion_correct.motion_correct_PCA( fNIRSdata: cdt.NDTimeSeries, tInc: cdt.NDTimeSeries, nSV: Quantity = 0.97, )[source]

cedalion.sigproc.motion_correct.pca( ts: cdt.NDTimeSeries, t_inc: cdt.NDTimeSeries, n_sv: float = 0.97, ) → tuple[TypeAliasForwardRef('cdt.NDTimeSeries'), int, ndarray][source]

Apply motion correction using PCA filter identified as motion artefact segments.

Based on Homer3 [1] v1.80.2 “hmrR_MotionCorrectPCA.m” Boston University Neurophotonics Center https://github.com/BUNPC/Homer3

Inputs:: ts: The time series to be motion corrected. t_inc: The time series indicating the presence of motion artifacts. n_sv: Specifies the number of prinicpal components to remove from the

data. If n_sv < 1 then the filter removes the first n components of the data that removes a fraction of the variance up to n_sv.

Returns:: The motion-corrected fNIRS data. n_sv (int): the number of principal components removed from the data. svs (np.array): the singular values of the PCA.
Return type:: ts_cleaned (cdt.NDTimeSeries)

References

Paper & Code: [HDFB09]

cedalion.sigproc.motion_correct.motion_correct_PCA_recurse( fNIRSdata: cdt.NDTimeSeries, t_motion: Quantity = 0.5, t_mask: Quantity = 1, stdev_thresh: Quantity = 20, amp_thresh: Quantity = 5, nSV: Quantity = 0.97, maxIter: Quantity = 5, )[source]

cedalion.sigproc.motion_correct.pca_recurse( ts: cdt.NDTimeSeries, t_motion: cdt.QTime = <Quantity(0.5, 'second')>, t_mask: cdt.QTime = <Quantity(1, 'second')>, stdev_thresh: float = 20, amp_thresh: float = 5, n_sv: float = 0.97, max_iter: int = 5, ) → tuple[cdt.NDTimeSeries, np.ndarray, int][source]

Identify motion artefacts in input time series ts.

If any active channel exhibits signal change greater than stdev_thresh or amp_thresh, then that segment of data is marked as a motion artefact. pca is applied to all segments of data identified as a motion artefact. This is called until max_iter is reached or there are no motion artefacts identified.

Parameters:

ts – The time series to be motion corrected.
t_motion – check for signal change indicative of a motion artefact over time range tMotion. (units of seconds)
t_mask (Quantity) – mark data +/- tMask seconds aroundthe identified motion artefact as a motion artefact.
stdev_thresh (Quantity) – if the signal d for any given active channel changes by more than stdev_thresh * stdev(d) over the time interval tMotion then this time point is marked as a motion artefact.
amp_thresh (Quantity) – if the signal d for any given active channel changes by more than amp_thresh over the time interval tMotion then this time point is marked as a motion artefact.
n_sv – Specifies the number of prinicpal components to remove from the data. If n_sv < 1 then the filter removes the first n components of the data that removes a fraction of the variance up to n_sv.
max_iter – maximum number of iterations.

Returns:

The motion-corrected fNIRS data. svs (np.array): the singular values of the PCA. n_sv (int): the number of principal components removed from the data. t_inc (np.ndarray): remaining motion artifacts

Return type:

ts_cleaned (cdt.NDTimeSeries)

References

Paper & Code: [HDFB09]

cedalion.sigproc.motion_correct.tddr(ts: cdt.NDTimeSeries) → cdt.NDTimeSeries[source]

Implementation of the TDDR algorithm for motion correction.

Uses an iterative reweighting approach to reduce large fluctuations typically associated with motion artifacts. Adapted for cedalion from the python implementation at [], which is the reference implementation for the algorithm described in [].

Parameters:: ts – The time series to be corrected. Should have dims channel and wavelength
Returns:: The corrected time series.

References

Paper: [] Code: []

cedalion.sigproc.motion_correct.mad(x)[source]: Compute Median Absolute Deviation.

cedalion.sigproc.motion_correct.normalize_signal(signal, wavelet='db2')[source]

Normalize signal by its noise level using MAD of downsampled coefficients.

Implements Homer3’s NormalizationNoise function.

Parameters:

signal – 1D numpy array containing the signal to normalize
wavelet – wavelet to use (default: ‘db2’)

Returns:

normalized version of input signal norm_coef: normalization coefficient (multiply by this to denormalize)

Return type:

normalized_signal

References

[HDFB09]

cedalion.sigproc.motion_correct.motion_correct_wavelet(od, iqr=1.5, wavelet='db2', level=4)[source]

cedalion.sigproc.motion_correct.wavelet(od, iqr=1.5, wavelet='db2', level=4)[source]

Wavelet-based motion correction, specializing in spike correction.

Implements the wavelet-based motion correction algorithm described in [], closely following the MATLAB implementation found in Homer3 ([HDFB09])

Parameters:

od – The time series to be corrected. Should have dims channel and wavelength
iqr – The interquartile range factor for outlier detection. Set to -1 to disable. Increasing iqr will delete less coefficients.
wavelet – The wavelet to use for decomposition (default: ‘db2’)
level – The level of decomposition to use (default: 4)

Returns:

The corrected time series.

References

Original paper: [] Implementation based on Homer3 v1.80.2 “hmrR_MotionCorrectWavelet.m” and its dependencies ([HDFB09]).