RapidEyeMovementsPipe#

class sleepeegpy.pipeline.RapidEyeMovementsPipe(*, 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: BaseEventPipe

Rapid eye movements detection.

Methods:

compute_tfr

Transforms the events signal to time-frequency representation.

detect

A wrapper around yasa.rem_detect() with option to save.

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.

detect(loc_chname='E46', roc_chname='E238', reference='average', include=4, freq_rem=(0.5, 5), duration=(0.3, 1.2), amplitude=(50, 325), remove_outliers=False, save=False)[source]#

A wrapper around yasa.rem_detect() with option to save.

plot_topomap()[source]#

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

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

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

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

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

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

  • save – Whether to save the figure. Defaults to False.

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

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

plot_topomap_collage()[source]#

Plots topomap collage for multiple sleep stages and event properties.

Parameters:
  • props – Properties from the self.results.summary() to generate topomaps for.

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

  • stages_to_plot – 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 – Mapping between sleep stages names and their integer representations. Defaults to {“Wake”: 0, “N1”: 1, “N2”: 2, “N3”: 3, “REM”: 4}.

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

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

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

  • save – Whether to save the figure. Defaults to False.

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

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

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

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

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_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().

plot_sensors(legend=None, legend_args=None, **kwargs)[source]#

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

Parameters:
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.

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.

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:
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.

tfrs: dict#

Instances of mne.time_frequency.AverageTFR per sleep stage.

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.

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: np.ndarray#

Hypnogram with sampling frequency hypno_freq with int representing sleep stage.

hypno_up: np.array#

Hypnogram upsampled to the sampling frequency of the raw data.

prec_pipe: Type[BasePipeType]#

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: mne.io.Raw#

An instanse of mne.io.Raw.