osl_dynamics.inference.modes#

Functions to manipulate and calculate statistics for inferred mode/state time courses.

Module Contents#

Functions#

argmax_time_courses(alpha[, concatenate, n_modes])

Hard classifies a time course using an argmax operation.

gmm_time_courses(alpha[, logit_transform, ...])

Fit a two-component GMM to time courses to get a binary time course.

correlate_modes(mode_time_course_1, mode_time_course_2)

Calculate the correlation matrix between modes in two mode time courses.

match_covariances(*covariances[, comparison, return_order])

Matches covariances.

match_modes(*mode_time_courses[, return_order])

Find correlated modes between mode time courses.

reduce_state_time_course(state_time_course)

Remove states that don't activate from a state time course.

fractional_occupancies(state_time_course)

Wrapper for analysis.modes.fractional_occupancies.

mean_lifetimes(state_time_course[, sampling_frequency])

Wrapper for analysis.modes.mean_lifetimes.

mean_intervals(state_time_course[, sampling_frequency])

Wrapper for analysis.modes.mean_intervals.

switching_rates(state_time_course[, sampling_frequency])

Wrapper for analysis.modes.switching_rates.

mean_amplitudes(state_time_course, data)

Wrapper for analysis.modes.mean_amplitudes.

lifetime_statistics(state_time_course[, ...])

Wrapper for analysis.modes.lifetime_statistics.

fano_factor(state_time_course, window_length[, ...])

Wrapper for analysis.modes.fano_factor.

convert_to_mne_raw(alpha, raw[, ch_names, ...])

Convert a time series to an MNE Raw object.

reweight_alphas(alpha, covs)

Re-weight mixing coefficients to account for the magnitude of the mode covariances.

reweight_mtc(mtc, params, params_type)

Re-weight mixing coefficients to account for the magnitude of

average_runs(alpha[, n_clusters, return_cluster_info])

Average the state probabilities from different runs using hierarchical clustering.
osl_dynamics.inference.modes.argmax_time_courses(alpha, concatenate=False, n_modes=None)[source]#

Hard classifies a time course using an argmax operation.

Parameters:

  • alpha (list or np.ndarray) – Mode mixing factors or state probabilities. Shape must be (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

  • concatenate (bool, optional) – If alpha is a list, should we concatenate the time courses?

  • n_modes (int, optional) – Number of modes/states there should be. Useful if there are modes/states which never activate.

Returns:

argmax_tcs – Argmax time courses. Shape is (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

Return type:

list or np.ndarray

osl_dynamics.inference.modes.gmm_time_courses(alpha, logit_transform=True, standardize=True, p_value=None, filename=None, sklearn_kwargs=None, plot_kwargs=None)[source]#

Fit a two-component GMM to time courses to get a binary time course.

Parameters:

  • alpha (list of np.ndarray or np.ndarray) – Mode time courses. Shape must be (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

  • logit_transform (bool, optional) – Should we logit transform the mode time course?

  • standardize (bool, optional) – Should we standardize the mode time course?

  • p_value (float, optional) – Used to determine a threshold. We ensure the data points assigned to the ‘on’ component have a probability of less than p_value of belonging to the ‘off’ component.

  • filename (str, optional) – Path to directory to plot the GMM fit plots.

  • sklearn_kwargs (dict, optional) – Keyword arguments to pass to sklean.mixture.GaussianMixture.

  • plot_kwargs (dict, optional) – Dictionary of keyword arguments to pass to osl_dynamics.utils.plotting.plot_gmm.

Returns:

gmm_tcs – GMM time courses with binary entries. Shape is (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

Return type:

list of np.ndarray or np.ndarray

osl_dynamics.inference.modes.correlate_modes(mode_time_course_1, mode_time_course_2)[source]#

Calculate the correlation matrix between modes in two mode time courses.

Given two mode time courses, calculate the correlation between each pair of modes in the mode time courses. The output for each value in the matrix is the value numpy.corrcoef(mode_time_course_1, mode_time_course_2)[0, 1].

Parameters:

  • mode_time_course_1 (np.ndarray) – Mode time course. Shape must be (n_samples, n_modes).

  • mode_time_course_2 (np.ndarray) – Mode time course. Shape must be (n_samples, n_modes).

Returns:

correlation_matrix – Correlation matrix. Shape is (n_modes, n_modes).

Return type:

np.ndarray

osl_dynamics.inference.modes.match_covariances(*covariances, comparison='rv_coefficient', return_order=False)[source]#

Matches covariances.

Parameters:

  • covariances (tuple of np.ndarray) – Covariance matrices to match. Each covariance must be (n_modes, n_channel, n_channels).

  • comparison (str, optional) – Either 'rv_coefficient', 'correlation' or 'frobenius'. Default is 'rv_coefficient'.

  • return_order (bool, optional) – Should we return the order instead of the covariances?

Returns:

matched_covariances – Matched covariances of shape (n_channels, n_channels) or order if return_order=True.

Return type:

tuple or list of np.ndarray

Examples

Reorder the matrices directly:

>>> covs1, covs2 = match_covariances(covs1, covs2, comparison="correlation")

Just get the reordering:

>>> orders = match_covariances(covs1, covs2, comparison="correlation", return_order=True)
>>> print(orders[0])  # order for covs1 (always unchanged)
>>> print(orders[1])  # order for covs2
osl_dynamics.inference.modes.match_modes(*mode_time_courses, return_order=False)[source]#

Find correlated modes between mode time courses.

Given N mode time courses and using the first given mode time course as a basis, find the best matches for modes between all of the mode time courses. Once found, the mode time courses are returned with the modes reordered so that the modes match.

Given two arrays with columns ABCD and CBAD, both will be returned with modes in the order ABCD.

Parameters:

  • mode_time_courses (list of np.ndarray) – Mode time courses. Each time course must be (n_samples, n_modes).

  • return_order (bool, optional) – Should we return the order instead of the mode time courses.

Returns:

matched_mode_time_courses – Matched mode time courses of shape (n_samples, n_modes) or order if return_order=True.

Return type:

tuple or list of np.ndarray

Examples

Reorder the modes directly:

>>> alp1, alp2 = match_modes(alp1, alp2)

Just get the reordering:

>>> orders = match_modes(alp1, alp2, return_order=True)
>>> print(orders[0])  # order for alp1 (always unchanged)
>>> print(orders[1])  # order for alp2
osl_dynamics.inference.modes.reduce_state_time_course(state_time_course)[source]#

Remove states that don’t activate from a state time course.

Parameters:

state_time_course (np.ndarray) – State time course. Shape must be (n_samples, n_states).

Returns:

reduced_state_time_course – Reduced state time course. Shape is (n_samples, n_reduced_states).

Return type:

np.ndarray

osl_dynamics.inference.modes.fractional_occupancies(state_time_course)[source]#

Wrapper for analysis.modes.fractional_occupancies.

osl_dynamics.inference.modes.mean_lifetimes(state_time_course, sampling_frequency=None)[source]#

Wrapper for analysis.modes.mean_lifetimes.

osl_dynamics.inference.modes.mean_intervals(state_time_course, sampling_frequency=None)[source]#

Wrapper for analysis.modes.mean_intervals.

osl_dynamics.inference.modes.switching_rates(state_time_course, sampling_frequency=None)[source]#

Wrapper for analysis.modes.switching_rates.

osl_dynamics.inference.modes.mean_amplitudes(state_time_course, data)[source]#

Wrapper for analysis.modes.mean_amplitudes.

osl_dynamics.inference.modes.lifetime_statistics(state_time_course, sampling_frequency=None)[source]#

Wrapper for analysis.modes.lifetime_statistics.

osl_dynamics.inference.modes.fano_factor(state_time_course, window_length, sampling_frequency=1.0)[source]#

Wrapper for analysis.modes.fano_factor.

osl_dynamics.inference.modes.convert_to_mne_raw(alpha, raw, ch_names=None, n_embeddings=None, n_window=None, extra_chans='stim', verbose=False)[source]#

Convert a time series to an MNE Raw object.

Parameters:

  • alpha (np.ndarray) – Time series containing raw data. Shape must be (n_samples, n_modes).

  • raw (mne.io.Raw or str) – Raw object to extract info from. If a str is passed, it must be the path to a fif file containing the Raw object.

  • ch_names (list, optional) – Name for each channel. Defaults to alpha_0, ..., alpha_{n_modes-1}.

  • n_embeddings (int, optional) – Number of embeddings that was used to prepare time-delay embedded training data.

  • n_window (int, optional) – Number of samples used to smooth amplitude envelope data.

  • extra_chans (str or list of str, optional) – Extra channel types to add to the Raw object.

  • verbose (bool, optional) – Should we print a verbose?

Returns:

alpha_raw – MNE Raw object for alpha.

Return type:

mne.io.Raw

osl_dynamics.inference.modes.reweight_alphas(alpha, covs)[source]#

Re-weight mixing coefficients to account for the magnitude of the mode covariances.

Parameters:

  • alpha (list of np.ndarray or np.ndarray) – Raw mixing coefficients. Shape must be (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

  • covs (np.ndarray) – Mode covariances. Shape must be (n_modes, n_channels, n_channels).

Returns:

reweighted_alpha – Re-weighted mixing coefficients. Shape is the same as alpha.

Return type:

list of np.ndarray or np.ndarray

osl_dynamics.inference.modes.reweight_mtc(mtc, params, params_type)[source]#

Re-weight mixing coefficients to account for the magnitude of observation model parameters.

Parameters:

  • mtc (List[np.ndarray] or np.ndarray) – Raw mixing coefficients. Shape must be (n_sessions, n_samples, n_modes) or (n_samples, n_modes).

  • params (np.ndarray) – Observation model parameters. Shape must be (n_modes, n_channels, n_channels).

  • params_type (str) – Observation model parameters type. Either ‘covariance’ or ‘correlation’.

Returns:

reweighted_mtc – Re-weighted mixing coefficients. Shape is the same as mtc.

Return type:

List[np.ndarray]

osl_dynamics.inference.modes.average_runs(alpha, n_clusters=None, return_cluster_info=False)[source]#

Average the state probabilities from different runs using hierarchical clustering.

Parameters:

  • alpha (list of list of np.ndarray or list of np.ndarray) – State probabilities. Shape must be (n_runs, n_sessions, n_samples, n_states) or (n_runs, n_samples, n_states).

  • n_clusters (int, optional) – Number of clusters to fit. Defaults to the largest number of states in alpha.

  • return_cluster_info (bool, optional) – Should we return information describing the clustering?

Returns:

  • average_alpha (list of np.ndarray or np.ndarray) – State probabilities averaged over runs. Shape is (n_sessions, n_states).

  • cluster_info (dict) – Clustering info. Only returned if return_cluster_info=True. This is a dictionary with keys 'correlation', 'dissimiarity', 'ids' and 'linkage'.

See also

S. Alonso and D. Vidaurre, “Towards stability of dynamic FC estimates in neuroimaging and electrophysiology: solutions and limits” bioRxiv (2023): 2023-01.