BaseEventPipe

Tip

🚨 Abstract Class - This class is abstract and cannot be used directly. Subclass it and implement the required methods.

class sleepeegpy.base.BaseEventPipe(*, prec_pipe=None, path_to_eeg=NOTHING, output_dir=NOTHING, path_to_hypno=None, hypno_freq=NOTHING, hypno=NOTHING)

Bases: BaseHypnoPipe, ABC

A base class for event detection.

Methods:

compute_tfr	Transforms the events signal to time-frequency representation.
detect	Each event class should contain the detection method
interpolate_bads	A wrapper for mne.io.Raw.interpolate_bads()
plot	A wrapper for mne.io.Raw.plot().
plot_average	Plot average of the detected event.
plot_sensors	A wrapper for mne.viz.plot_sensors() with a legend.
plot_topomap	Plots topomap for a sleep stage and some property of detected events.
plot_topomap_collage	Plots topomap collage for multiple sleep stages and event properties.
predict_hypno	Runs YASA's automatic sleep staging.
read_tfrs	Loads TFRs stored in hdf5 files.
save_raw	A wrapper for mne.io.Raw.save().
set_eeg_reference	A wrapper for mne.io.Raw.set_eeg_reference().
sleep_stats	A wrapper for yasa.sleep_statistics().

Attributes:

bad_data_percent	Calculates percent of data segments annotated as BAD.
sf	A wrapper for raw.info["sfreq"].
tfrs	Instances of mne.time_frequency.AverageTFR per sleep stage.
results	Event detection results as returned by YASA's event detection methods.
path_to_hypno	Path to hypnogram.
hypno_freq	Sampling rate of the hypnogram in Hz.
hypno	Hypnogram with sampling frequency hypno_freq with int representing sleep stage.
hypno_up	Hypnogram upsampled to the sampling frequency of the raw data.
prec_pipe	Preceding pipe that hands over mne_raw object and output_dir.
path_to_eeg	Can be any eeg file type supported by mne.io.read_raw().
output_dir	Path to the directory where the output will be saved.
mne_raw	An instanse of mne.io.Raw.

results

Event detection results as returned by YASA’s event detection methods. Depending on the child class can be instance of either yasa.SpindlesResults, yasa.SWResults or yasa.REMResults classes.

tfrs: dict

Instances of mne.time_frequency.AverageTFR per sleep stage.

abstract detect()

Each event class should contain the detection method

plot_average(save=False, **kwargs)

Plot average of the detected event.

Parameters:

• save (bool) – Whether to save the figure to file. Defaults to False.

• **kwargs – Arguments passed to the YASA’s plot_average().

property bad_data_percent

Calculates percent of data segments annotated as BAD.

Returns:

percent of bad data spans in raw data

Return type:

float

interpolate_bads(**interp_kwargs)

A wrapper for mne.io.Raw.interpolate_bads()

Parameters:

**interp_kwargs – Arguments passed to mne.io.Raw.interpolate_bads().

plot(save_annotations=False, save_bad_channels=False, overwrite=False, **kwargs)

A wrapper for mne.io.Raw.plot().

Parameters:

• save_annotations (bool) – Whether to save annotations as txt. Defaults to False.

• save_bad_channels (bool) – Whether to save bad channels as txt. Defaults to False.

• overwrite (bool) – Whether to overwrite annotations and bad_channels files if exist. Defaults to False.

• **kwargs – Arguments passed to mne.io.Raw.plot().

plot_sensors(legend=None, legend_args=None, **kwargs)

A wrapper for mne.viz.plot_sensors() with a legend.

Parameters:

• legend (Iterable[str]) – ch_groups names to connect to colors. Defaults to None.

• legend_args (dict) – Arguments passed to matplotlib.axes.Axes.legend(). Defaults to None.

• **kwargs – Arguments passed to mne.viz.plot_sensors().

plot_topomap(prop, stage='N2', aggfunc='mean', sleep_stages={'N1': 1, 'N2': 2, 'N3': 3, 'REM': 4, 'Wake': 0}, axis=None, save=False, topomap_args=None, cbar_args=None)

Plots topomap for a sleep stage and some property of detected events.

Parameters:

• prop (str) – Any event property returned by self.results.summary().

• stage (str) – One of the sleep_stages keys. Defaults to “N2”.

• aggfunc (str) – Averaging function, “mean” or “median”. Defaults to “mean”.

• sleep_stages (dict) – Mapping between sleep stages names and their integer representations. Defaults to {“Wake”: 0, “N1”: 1, “N2”: 2, “N3”: 3, “REM”: 4}.

• axis (axis) – Instance of matplotlib.axes.Axes. Defaults to None.

• save (bool) – Whether to save the figure. Defaults to False.

• topomap_args (dict) – Arguments passed to mne.viz.plot_topomap().Defaults to None.

• cbar_args (dict) – Arguments passed to matplotlib.pyplot.colorbar().Defaults to None.

predict_hypno(eeg_name='E183', eog_name='E252', emg_name='E247', ref_name='E26', save=True)

Runs YASA’s automatic sleep staging.

Parameters:

• eeg_name (str) – Preferentially a central electrode. Defaults to “E183”.

• eog_name (str) – Preferentially, the left LOC channel. Defaults to “E252”.

• emg_name (str) – Preferentially a chin electrode. Defaults to “E247”.

• ref_name (str) – Reference channel, preferentially a mastoid. Defaults to “E26”.

• save (bool) – Whether to save the hypnogram to file. Defaults to True.

save_raw(fname, **kwargs)

A wrapper for mne.io.Raw.save().

Parameters:

• fname (str) – Filename for the fif file being saved.

• **kwargs – Arguments passed to mne.io.Raw.save().

set_eeg_reference(ref_channels='average', projection=False, **kwargs)

A wrapper for mne.io.Raw.set_eeg_reference().

Parameters:

• ref_channels – ref_channels. Defaults to ‘average’.

• projection – projection. Defaults to False.

• **kwargs – Additional arguments passed to mne.io.Raw.set_eeg_reference().

property sf

A wrapper for raw.info["sfreq"].

Returns:

sampling frequency

Return type:

float

sleep_stats(save=False)

A wrapper for yasa.sleep_statistics().

Parameters:

save (bool) – Whether to save the stats to csv. Defaults to False.

path_to_hypno: Path

Path to hypnogram. Must be text file with every row being int representing sleep stage for the epoch.

hypno_freq: float

Sampling rate of the hypnogram in Hz.

E.g., 1/30 means 1 sample per 30 secs epoch, 250 means 1 sample per 1/250 sec epoch.

hypno: ndarray

Hypnogram with sampling frequency hypno_freq with int representing sleep stage.

hypno_up: array

Hypnogram upsampled to the sampling frequency of the raw data.

prec_pipe: Type[TypeVar(BasePipeType, bound= BasePipe)]

Preceding pipe that hands over mne_raw object and output_dir.

path_to_eeg: Path

Can be any eeg file type supported by mne.io.read_raw().

output_dir: Path

Path to the directory where the output will be saved.

mne_raw: Raw

An instanse of mne.io.Raw.

plot_topomap_collage(props, aggfunc='mean', stages_to_plot='all', sleep_stages={'N1': 1, 'N2': 2, 'N3': 3, 'REM': 4, 'Wake': 0}, low_percentile=5, high_percentile=95, fig=None, save=False, topomap_args=None, cbar_args=None)

Plots topomap collage for multiple sleep stages and event properties.

Parameters:

• props (Iterable[str]) – Properties from the self.results.summary() to generate topomaps for.

• aggfunc (str) – Averaging function, “mean” or “median”. Defaults to “mean”.

• stages_to_plot (tuple) – stages_to_plot: Tuple of strings representing names from sleep_stages, e.g., (“REM”, “N1”). If set to “all” plots every stage provided in sleep_stages. Defaults to “all”.

• sleep_stages (dict) – Mapping between sleep stages names and their integer representations. Defaults to {“Wake”: 0, “N1”: 1, “N2”: 2, “N3”: 3, “REM”: 4}.

• low_percentile (float) – Set min color value by percentile of the property data. Defaults to 5.

• high_percentile (float) – Set max color value by percentile of the property data. Defaults to 95.

• fig (figure) – Instance of mpl:matplotlib.pyplot.figure. Defaults to None.

• save (bool) – Whether to save the figure. Defaults to False.

• topomap_args (dict) – Arguments passed to mne.viz.plot_topomap(). Defaults to None.

• cbar_args (dict) – Arguments passed to matplotlib.pyplot.colorbar(). Defaults to None.

compute_tfr(freqs, n_freqs, time_before, time_after, method='morlet', save=False, overwrite=False, **tfr_kwargs)

Transforms the events signal to time-frequency representation.

Parameters:

• freqs (Iterable[float]) – Lower and upper bounds of frequencies of interest in Hz, e.g., (10,20).

• n_freqs (int) – Frequency resolution in TFR.

• time_before (float) – Seconds before the event peak to get from the real data.

• time_after (float) – Seconds after the event peak to get from the real data

• method (str) – TFR transform method. Defaults to “morlet”.

• save (bool) – Whether to save the TFRs to file. Defaults to False.

• overwrite (bool) – Whether to overwrite existing TFR files.

• **tfr_kwargs – Arguments passed to mne.time_frequency.tfr_array_morlet() or mne.time_frequency.tfr_array_multitaper().

read_tfrs(dirpath=None)

Loads TFRs stored in hdf5 files.

Filenames should end with {type_of_event}_{sleep_stage}-tfr.h5

Parameters:

dirpath (str | None) – Path to the directory containing hdf5 files. Defaults to None.