glhmm.spectral

Spectral analysis from Gaussian Linear Hidden Markov Model @author: Laura Masaracchia & Nick Y. Larsen, 2025

glhmm.spectral.get_frequency_args_range(frequencies, frequency_range)

Gets the index range corresponding to a frequency interval.

Parameters:

frequencies (numpy.ndarray):

1D array of frequency values (Hz).

frequency_range (tuple):

Two-element tuple (min_freq, max_freq) defining the desired frequency range.

Returns:

args_range (list):

List containing the start and end indices corresponding to the frequency range.

glhmm.spectral.get_nnmf_component_intervals(freqs, nnmf_components)

Identify the frequency intervals between adjacent NNMF spectral components based on their first point of intersection.

Parameters:

freqsnumpy.ndarray

1D array of shape (n_freqs,) representing frequency values (e.g., in Hz).

nnmf_componentsnumpy.ndarray

2D array of shape (n_components, n_freqs) representing the spectral profiles of each NNMF component.

Returns:

intervalslist of [float, float]

List of frequency intervals defined by the first intersection between each adjacent pair of components. The first interval starts at the lowest frequency and the last ends at the highest frequency.

glhmm.spectral.getfgrid(Fs, nfft, fpass)

Generate frequency grid for FFT computation.

glhmm.spectral.mean_coherence_from_spectra(frequencies, coh, components=None, frequency_range=None)

Computes mean coherence per channel pair from coherence spectra, either averaged over a frequency range or projected onto spectral components.

Parameters:

• (np.ndarray) (coh) – 1D array of frequency values (Hz). Required if using frequency_range.

• (np.ndarray) –

  Coherence array. Shape must be one of:

  • (n_freq, n_channels, n_channels)

  • (n_freq, n_channels, n_channels, n_modes)

  • (n_sessions, n_freq, n_channels, n_channels, n_modes)

• (np.ndarray (components) – Spectral components to project onto. Shape: (n_components, n_freq).

• optional) – Spectral components to project onto. Shape: (n_components, n_freq).

• frequency_range (tuple, optional) – Frequency range (min_freq, max_freq) to average over.

Returns:

• (n_components, n_modes, n_channels, n_channels) if components provided

• (n_modes, n_channels, n_channels) or (n_channels, n_channels) otherwise

• Includes (n_sessions, …) if multiple sessions present

Return type:

Mean coherence (np.ndarray). Shape

glhmm.spectral.multitaper_coherence(cpsd)

Compute the coherence across frequency between channels

Parameters:

cpsdarray-like with shape (n_channels, n_channels, n_freq)

input is the cross power spectral density

Returns:

coherencearray-like, with shape (n_channels, n_channels, n_freq)

coherence values across channels at each frequency bin

glhmm.spectral.multitaper_spectra(data, tapers, window_length, nfft, findx)

Perform multitaper spectral analysis on input data.

Parameters:

dataarray-like of shape (n_samples, n_channels)

(subject- or session-level) timeseries data

tapersarray-like of shape (n_tapers, window_length)

the multitapers

window_lengthint, default=

the length of each multitaper window

nfftint, default=

number of FFT points to use

findxarray-like or list of length n_freq

indices of frequency points to keep (frequency range for power spectrum estimation)

Returns:

PWarray-like of shape (n_tapers, n_channels, n_freq)

power spectrum for each taper and each channel within the indicated frequency range

CPW: array-like of shape (n_tapers, n_channels, n_channels, n_freq)

cross-channels power spectrum, for each taper and each channel within the indicated frequency range

Raises:

Error : if data and tapers dimensions are not compatible

glhmm.spectral.multitaper_spectral_analysis(data, indices, Fs, Gamma=None, options=None)

Compute spectral measures using the multitaper non parametric method, with options specified in “options”. If the state time courses of a fitted hidden Markov models (Gamma) are given as input, the function computes the spectral measures for each state. These spectral measures are power, coherence, cross-power spectral density

Parameters:

dataarray-like of shape (total_samples, n_channels)

the data, all subjects or sessions concatenated

indicesarray-like of shape (n_subjects or n_sessions, 2)

the indices to start and end of each subject/session

Fs : int, sampling frequency of the data Gamma : array-like of shape (total_samples, n_states)

State time courses. If specified, the spectral measures are computed per state If HMM-MAR or HMM-TDE are used, and Gamma is used unpadded, the order or embedded lags have to be specified in the options (see below)

optionsdict

Possible keys of the options dictionary - ‘standardize’ : bool, whether to standardize the data - ‘fpass’ : tuple or list of length 2, the frequency range for the power spectrum estimation.

If not specified, the whole range from 0 to Fs/2 is used

• ‘win’int, window length of each multitaper.

  If not specified, default as Fs * 2 is used

• ‘tapers_res’int, half time bandwidth, resolution of the tapers

  If not specified, default as 3 is uded

• ‘n_tapers’int, number of tapers to use.

  If not specified, default as 5 is used

If Gamma is given as an input, you might need to specify - ‘order’ or ‘embeddedlags’ : compulsory if the HMM was trained using those (respectively, MAR or TDE)

Returns:

fitdict with spectral estimates per state

The dict would contain a dict for each state, with measures: - ‘f’ : frequency bins, with shape (n_freq) - ‘p’ : power spectrum for each channel, with shape (n_subjects or n_sessions, n_freq, n_channels, n_states) - ‘psdc’ : cross-channel power spectral density, with shape (n_subjects or n_sessions, n_freq, n_channels, n_channels, n_states) - ‘coh’ : channels coherence, with shape (n_subjects or n_sessions, n_freq, n_channels, n_channels, n_states)

glhmm.spectral.nnmf_decompose(coh, indices, n_components, max_iter=1000)

Perform a non negative matrix factorization spectral decomposition of the data

Parameters:

coh : array-like of shape (n_subjects, n_freq, n_channels, n_channels, n_states) or (n_subjects, n_freq, n_channels, n_channels), or (n_freq, n_channels, n_channels, n_states)

coherence just as in the fit dictionary ‘coh’ outputted by the multitaper spectral estimation

indicesarray-like of shape (n_subjects or n_sessions, 2)

the indices of timepoints indicating start and end of each subject/session data

n_componentsint

number of components into which the signal will be decomposed

max_iterint, optional. default=1000

maximum number of iteration to allow the method to do.

Returns:

nnmf_frequency_profiles (numpy.ndarray):

frequency components derived from NNMF with shape (n_subjects, n_components, n_freq)

glhmm.spectral.power_from_spectra(frequencies, power_spectra, components=None, frequency_range=None, method='mean')

Compute region-wise power from power spectra across frequency bands or spectral components.

Parameters:

• frequencies (np.ndarray) – 1D array of frequency values in Hz. Shape: (n_freq,)

• power_spectra (np.ndarray) –

  Power spectral or cross-spectral density array. Shape must be one of the following:

  • (n_freq, n_channels)

  • (n_freq, n_channels, n_states)

  • (n_sessions, n_freq, n_channels, n_states)

  • (n_sessions, n_freq, n_channels, n_channels, n_states)

• components (np.ndarray, optional) – Spectral components to project PSDs onto. Shape: (n_components, n_freq). Cannot be used with frequency_range.

• frequency_range (tuple of float, optional) – Frequency range as (min_freq, max_freq) in Hz to select power within. Cannot be used with components.

• method (str) – One of: ‘sum’, ‘mean’, or ‘integral’.

Returns:

Power values with shape:

• (n_components, n_channels, n_states) if components are provided

• (n_states, n_channels) otherwise

If sessions are present, shape will be (n_sessions, …)

Return type:

np.ndarray