GrandSpectralPipe

Tip

πŸ’‘ Usage Examples - See the notebook for usage examples and code snippets: Grand spectral analyses

class sleepeegpy.pipeline.GrandSpectralPipe(*, pipes, output_dir)[source]

Bases: SpectrumPlots

The pipeline element combining results from multiple subjects.

Contains methods for computing and plotting combined PSD and topomaps, per sleep stage.

Methods:

compute_psd

For each sleep stage creates a mne.time_frequency.SpectrumArray object.

parametrize

Spectral parametrization by FOOOF - fitting oscillations & one over f.

plot_psds

Plot PSD per sleep stage.

plot_topomap

Plots topomap for a sleep stage and a frequency band.

plot_topomap_collage

Plots topomap collage for multiple sleep stages and bands.

save_psds

Saves SleepSpectrum objects to h5 files.

Attributes:

pipes

Stores SpectralPipes for multiple subjects.

output_dir

Path to the directory where the output will be saved.

mne_raw

Representative raw object to infer montage

fooofs

Instances of fooof.FOOOFGroup per sleep stage.

psds

Instances of SleepSpectrum per sleep stage.
pipes: Iterable[SpectralPipe][source]

Stores SpectralPipes for multiple subjects.

output_dir: Path[source]

Path to the directory where the output will be saved.

mne_raw: Raw[source]

Representative raw object to infer montage

plot_psds(picks, psd_range=(-40, 60), freq_range=(0, 60), dB=True, xscale='linear', axis=None, plot_sensors=False, save=False, legend_args=None, **plot_kwargs)[source]

Plot PSD per sleep stage.

Parameters:

  • picks (Iterable[str] | str) – Channels to plot PSDs for. Refer to mne.io.Raw.pick().

  • psd_range (tuple) – Range of y axis on PSD plot. Defaults to (-40, 60).

  • freq_range (tuple) – Range of x axis on PSD plot. Defaults to (0, 40).

  • dB – Whether transform PSD to dB. Defaults to True.

  • xscale (str) – Scale of the X axis, check available values at matplotlib.axes.Axes.set_xscale(). Defaults to β€œlinear”.

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

  • plot_sensors (bool) – Whether to plot sensor map showing which channels were used for computing PSD. Defaults to False.

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

  • **plot_kwargs – Arguments passed to the matplotlib.pyplot.plot(). Have no effect if axis is provided.Defaults to None.

plot_topomap(stage='REM', band={'Delta': (0, 4)}, dB=False, axis=None, save=False, topomap_args=None, cbar_args=None)[source]

Plots topomap for a sleep stage and a frequency band.

Parameters:

  • stage (str) – One of the sleep_stages keys. Defaults to β€œREM”.

  • band (dict) – Name-value pair - with name=arbitrary name and value=(l_freq, h_freq). Defaults to {β€œDelta”: (0, 4)}.

  • dB (bool) – Whether transform PSD to dB. Defaults to False.

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

plot_topomap_collage(stages_to_plot='all', bands={'Alpha': (8, 12.49), 'Beta': (12.5, 29.99), 'Delta': (0, 3.99), 'Gamma': (30, 60), 'Sigma': (12.5, 15), 'Theta': (4, 7.99)}, dB=False, 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 bands.

Parameters:

  • stages_to_plot (tuple) – 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”.

  • bands (dict) – Dict of name-value pairs - with name=arbitrary name and value=(l_freq, h_freq). Defaults to { β€œDelta”: (0, 3.99), β€œTheta”: (4, 7.99), β€œAlpha”: (8, 12.49), β€œSigma”: (12.5, 15), β€œBeta”: (12.5, 29.99), β€œGamma”: (30, 60), }.

  • dB (bool) – Whether transform PSD to dB. Defaults to False.

  • 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 (float) – Set min color value by percentile of the band data. Defaults to 5.

  • high_percentile (float) – Set max color value by percentile of the band 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.

save_psds(overwrite)[source]

Saves SleepSpectrum objects to h5 files.

Parameters:

overwrite – Whether to overwrite existing spectrum files.

psds: dict

Instances of SleepSpectrum per sleep stage.

fooofs: dict[source]

Instances of fooof.FOOOFGroup per sleep stage.

compute_psd(sleep_stages={'N1': 1, 'N2': 2, 'N3': 3, 'REM': 4, 'Wake': 0}, reference=None, fmin=0, fmax=60, average='mean', picks='eeg', reject_by_annotation=True, save=False, overwrite=False, **psd_kwargs)[source]

For each sleep stage creates a mne.time_frequency.SpectrumArray object.

Parameters:

  • sleep_stages (dict) – Sleep stages mapping in hypnogram. Defaults to {β€œWake”: 0, β€œN1”: 1, β€œN2”: 2, β€œN3”: 3, β€œREM”: 4}.

  • reference (Iterable[str] | str | None) – Which eeg reference to compute PSD with. If None, the reference isn’t changed. Defaults to None.

  • fmin (float) – Lower frequency bound. Defaults to 0.

  • fmax (float) – Upper frequency bound. Defaults to 60.

  • picks (str | Iterable[str]) – Channels to compute spectra for. Refer to mne.io.Raw.pick(). Defaults to β€œeeg”.

  • reject_by_annotation (bool) – Whether to not use the annotations for the spectra computation. Defaults to True.

  • save (bool) – Whether to save the spectra in .h5 files. Defaults to False.

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

  • **psd_kwargs – Additional arguments passed to mne.time_frequency.psd_array_welch()

parametrize(picks, freq_range, average_ch=False, **kwargs)[source]

Spectral parametrization by FOOOF - fitting oscillations & one over f.

Parameters:

  • picks – Channels to use in parametrization.

  • freq_range – Range of frequencies to parametrize. If None, set to bandpass filter boundaries. Defaults to None.

  • average_ch – Whether to average psds over channels. If False will be averaged over subjects. Defaults to False.

  • **kwargs – Arguments passed to fooof.FOOOFGroup.