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:

find_period()
create_filter()
filter_data()

Parameters:

datanumpy.ndarray, 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.

References

Attributes:

data: Return a copy of the data.
filter: Return a copy of the PARRM filter.
filtered_data: Return a copy of the most recently filtered data.
period: Return a copy of the estimated stimulation period.
settings: 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.

Find the period of the artefacts.

Parameters:

search_samplesnumpy.ndarray | 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_seed: int | 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] | None = None, time_res: int | float = 0.01, freq_range: list[int] | 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:

datanumpy.ndarray, shape of (channels, times) | None (default None): The data to filter. If None, data is used.

Returns:

filtered_datanumpy.ndarray, shape of (channels, times): The filtered, artefact-free data.

property data: ndarray#: Return a copy of the data.

property period: float#: Return a copy of the estimated stimulation period.

property filter: ndarray#: Return a copy of the PARRM filter.

property filtered_data: ndarray#: Return a copy of the most recently filtered data.

property settings: dict#: Return the settings used to generate the PARRM filter.