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