cedalion.sigproc package

Submodules

cedalion.sigproc.frequency module

Frequency-related signal processing methods.

cedalion.sigproc.frequency.freq_filter(timeseries, fmin, fmax, butter_order=4)

Apply a Butterworth bandpass frequency filter.

Parameters:

  • timeseries (NDTimeSeries, (time,*)) – the input time series

  • fmin (Quantity, [frequency]) – lower threshold of the pass band

  • fmax (Quantity, [frequency]) – higher threshold of the pass band

  • butter_order (int) – order of the filter

Return type:

DataArray

Returns:

The frequency-filtered time series

cedalion.sigproc.frequency.sampling_rate(timeseries)

Estimate the sampling rate of the timeseries.

Note

This functions assumes uniform sampling.

Parameters:

timeseries (NDTimeSeries, (time,*)) – the input time series

Return type:

Quantity

Returns:

The sampling rate estimated by averaging time differences between samples.

cedalion.sigproc.motion_correct module

cedalion.sigproc.motion_correct.compute_window(SegLength, dtShort, dtLong, fs)

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_PCA(fNIRSdata, tInc, nSV=0.97)

Apply motion correction using PCA filter idenitfied 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, t_motion=0.5, t_mask=1, stdev_thresh=20, amp_thresh=5, nSV=0.97, maxIter=5)

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 (Quantity) – 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 (Quantity) – FIXME

  • maxIter (Quantity) – 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.motion_correct_spline(fNIRSdata, tIncCh)

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 (DataArray) – The fNIRS data to be motion corrected.

  • tIncCh (DataArray) – The time series indicating the presence of motion artifacts.

Returns:

The motion-corrected fNIRS data.

Return type:

dodSpline (cdt.NDTimeSeries)

cedalion.sigproc.motion_correct.motion_correct_splineSG(fNIRSdata, framesize_sec=10)

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

Parameters:

  • fNIRSdata (cdt.NDTimeSeries) – The fNIRS data to be motion corrected.

  • framesize_sec (Quantity) – The size of the sliding window in seconds for the Savitzky-Golay filter. Default is 10 seconds.

Returns:

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

Return type:

dodSplineSG (cdt.NDTimeSeries)

cedalion.sigproc.quality module

Signal quality metrics and channel pruning functionality.

cedalion.sigproc.quality.detect_baselineshift(ts, outlier_mask)
cedalion.sigproc.quality.detect_outliers(ts, t_window_std, iqr_threshold_std=2, iqr_threshold_grad=1.5)
cedalion.sigproc.quality.detect_outliers_grad(ts, iqr_threshold=1.5)

Detect outliers in fNIRSdata based on gradient of signal.

cedalion.sigproc.quality.detect_outliers_std(ts, t_window, iqr_threshold=2)

Detect outliers in fNIRSdata based on standard deviation of signal.

cedalion.sigproc.quality.id_motion(fNIRSdata, t_motion=<Quantity(0.5, 'second')>, t_mask=<Quantity(1.0, 'second')>, stdev_thresh=50.0, amp_thresh=5.0)

Identify motion artifacts in an fNIRS input data array.

If any active data channel exhibits a signal change greater than std_thresh or amp_thresh, then a segment of data around that time point is marked as a motion artifact.

Parameters:

  • fNIRSdata (NDTimeSeries, (time, channel, *)) – input time series

  • t_motion (Quantity, [time]) – time interval for motion artifact detection. Checks for signal change indicative of a motion artifact over time range t_motion.

  • t_mask (Quantity, [time]) – time range to mask around motion artifacts. Mark data over +/- t_mask around the identified motion artifact as a motion artifact.

  • stdev_thresh (float) – threshold for std deviation of signal change. 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 artifact. The standard deviation is determined for each channel independently. Typical value ranges from 5 to 20. Use a value of 100 or greater if you wish for this condition to not find motion artifacts.

  • amp_thresh (float) – threshold for amplitude of signal change. If the signal d for any given active channel changes by more that amp_thresh over the time interval t_motion, then this time point is marked as a motion artifact. Typical value ranges from 0.01 to 0.3 for optical density units. Use a value greater than 100 if you wish for this condition to not find motion artifacts.

Return type:

DataArray

Returns:

a DataArray that has at least the dimensions channel and time, dtype is boolean. At each time point, CLEAN indicates data included and TAINTED indicates motion artifacts.

References

Based on Homer3 v1.80.2 “hmR_MotionArtifact.m” and “hmR_MotionArtifactByChannel” (Huppert et al. [HDFB09]).

cedalion.sigproc.quality.id_motion_refine(ma_mask, operator)

Refines motion artifact mask to simplify and quantify motion artifacts.

:param ma_mask NDTimeSeries: motion artifact mask as :type ma_mask NDTimeSeries: time, channel, * :param : motion artifact mask as :type : time, channel, * :param generated by id_motion().: :type operator: str :param operator: operation to apply to the mask. Available operators:

  • “by_channel”: collapses the mask along the amplitude/wavelength/chromo

    dimension to provide a single motion artifact mask per channel (default) over time

  • “all”: collapses the mask along all dimensions to provide a single motion

    artifact marker for all channels over time i.e. an artifact detected in any channel masks all channels.

Returns:

A tuple (ma_mask_new, ma_info), where ma_mask_new is the updated motion artifact mask, collapsed according to operator and ma_info is a pandas.DataFrame that contains 1) channels with motion artifacts, 2) # of artifacts detected per channel and 3) fraction of artifacts/total time.

cedalion.sigproc.quality.mean_amp(amplitudes, amp_range)

Calculate mean amplitudes and mask channels outside amplitude range.

Parameters:

  • amplitudes (NDTimeSeries, (time, *)) – input time series

  • amp_range (tuple[Quantity, Quantity]) – if amplitudes.mean(“time”) < amp_threshs[0] or > amp_threshs[1] then it is excluded as an active channel in amp_mask

Returns:

A tuple (mean_amp, amp_mask), where mean_amp is DataArray with coords from input NDTimeseries containing the amplitudes averaged over time. The boolean DataArray amp_mask is true where amp_threshs are met

References

Based on Homer3 v1.80.2 “hmR_PruneChannels.m” (Huppert et al. [HDFB09])

cedalion.sigproc.quality.prune_ch(amplitudes, masks, operator)

Prune channels from the the input data array using quality masks.

Parameters:

  • amplitudes (NDTimeSeries) – input time series

  • masks (list[NDTimeSeries]) – list of boolean masks with coordinates comptabile to amplitudes

  • operator (str) –

    operators for combination of masks before pruning data_array

    • ”all”: logical AND, keeps channel if it is good across all masks

    • ”any”: logical OR, keeps channel if it is good in any mask/metric

Returns:

A tuple (amplitudes_pruned, prune_list), where amplitudes_pruned is a the original time series channels pruned (dropped) according to quality masks. A list of removed channels is returned in prune_list.

cedalion.sigproc.quality.psp(amplitudes, window_length, psp_thresh)
cedalion.sigproc.quality.sci(amplitudes, window_length, sci_thresh)

Calculate the scalp-coupling index.

The scalp-coupling index metric is based on Pollonini et al. [POA+14] / Pollonini et al. [PBO16].

Parameters:

  • amplitudes (NDTimeSeries, (channel, wavelength, time)) – input time series

  • window_length (Quantity, [time]) – size of the computation window

  • sci_thresh (float) – if the calculated SCI metric falls below this threshold then the corresponding time window should be excluded.

Returns:

A tuple (sci, sci_mask), where sci is a DataArray with coords from the input NDTimeseries containing the scalp-coupling index. Sci_mask is a boolean mask DataArray with coords from sci, true where sci_thresh is met.

cedalion.sigproc.quality.sd_dist(amplitudes, geo3D, sd_range=(<Quantity(0, 'centimeter')>, <Quantity(4.5, 'centimeter')>))

Calculate source-detector separations and mask channels outside a distance range.

Parameters:

  • amplitudes (NDTimeSeries, (channel, *)) – input time series

  • geo3D (LabeledPointCloud) – 3D optode coordinates

  • sd_range (tuple[Quantity, Quantity]) – if source-detector separation < sd_range[0] or > sd_range[1] then it is excluded as an active channelin sd_mask

Returns:

A tuple (sd_dist, sd_mask), where sd_dist contains the channel distances and sd_mask is a boolean NDTimeSeries, indicating where distances fall into sd_range.

References

Based on Homer3 v1.80.2 “hmR_PruneChannels.m” (Huppert et al. [HDFB09])

cedalion.sigproc.quality.snr(amplitudes, snr_thresh=2.0)

Calculates signal-to-noise ratio for each channel and other dimension.

Parameters:

  • amplitudes (NDTimeSeries, (time, *)) – the input time series

  • snr_thresh (float) – threshold (unitless) below which a channel should be excluded.

Returns:

A tuple (snr, snr_mask) , where snr is a DataArray with coords from input NDTimeseries containing the ratio between mean and std of the amplitude signal for all channels. snr_mask is a boolean mask DataArray with the same coords as snr, true where snr_threshold is met.

References

Based on Homer3 v1.80.2 “hmR_PruneChannels.m” (Huppert et al. [HDFB09])

cedalion.sigproc.tasks module

cedalion.sigproc.tasks.int2od(rec, ts_input=None, ts_output='od')

Calculate optical density from intensity amplitude data.

Parameters:

  • rec (Recording) – container of timeseries data

  • ts_input (str) – name of intensity timeseries. If None, this tasks operates on the last timeseries in rec.timeseries.

  • ts_output (str) – name of optical density timeseries.

cedalion.sigproc.tasks.od2conc(rec, dpf, spectrum='prahl', ts_input=None, ts_output='conc')

Calculate hemoglobin concentrations from optical density data.

Parameters:

  • rec (Recording) – container of timeseries data

  • dpf (dict[float, float]) – differential path length factors

  • spectrum (str) – label of the extinction coefficients to use

  • ts_input (str | None) – name of intensity timeseries. If None, this tasks operates on the last timeseries in rec.timeseries.

  • ts_output (str) – name of optical density timeseries.

cedalion.sigproc.tasks.sd_dist(rec, sd_min, sd_max, ts_input=None, aux_obj_output='sd_dist', mask_output='sd_dist')
cedalion.sigproc.tasks.snr(rec, snr_thresh=2.0, ts_input=None, aux_obj_output='snr', mask_output='snr')

Module contents