yasa.bandpower#

yasa.bandpower(data, sf=None, ch_names=None, hypno=None, include=(2, 3), win_sec=4, relative=True, bandpass=False, bands=[(0.5, 4, 'Delta'), (4, 8, 'Theta'), (8, 12, 'Alpha'), (12, 16, 'Sigma'), (16, 30, 'Beta'), (30, 40, 'Gamma')], kwargs_welch={'average': 'median', 'window': 'hamming'})[source]#

Calculate the Welch bandpower for each channel and, if specified, for each sleep stage.

Added in version 0.1.6.

Parameters:
dataarray_like or mne.io.BaseRaw

1D or 2D EEG data. If data is array_like, unit must be uV. If data is a BaseRaw instance, data, sf, and ch_names will be automatically extracted, and data will be automatically converted from Volts (MNE) to micro-Volts (YASA).

sffloat

The sampling frequency of data AND the hypnogram if data is array_like. Should be omitted if data is a BaseRaw.

ch_nameslist

List of channel names, e.g. [‘Cz’, ‘F3’, ‘F4’, …], if data is array_like. If None, channels will be labelled [‘CHAN000’, ‘CHAN001’, …]. Should be omitted if data is a BaseRaw.

hypnoarray_like or yasa.Hypnogram

Sleep stage (hypnogram). If the hypnogram is loaded, the bandpower will be extracted for each sleep stage defined in include.

Can be an upsampled integer array (same number of samples as data) or a yasa.Hypnogram instance (automatically upsampled). To manually upsample an integer array, use yasa.Hypnogram.upsample_to_data or yasa.hypno_upsample_to_data.

Note

When passing an integer array, hypnogram values follow this mapping:

  • -2 = Unscored

  • -1 = Artefact / Movement

  • 0 = Wake

  • 1 = N1 sleep

  • 2 = N2 sleep

  • 3 = N3 sleep

  • 4 = REM sleep

includetuple, list or int or str

Values in hypno that will be included in the mask. The default is (2, 3), meaning that the bandpower are sequentially calculated for N2 and N3 sleep. This has no effect when hypno is None.

When hypno is a yasa.Hypnogram, string labels can be used instead of integers (e.g. ["N2", "N3"]).

win_secint or float

The length of the sliding window, in seconds, used for the Welch PSD calculation. Ideally, this should be at least two times the inverse of the lower frequency of interest (e.g. for a lower frequency of interest of 0.5 Hz, the window length should be at least 2 * 1 / 0.5 = 4 seconds).

relativeboolean

If True, bandpower is divided by the total power between the min and max frequencies defined in band.

bandpassboolean

If True, apply a standard FIR bandpass filter using the minimum and maximum frequencies in bands. Fore more details, refer to mne.filter.filter_data.

bandslist of tuples

List of frequency bands of interests. Each tuple must contain the lower and upper frequencies, as well as the band name (e.g. (0.5, 4, ‘Delta’)).

kwargs_welchdict

Optional keywords arguments that are passed to the scipy.signal.welch function.

Returns:
bandpowerspandas.DataFrame

Bandpower dataframe, in which each row is a channel and each column a spectral band.

Examples

  1. Bandpower per sleep stage using an upsampled integer hypnogram (legacy):

>>> import yasa
>>> bp = yasa.bandpower(raw, hypno=hypno_up, include=(2, 3, 4))

  1. Pass a Hypnogram directly — upsampling is handled automatically. String stage labels can be used for include:

>>> hyp = yasa.Hypnogram.from_integers(hypno_30s, freq="30s")
>>> bp = yasa.bandpower(raw, hypno=hyp, include=["N2", "N3", "REM"])

For a full walkthrough, please refer to: raphaelvallat/yasa

On this page