features.get_psd_decay_features

features.get_psd_decay_features(
    data,
    fs,
    fscale,
    period,
    bands,
    nperseg=2048,
    PSD_range=BANDS['lfp'],
)

Extract power spectral density decay features from electrophysiological data.

This function computes spectral parameterization features that characterize the aperiodic (1/f) component of the power spectral density (PSD) using the specparam library. It fits a model to separate periodic peaks from the aperiodic background in the frequency domain, providing insights into the underlying neural dynamics.

Additionally, it computes residual power features by removing the fitted aperiodic component from the observed PSD, highlighting periodic components across different frequency bands.

The aperiodic component of neural signals is thought to reflect the balance of excitation and inhibition in neural circuits, making these features particularly useful for characterizing brain states and pathological conditions.

Parameters

Name	Type	Description	Default
data	np.ndarray	Input electrophysiological data with shape (n_channels, n_samples). Each row represents a different recording channel.	required
fs	float	Sampling frequency of the data in Hz.	required
fscale	np.ndarray	Frequency scale array corresponding to the period data.	required
period	np.ndarray	2D array of power spectral density values with shape (n_channels, n_frequencies). Each row represents the PSD for a different recording channel.	required
bands	dict	Dictionary mapping frequency band names to [min_freq, max_freq] ranges in Hz. Used for computing residual power in specific frequency bands.	required
nperseg	int	Length of each segment for Welch’s method PSD estimation, by default 2048. Larger values provide better frequency resolution but less temporal averaging.	2048
PSD_range	list of float	Frequency range [min_freq, max_freq] in Hz for spectral parameterization, by default BANDS[“lfp”] which is [0, 90] Hz.	BANDS['lfp']

Returns

Name	Type	Description
	pd.DataFrame	One row per channel. Aperiodic-component columns: aperiodic_offset (log10 power at 1 Hz), aperiodic_exponent (1/f slope in log-log space), decay_fit_error (RMS fit error), decay_fit_r_squared (goodness of fit) and decay_n_peaks (number of periodic peaks). Residual-power columns (periodic power per band after aperiodic removal): psd_residual_delta, psd_residual_theta, psd_residual_alpha, psd_residual_beta, psd_residual_gamma and psd_residual_lfp.

Notes

The function uses the specparam library (formerly FOOOF) to separate periodic and aperiodic components of the PSD. The aperiodic component follows a 1/f^β relationship where β is the aperiodic exponent.

Channels with R-squared < 0.9 are flagged as having poor fits, which may indicate artifacts or unusual spectral properties.

The spectral model is configured with: - Peak width limits: [10, 15] Hz - Maximum peaks: 4 - Minimum peak height: 0.1

The residual curve is computed as: residual = 10^(log10(observed_PSD) - log10(fitted_aperiodic_component))

Examples

>>> import numpy as np
>>> # Generate sample data and frequency arrays
>>> data = np.random.randn(10, 10000)
>>> fs = 1000.0  # 1 kHz sampling rate
>>> fscale = np.linspace(0, 90, 100)
>>> period = np.random.rand(10, 100)  # Mock PSD data
>>> bands = {'delta': [0, 4], 'theta': [4, 10], 'alpha': [8, 12]}
>>> features = get_psd_decay_features(data, fs, fscale, period, bands)
>>> print(features.columns)
Index(['aperiodic_offset', 'aperiodic_exponent', 'decay_fit_error',
       'decay_fit_r_squared', 'decay_n_peaks', 'psd_residual_delta',
       'psd_residual_theta', 'psd_residual_alpha', ...], dtype='object')

References

Donoghue, T., Haller, M., Peterson, E. J., Varma, P., Sebastian, P., Gao, R., et al. (2020). Parameterizing neural power spectra into periodic and aperiodic components. Nature Neuroscience, 23(12), 1655-1665.