cedalion.sigproc package

Submodules

cedalion.sigproc.artifact module

cedalion.sigproc.artifact.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, False indicates data included and True indicates motion artifacts.

References

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

cedalion.sigproc.artifact.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.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.quality module

Signal quality metrics and channel pruning.

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.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])

Module contents