BaseEventPipe#

class sleepeegpy.base.BaseEventPipe(*, prec_pipe=None, path_to_eeg=_Nothing.NOTHING, output_dir=_Nothing.NOTHING, path_to_hypno=None, hypno_freq=_Nothing.NOTHING, hypno=_Nothing.NOTHING)[source]#

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()[source]#: Each event class should contain the detection method

plot_average(save=False, **kwargs)[source]#

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[source]#

Calculates percent of data segments annotated as BAD.

Returns:: percent of bad data spans in raw data
Return type:: float

interpolate_bads(**interp_kwargs)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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

Returns:: sampling frequency
Return type:: float

sleep_stats(save=False)[source]#

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)[source]#

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)[source]#

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)[source]#

Loads TFRs stored in hdf5 files.

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

Parameters:: dirpath (Optional[str]) – Path to the directory containing hdf5 files. Defaults to None.