glhmm.auxiliary

Auxiliary functions - Gaussian Linear Hidden Markov Model @author: Diego Vidaurre 2022

glhmm.auxiliary.Gamma_entropy(Gamma, Xi, indices)

Computes the entropy of a Gamma distribution and a sequence of transition probabilities Xi.

Parameters:

GammaArray-like of shape (n_samples, n_states)

The posterior probabilities of a hidden variable.

XiArray-like of shape (n_samples - n_sessions, n_states, n_states)

The joint probability of past and future states conditioned on data.

indicesArray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

Returns:

float: The entropy of the Gamma distribution and the sequence of transition probabilities.

glhmm.auxiliary.Gamma_indices_to_Xi_indices(indices)

Converts indices from Gamma array to Xi array format.

Note Xi has 1 sample less than Gamma per trial/session (i.e., n_samples - n_sessions).

Parameters:

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

Returns:

indices_Xiarray-like of shape (n_sessions, 2)

The converted indices in Xi array format.

glhmm.auxiliary.approximate_Xi(Gamma, indices)

Approximates Xi array based on Gamma and indices.

Parameters:

Gammaarray-like of shape (n_samples, n_states)

The state probability time series.

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

Returns:

Xiarray-like of shape (n_samples - n_sessions, n_states, n_states)

The joint probabilities of past and future states conditioned on data.

glhmm.auxiliary.compute_alpha_beta_parallel(L, Pi, P, indices_individual, gpu_acceleration)

Computes alpha and beta values and scaling factors.

Parameters:

Larray-like of shape (n_samples, n_timeseries, n_states)

The L matrix.

Piarray-like with shape (n_states,)

The initial state probabilities.

Parray-like of shape (n_states, n_states)

The transition probabilities across states.

indices_individualarray-like of shape (n_timeseries,2)

The first and last index of the subject-specific time series

gpu_accelerationint

GPU acceleration setting.

Returns:

aGPU array-like of shape (n_samples, n_states)

The alpha values.

bGPU array-like of shape (n_samples, n_states)

The beta values.

scGPU array-like of shape (n_samples,)

The scaling factors.

glhmm.auxiliary.compute_alpha_beta_serial(L, Pi, P)

Computes alpha and beta values and scaling factors.

Parameters:

Larray-like of shape (n_samples, n_states)

The L matrix.

Piarray-like with shape (n_states,)

The initial state probabilities.

Parray-like of shape (n_states, n_states)

The transition probabilities across states.

Returns:

aarray-like of shape (n_samples, n_states)

The alpha values.

barray-like of shape (n_samples, n_states)

The beta values.

scarray-like of shape (n_samples,)

The scaling factors.

glhmm.auxiliary.compute_qstar_parallel(L, Pi, P, indices_individual)

Compute the most probable state sequence.

Parameters:

Larray-like of shape (n_samples, n_states)

The L matrix.

Piarray-like with shape (n_states,)

The initial state probabilities.

Parray-like of shape (n_states, n_states)

The transition probabilities across states.

Returns:

qstararray-like of shape (n_samples, n_states)

The most probable state sequence.

glhmm.auxiliary.compute_qstar_serial(L, Pi, P)

Compute the most probable state sequence.

Parameters:

Larray-like of shape (n_samples, n_states)

The L matrix.

Piarray-like with shape (n_states,)

The initial state probabilities.

Parray-like of shape (n_states, n_states)

The transition probabilities across states.

Returns:

qstararray-like of shape (n_samples, n_states)

The most probable state sequence.

glhmm.auxiliary.dirichlet_kl(alpha_q, alpha_p)

Computes the Kullback-Leibler divergence between two Dirichlet distributions with parameters alpha_q and alpha_p.

Parameters:

alpha_qArray of shape (n_states,)

The concentration parameters of the first Dirichlet distribution.

alpha_pArray of shape (n_states,)

The concentration parameters of the second Dirichlet distribution.

Returns:

float: The Kullback-Leibler divergence between the two Dirichlet distributions.

glhmm.auxiliary.gamma_kl(shape_q, rate_q, shape_p, rate_p)

Computes the Kullback-Leibler divergence between two Gamma distributions with shape and rate parameters.

The Kullback-Leibler divergence is a measure of how different two probability distributions are.

This implementation follows the formula presented here (https://statproofbook.github.io/P/gam-kl) from the book “KL-Divergences of Normal, Gamma, Dirichlet and Wishart densities” by Penny, William D. in 2001.

Parameters:

shape_qfloat or numpy.ndarray

The shape parameter of the first Gamma distribution.

rate_qfloat or numpy.ndarray

The rate parameter of the first Gamma distribution.

shape_pfloat or numpy.ndarray

The shape parameter of the second Gamma distribution.

rate_pfloat or numpy.ndarray

The rate parameter of the second Gamma distribution.

Returns:

Dfloat or numpy.ndarray

The Kullback-Leibler divergence between the two Gamma distributions.

glhmm.auxiliary.gauss1d_kl(mu_q, sigma_q, mu_p, sigma_p)

Computes the KL divergence between two univariate Gaussian distributions.

Parameters:

mu_qfloat of shape (n_parcels,)

The mean of the first Gaussian distribution.

sigma_qfloat of shape (n_parcels, n_parcels)

The variance of the first Gaussian distribution.

mu_pfloat of shape (n_parcels,)

The mean of the second Gaussian distribution.

sigma_pfloat of shape (n_parcels, n_parcels)

The variance of the second Gaussian distribution.

Returns:

Dfloat

The KL divergence between the two Gaussian distributions.

glhmm.auxiliary.gauss_kl(mu_q, sigma_q, mu_p, sigma_p)

Computes the KL divergence between two multivariate Gaussian distributions.

Parameters:

mu_qfloat of shape (n_parcels,)

The mean of the first Gaussian distribution.

sigma_qfloat of shape (n_parcels, n_parcels)

The variance of the first Gaussian distribution.

mu_pfloat of shape (n_parcels,)

The mean of the second Gaussian distribution.

sigma_pfloat of shape (n_parcels, n_parcels)

The variance of the second Gaussian distribution.

Returns:

Dfloat

The KL divergence between the two Gaussian distributions.

glhmm.auxiliary.get_T(idx_data)

Returns the timepoints spent for each trial/session based on the given indices. We want to get the variable “T” when we are using the function padGamma

Parameters:

idx_data (numpy.ndarray): The indices that mark the timepoints for when each trial/session starts and ends. It should be a 2D array where each row represents the start and end index for a trial. Example: idx_data = np.array([[0, 150], [150, 300], [300, 500]])

Returns:

T (numpy.ndarray): An array containing the timepoints spent for each trial/session. For example, given idx_data = np.array([[0, 150], [150, 300], [300, 500]]), the function would return T = np.array([150, 150, 200]).

glhmm.auxiliary.jls_extract_def()

glhmm.auxiliary.make_indices_from_T(T)

Creates indices array from trials/sessions lengths.

Parameters:

Tarray-like of shape (n_sessions,)

Contains the lengths of each trial/session.

Returns:

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

glhmm.auxiliary.padGamma(Gamma, T, options)

Adjusts the state time courses to have the same size as the data time series.

Parameters:

Gamma (numpy.ndarray): The state time courses. T (numpy.ndarray): Timepoints spent for each trial/session. options (dict): Dictionary containing various options. - ‘embeddedlags’ (list): Array of lagging times if ‘embeddedlags’ is specified. - ‘order’ (int): Integer value if ‘order’ is specified.

Returns:

Gamma (numpy.ndarray): Adjusted state time courses.

glhmm.auxiliary.roll_by_vector(arr, shifts, axis=1, gpu_enabled=False)

Apply an independent roll for each dimensions of a single axis.

Parameters:

• arr (np.ndarray) – Array of any shape.

• shifts (np.ndarray) – How many shifting to use for each dimension. Shape: (arr.shape[axis],).

• axis (int) – Axis along which elements are shifted.

• gpu_enabled (bool) – Whether input arrays are loaded in the GPU or not.

glhmm.auxiliary.slice_matrix(M, indices)

Slices rows of input matrix M based on indices array along axis 0.

Parameters:

Marray-like of shape (n_samples, n_parcels)

The input matrix.

indicesarray-like of shape (n_sessions, 2)

The indices that define the sections (i.e., trials/sessions) of the data to be processed.

Returns:

M_slicedarray-like of shape (n_total_samples, n_parcels)

The sliced matrix.

glhmm.auxiliary.wishart_kl(shape_q, C_q, shape_p, C_p)

Computes the Kullback-Leibler (KL) divergence between two Wishart distributions.

Parameters:

shape_qfloat

Shape parameter of the first Wishart distribution.

C_qndarray of shape (n_parcels, n_parcels)

Scale parameter of the first Wishart distribution.

shape_pfloat

Shape parameter of the second Wishart distribution.

C_pndarray of shape (n_parcels, n_parcels)

Scale parameter of the second Wishart distribution.

Returns:

Dfloat

KL divergence from the first to the second Wishart distribution.