yasa.irasa#

yasa.irasa(data, *, sf=None, ch_names=None, hypno=None, include=(2, 3), band=(1, 30), hset=(1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75, 1.8, 1.85, 1.9), return_fit=True, win_sec=4, welch_kwargs=None, verbose=False, kwargs_welch=None)[source]#

Separate the aperiodic (= fractal, or 1/f) and oscillatory component of the power spectra of EEG data using the IRASA method.

Added in version 0.1.7.

Changed in version 0.8.0: All the parameters except data are now keyword-only, e.g. irasa(data, sf=sf).

Parameters:
datanumpy.ndarray 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 :py:class:~`mne.io.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, IRASA is applied separately to the data of 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.

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

Added in version 0.8.0.

includetuple, list or int or str

Values in hypno that will be included in the mask. The default is (2, 3), meaning that IRASA is sequentially applied to N2 and N3 sleep. This has no effect when hypno is None. Stages that are too short for the Welch window and resampling factors are skipped with a warning.

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

Added in version 0.8.0.

bandtuple

Broad band frequency range. Default is 1 to 30 Hz.

hsettuple, list or numpy.ndarray

Resampling factors used in IRASA calculation. Default is to use a range of values from 1.1 to 1.9 with an increment of 0.05.

return_fitboolean

If True (default), fit an exponential function to the aperiodic PSD and return the fit parameters (intercept, slope) and \(R^2\) of the fit.

The aperiodic signal, \(L\), is modeled using an exponential function in semilog-power space (linear frequencies and log PSD) as:

\[L = a + \text{log}(F^b)\]

where \(a\) is the intercept, \(b\) is the slope, and \(F\) the vector of input frequencies.

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

welch_kwargsdict or None

Optional keywords arguments that are passed to the scipy.signal.welch function. Default is {"average": "median", "window": "hamming"}.

Added in version 0.8.0: Replaces kwargs_welch.

verbosebool or str

Verbose level. Default (False) will only print warning and error messages. The logging levels are ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘critical’. For most users the choice is between ‘info’ (or verbose=True) and warning (verbose=False).

Changed in version 0.8.0: The default is now False, as documented. Previously, the default was True, but the info messages were not shown because they were sent to the root logger.

kwargs_welchdict or None

Deprecated since version 0.8.0: Use welch_kwargs instead. This argument will be removed in v0.9.

Returns:
freqsnumpy.ndarray

Frequency vector.

psd_aperiodicnumpy.ndarray or dict

The fractal (= aperiodic) component of the PSD. If hypno is specified, this is a dictionary with one array per sleep stage, e.g. psd_aperiodic["N2"].

psd_oscillatorynumpy.ndarray or dict

The oscillatory (= periodic) component of the PSD. If hypno is specified, this is a dictionary with one array per sleep stage.

fit_paramspandas.DataFrame (optional)

Dataframe of fit parameters. Only if return_fit=True. If hypno is specified, the dataframe has one row per sleep stage and channel, and an additional Stage column.

Notes

The Irregular-Resampling Auto-Spectral Analysis (IRASA) method is described in Wen & Liu (2016). In a nutshell, the goal is to separate the fractal and oscillatory components in the power spectrum of EEG signals.

The steps are:

  1. Compute the original power spectral density (PSD) using Welch’s method.

  2. Resample the EEG data by multiple non-integer factors and their reciprocals (\(h\) and \(1/h\)).

  3. For every pair of resampled signals, calculate the PSD and take the geometric mean of both. In the resulting PSD, the power associated with the oscillatory component is redistributed away from its original (fundamental and harmonic) frequencies by a frequency offset that varies with the resampling factor, whereas the power solely attributed to the fractal component remains the same power-law statistical distribution independent of the resampling factor.

  4. It follows that taking the median of the PSD of the variously resampled signals can extract the power spectrum of the fractal component, and the difference between the original power spectrum and the extracted fractal spectrum offers an approximate estimate of the power spectrum of the oscillatory component.

Note that an estimate of the original PSD can be calculated by simply adding psd = psd_aperiodic + psd_oscillatory.

If hypno is specified, the samples of each sleep stage are concatenated before applying IRASA, in the same way as in yasa.bandpower.

For an example of how to use this function, please refer to raphaelvallat/yasa

For an article discussing the challenges of using IRASA (or fooof) see [5].

References

[1] Wen, H., & Liu, Z. (2016). Separating Fractal and Oscillatory

Components in the Power Spectrum of Neurophysiological Signal. Brain Topography, 29(1), 13–26. https://doi.org/10.1007/s10548-015-0448-0

[2] fieldtrip/fieldtrip

[3] fooof-tools/fooof

[4] https://www.biorxiv.org/content/10.1101/299859v1

[5] https://doi.org/10.1101/2021.10.15.464483

Examples

IRASA applied separately to each sleep stage:

>>> import yasa
>>> hyp = yasa.Hypnogram.from_integers(hypno_30s, freq="30s")
>>> freqs, psd_ap, psd_osc, fit = yasa.irasa(
...     raw, hypno=hyp, include=["N2", "N3", "REM"]
... )
>>> psd_ap["N3"]  # Aperiodic PSD in N3 sleep, shape (n_chan, n_freqs)
On this page