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])	Apply motion correction using PCA filter identified as motion artefact segments.
`motion_correct_PCA_recurse`(fNIRSdata[, ...])	Identify motion artefacts in input fNIRSdata.
`motion_correct_spline`(fNIRSdata, tIncCh, p)	Apply motion correction using spline interpolation to fNIRS data.
`motion_correct_splineSG`(fNIRSdata, p[, ...])	Apply motion correction using spline interpolation and Savitzky-Golay filter.
`motion_correct_wavelet`(od[, iqr, wavelet, level])	Wavelet-based motion correction, specializing in spike correction.
`normalize_signal`(signal[, wavelet])	Normalize signal by its noise level using MAD of downsampled coefficients.
`pad_to_power_2`(signal)	Pad signal to next power of 2.
`process_coefficients`(coeffs, iqr_factor, ...)	Deletes outlier coefficients based on IQR.
`tddr`(ts)	Implementation of the TDDR algorithm for motion correction.

cedalion.sigproc.motion_correct.motion_correct_spline( fNIRSdata: cdt.NDTimeSeries, tIncCh: 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:

fNIRSdata – The fNIRS data to be motion corrected.
tIncCh – 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]

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

Parameters:

fNIRSdata (cdt.NDTimeSeries) – The fNIRS data 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)

cedalion.sigproc.motion_correct.motion_correct_PCA( fNIRSdata: cdt.NDTimeSeries, tInc: cdt.NDTimeSeries, nSV: Quantity = 0.97, )[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:: fNIRSdata: The fNIRS data to be motion corrected. tInc: The time series indicating the presence of motion artifacts. nSV (Quantity): Specifies the number of prinicpal components to remove from the

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

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

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]

Identify motion artefacts in input fNIRSdata.

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

Parameters:

fNIRSdata (cdt.NDTimeSeries) – The fNIRS data 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.
nSV – FIXME
maxIter – FIXME

Returns:

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

Return type:

fNIRSdata_cleaned (cdt.NDTimeSeries)

cedalion.sigproc.motion_correct.tddr(ts: 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 [Fis18], which is the reference implementation for the algorithm described in [FLVM19].

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

References

Paper: [FLVM19] Code: [Fis18]

cedalion.sigproc.motion_correct.pad_to_power_2(signal)[source]: Pad signal to next power of 2.

cedalion.sigproc.motion_correct.process_coefficients(coeffs, iqr_factor, signal_length)[source]: Deletes outlier coefficients based on IQR.

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]

Wavelet-based motion correction, specializing in spike correction.

Implements the wavelet-based motion correction algorithm described in [MD12], 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: [MD12] Implementation based on Homer3 v1.80.2 “hmrR_MotionCorrectWavelet.m” and its dependencies ([HDFB09]).