glhmm.utils

Some public useful functions - Gaussian Linear Hidden Markov Model @author: Diego Vidaurre 2023

glhmm.utils.get_FO(Gamma, indices, summation=False)

Calculates the fractional occupancy of each state.

Parameters:

Gammaarray-like, shape (n_samples, n_states)

The state probability time series.

indicesarray-like, shape (n_sessions, 2)

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

summationbool, optional, default=False

If True, the sum of each row is not normalized, otherwise it is.

Returns:

FOarray-like, shape (n_sessions, n_states)

The fractional occupancy of each state per session.

glhmm.utils.get_FO_entropy(Gamma, indices)

Calculates the entropy of each session, if we understand fractional occupancies as probabilities.

Parameters:

Gammaarray-like of shape (n_samples, n_states)

The Gamma represents the state probability timeseries.

indicesarray-like of shape (n_sessions, 2)

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

Returns:

entropyarray-like of shape (n_sessions,)

The entropy of each session.

glhmm.utils.get_gamma_similarity(gamma1, gamma2)

Computes a measure of similarity between two sets of state time courses.

These can have different numbers of states, but they must have the same number of time points.

Parameters:

gamma1numpy.ndarray

First set of state time courses with shape (T, K).

gamma2numpy.ndarray

Second set of state time courses with shape (T, K2), where K2 may be different from K.

Returns:

Sfloat

Similarity, measured as the sum of joint probabilities under the optimal state alignment.

assignumpy.ndarray

Optimal state alignment for gamma2 (uses Munkres’ algorithm).

gamma2numpy.ndarray

The second set of state time courses reordered to match gamma1.

glhmm.utils.get_life_times(vpath, indices, threshold=0)

Calculates the average, median and maximum life times for each state.

Parameters:

vpatharray-like of shape (n_samples,)

The viterbi path represents the most likely state sequence.

indicesarray-like of shape (n_sessions, 2)

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

thresholdint, optional, default=0

A threshold value used to exclude visits with a duration below this value.

Returns:

meanLFarray-like of shape (n_sessions, n_states)

The average visit duration for each state in each trial/session.

medianLFarray-like of shape (n_sessions, n_states)

The median visit duration for each state in each trial/session.

maxLFarray-like of shape (n_sessions, n_states)

The maximum visit duration for each state in each trial/session.

Notes:

A visit to a state is defined as a contiguous sequence of time points in which the state is active. The duration of a visit is the number of time points in the sequence. This function uses the get_visits function to compute the visits and exclude those below the threshold.

glhmm.utils.get_maxFO(Gamma, indices)

Calculates the maximum fractional occupancy per session.

The first argument can also be a viterbi path (vpath).

Parameters:

Gammaarray-like of shape (n_samples, n_states); or a vpath, array of shape (n_samples,)

The Gamma represents the state probability timeseries and the vpath represents the most likely state sequence.

indicesarray-like of shape (n_sessions, 2)

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

Returns:

maxFO: array-like of shape (n_sessions,)

The maximum fractional occupancy across states for each trial/session

Notes:

The maxFO is useful to assess the amount of state mixing. For more information, see [^1].

References:

[^1]: Ahrends, R., et al. (2022). Data and model considerations for estimating time-varying functional connectivity in fMRI. NeuroImage 252, 119026.

https://pubmed.ncbi.nlm.nih.gov/35217207/)

glhmm.utils.get_state_evoked_response(Gamma, indices)

Calculates the state evoked response

The first argument can also be a viterbi path (vpath).

Parameters:

Gammaarray-like of shape (n_samples, n_states), or a vpath array of shape (n_samples,)

The Gamma represents the state probability timeseries and the vpath represents the most likely state sequence.

indicesarray-like of shape (n_sessions, 2)

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

Returns:

serarray-like of shape (n_samples, n_states)

The state evoked response matrix.

Raises:

Exception

If the input data violates any of the following conditions: - There is only one trial/session - Not all trials/sessions have the same length.

glhmm.utils.get_state_evoked_response_entropy(Gamma, indices)

Calculates the entropy of each time point, if we understand state evoked responses as probabilities.

Parameters:

Gamma: array-like of shape (n_samples, n_states)

The Gamma represents the state probability timeseries.

indicesarray-like of shape (n_sessions, 2)

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

Returns:

entropy: array-like of shape (n_samples,)

The entropy of each time point.

glhmm.utils.get_state_onsets(vpath, indices, threshold=0)

Calculates the state onsets, i.e., the time points when each state activates.

Parameters:

vpatharray-like of shape (n_samples, n_states)

The viterbi path represents the most likely state sequence.

indicesarray-like of shape (n_sessions, 2)

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

thresholdint, optional, default=0

A threshold value used to exclude visits with a duration below this value.

Returns:

onsetslist of lists of ints

A list of the time points when each state activates for each trial/session.

Notes:

A visit to a state is defined as a contiguous sequence of time points in which the state is active. This function uses the get_visits function to compute the visits and exclude those below the threshold.

glhmm.utils.get_switching_rate(Gamma, indices)

Calculates the switching rate.

The first argument can also be a viterbi path (vpath).

Parameters:

Gammaarray-like of shape (n_samples, n_states), or a vpath array of shape (n_samples,)

The Gamma represents the state probability timeseries and the vpath represents the most likely state sequence.

indicesarray-like of shape (n_sessions, 2)

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

Returns:

SRarray-like of shape (n_sessions, n_states)

The switching rate matrix.

glhmm.utils.get_visits(vpath, k, threshold=0)

Computes a list of visits for state k, given a viterbi path (vpath).

Parameters:

vpatharray-like of shape (n_samples,)

The viterbi path represents the most likely state sequence.

kint

The state for which to compute the visits.

thresholdint, optional, default=0

A threshold value used to exclude visits with a duration below this value.

Returns:

lengthslist of floats

A list of visit durations for state k, where each duration is greater than the threshold.

onsetslist of ints

A list of onset time points for each visit.

Notes:

A visit to state k is defined as a contiguous sequence of time points in which state k is active.