pyparrm.parrm.PARRM#

class pyparrm.parrm.PARRM(data: ndarray, sampling_freq: int | float, artefact_freq: int | float, verbose: bool = True)[source]#

Class for removing stimulation artefacts from data using PARRM.

The Period-based Artefact Reconstruction and Removal Method (PARRM) is described in Dastin-van Rijn et al. (2021) [1]. PARRM assumes that the artefacts are semi-regular, periodic, and linearly combined with the signal of interest.

The methods should be called in the following order:

  1. find_period()

  2. create_filter()

  3. filter_data()

Parameters:
datandarray, shape of [channels, times]

Time-series from which stimulation artefacts should be identified and removed.

sampling_freqint | float

Sampling frequency of data, in Hz.

artefact_freqint | float

Frequency of the stimulation artefact in data, in Hz.

verbosebool (default True)

Whether or not to print information about the status of the processing.

Attributes:
datandarray, shape of [channels, times]

Return the data.

periodfloat

Return the estimated stimulation period.

filterndarray, shape of [times]

Return the PARRM filter.

filtered_datandarray, shape of [channels, times]

Return the most recently filtered data.

settingsdict

Return the settings used to generate the PARRM filter.

Methods

find_period([search_samples, ...])

Find the period of the artefacts.

explore_filter_params([time_range, ...])

Create an interactive plot to explore filter parameters.

create_filter([filter_half_width, ...])

Create the PARRM filter for removing the stimulation artefacts.

filter_data([data])

Apply the PARRM filter to the data and return it.

References

find_period(search_samples: ndarray | None = None, assumed_periods: int | float | tuple[int | float] | None = None, outlier_boundary: int | float = 3.0, random_seed: int | None = None, n_jobs: int = 1) → None[source]#

Find the period of the artefacts.

Parameters:
search_samplesndarray | None (default None), shape of [times]

Samples of data to use when finding the artefact period. If None, all samples are used.

assumed_periodsint | float | tuple[int or float] | None (default None)

Guess(es) of the artefact period. If None, the period is assumed to be sampling_freq / artefact_freq.

outlier_boundaryint | float (default 3.0)

Boundary (in standard deviation) to consider outlier values in data.

random_seedint | None (default None)

Seed to use when generating indices of samples to search for the period. Only used if the number of available samples is less than the number of requested samples.

n_jobsint (default 1)

Number of jobs to run in parallel when optimising the period estimates. Must lie in the range [1, number of CPUs] (unless it is -1, in which case all available CPUs are used).

explore_filter_params(time_range: list[int | float] | None = None, time_res: int | float = 0.01, freq_range: list[int | float] | None = None, freq_res: int | float = 5.0, n_jobs: int = 1) → None[source]#

Create an interactive plot to explore filter parameters.

Can only be called after the artefact period has been estimated with find_period().

Parameters:
time_rangelist of int or float | None (default None)

Range of the times to plot and filter in a list of length two, containing the first and last timepoints, respectively, in seconds. If None, all timepoints are used.

time_resint | float (default 0.01)

Time resolution, in seconds, to use when plotting the time-series data.

freq_rangelist of int or float | None (default None)

Range of the frequencies to plot in a list of length two, containing the first and last frequencies, respectively, in Hz. If None, all frequencies are used.

freq_resint | float (default 5.0)

Frequency resolution, in Hz, to use when computing the power spectra of the data.

n_jobsint (default 1)

Number of jobs to run in parallel when computing the power spectra. Must lie in the range [1, number of CPUs] (unless it is -1, in which case all available CPUs are used).

Notes

It is recommended that you call this method from a script; behaviour in notebooks is not guaranteed!

create_filter(filter_half_width: int | None = None, omit_n_samples: int = 0, filter_direction: str = 'both', period_half_width: int | float | None = None) → None[source]#

Create the PARRM filter for removing the stimulation artefacts.

Can only be called after the artefact period has been estimated with find_period().

Parameters:
filter_half_widthint | None (default None)

Half-width of the filter to create, in samples. If None, a filter half-width will be generated based on omit_n_samples.

omit_n_samplesint (default 0)

Number of samples to omit from the centre of filter_half_width.

filter_directionstr (default “both”)

Direction from which samples should be taken to create the filter, relative to the centre of the filter window. Can be: "both" for backward and forward samples; "past" for backward samples only; and "future" for forward samples only.

period_half_widthint | float | None (default None)

Half-width of the window in samples of period space for which points at a similar location in the waveform will be averaged. If None, period / 50 is used.

filter_data(data: ndarray | None = None) → ndarray[source]#

Apply the PARRM filter to the data and return it.

Can only be called after the filter has been created with create_filter().

Parameters:
datandarray, shape of [channels, times] | None (default None)

The data to filter. If None, data is used.

Returns:
filtered_datandarray, shape of [channels, times]

The filtered, artefact-free data.

property data: ndarray#

Return the data.

property period: float#

Return the estimated stimulation period.

property filter: ndarray#

Return the PARRM filter.

property filtered_data: ndarray#

Return the most recently filtered data.

property settings: dict#

Return the settings used to generate the PARRM filter.