osl_dynamics.analysis.modes#

Functions to manipulate and analyse inferred mode/state data.

Module Contents#

Functions#

autocorr_from_tde_cov(covs, n_embeddings[, ...])

Auto/cross-correlation function from the mode covariance matrices.

raw_covariances(mode_covariances, n_embeddings[, ...])

Covariance matrix of the raw channels.

reverse_pca(covariances, pca_components)

Reverses the effect of PCA on covariance matrices.

state_activations(state_time_course)

Calculate state activations from a state time course.

lifetimes(state_time_course[, sampling_frequency, squeeze])

Calculate state lifetimes from a state time course.

lifetime_statistics(state_time_course[, ...])

Calculate statistics of the lifetime distribution of each state.

mean_lifetimes(state_time_course[, sampling_frequency])

Calculate the mean lifetime of each state.

intervals(state_time_course[, sampling_frequency, squeeze])

Calculate state intervals from a state time course.

interval_statistics(state_time_course[, ...])

Calculate statistics of the interval distribution of each state.

mean_intervals(state_time_course[, sampling_frequency])

Calculate the mean interval of each state.

fractional_occupancies(state_time_course)

Calculate the fractional occupancy.

switching_rates(state_time_course[, sampling_frequency])

Calculate the switching rate.

mean_amplitudes(state_time_course, data)

Calculate mean amplitude for bursts.

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

Calculate the Fano factor.

calc_trans_prob_matrix(state_time_course[, n_states])

Calculate session-specific transition probability matrices.

simple_moving_average(data, window_length, step_size)

Calculate imple moving average.

partial_covariances(data, alpha)

Calculate partial covariances.

hmm_dual_estimation(data, alpha[, zero_mean, eps, n_jobs])

HMM dual estiation of observation model parameters.

Attributes#

_logger

osl_dynamics.analysis.modes._logger[source]#
osl_dynamics.analysis.modes.autocorr_from_tde_cov(covs, n_embeddings, pca_components=None, sampling_frequency=None)[source]#

Auto/cross-correlation function from the mode covariance matrices.

Parameters:

  • covs (np.ndarray) – Covariance matrix of time-delay embedded data. Shape must be (n_channels, n_channels) or (n_modes, n_channels, n_channels).

  • n_embeddings (int) – Number of embeddings.

  • pca_components (np.ndarray, optional) – PCA components used for dimensionality reduction. Only needs to be passed if PCA was performed on the time embedded data.

  • sampling_frequency (float, optional) – Sampling_frequency in Hz.

Returns:

  • tau (np.ndarray) – Time lags in samples if sampling_frequency=None, otherwise in seconds. Shape is (n_lags).

  • acfs (np.ndarray) – Auto/cross-correlation functions. Shape is (n_channels, n_channels, n_lags) or (n_modes, n_channels, n_channels, n_lags).

osl_dynamics.analysis.modes.raw_covariances(mode_covariances, n_embeddings, pca_components=None, zero_lag=False)[source]#

Covariance matrix of the raw channels.

PCA and time embedding is reversed to give you to the covariance matrix of the raw channels.

Parameters:

  • mode_covariances (np.ndarray) – Mode covariance matrices.

  • n_embeddings (int) – Number of embeddings applied to the training data.

  • pca_components (np.ndarray, optional) – PCA components used for dimensionality reduction.

  • zero_lag (bool, optional) – Should we return just the zero-lag elements? Otherwise, we return the mean over time lags.

Returns:

raw_covs – Covariance matrix for raw channels.

Return type:

np.ndarray

osl_dynamics.analysis.modes.reverse_pca(covariances, pca_components)[source]#

Reverses the effect of PCA on covariance matrices.

Parameters:

  • covariances (np.ndarray) – Covariance matrices.

  • pca_components (np.ndarray) – PCA components used for dimensionality reduction.

Returns:

covariances – Covariance matrix of the time embedded data.

Return type:

np.ndarray

osl_dynamics.analysis.modes.state_activations(state_time_course)[source]#

Calculate state activations from a state time course.

Given a state time course (strictly binary), calculate the beginning and end of each activation of each state. Accepts a 1D or 2D array. If a 1D array is passed, it is assumed to be a single state time course.

Either an array of ints or an array of bool is accepted, but if int are passed they should be explicitly 0 or 1.

Parameters:

state_time_course (numpy.ndarray or list of numpy.ndarray) – State time course (strictly binary).

Returns:

slices – List containing state activations (index) in the order they occur for each state. This cannot necessarily be converted into an array as an equal number of elements in each array is not guaranteed.

Return type:

list of list of slice

osl_dynamics.analysis.modes.lifetimes(state_time_course, sampling_frequency=None, squeeze=True)[source]#

Calculate state lifetimes from a state time course.

Given a state time course (one-hot encoded), calculate the lifetime of each activation of each state.

Parameters:

  • state_time_course (numpy.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, or n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the lifetimes in seconds.

  • squeeze (bool, optional) – If True, squeeze the output to remove singleton dimensions.

Returns:

lts – List containing an array of lifetimes in the order they occur for each state. This cannot necessarily be converted into an array as an equal number of elements in each array is not guaranteed. Shape is (n_sessions, n_states, n_activations) or (n_states, n_activations).

Return type:

list of numpy.ndarray

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

Calculate statistics of the lifetime distribution of each state.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the lifetimes in seconds.

Returns:

  • means (np.ndarray) – Mean lifetime of each state. Shape is (n_sessions, n_states) or (n_states,).

  • std (np.ndarray) – Standard deviation of each state. Shape is (n_sessions, n_states) or (n_states,).

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

Calculate the mean lifetime of each state.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the lifetimes in seconds.

Returns:

mlt – Mean lifetime of each state. Shape is (n_sessions, n_states) or (n_states,).

Return type:

np.ndarray

osl_dynamics.analysis.modes.intervals(state_time_course, sampling_frequency=None, squeeze=True)[source]#

Calculate state intervals from a state time course.

An interval is the duration between successive visits for a particular state.

Parameters:

  • state_time_course (list or numpy.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the intervals in seconds.

  • squeeze (bool, optional) – If True, squeeze the output to remove singleton dimensions.

Returns:

intvs – List containing an array of intervals in the order they occur for each state. This cannot necessarily be converted into an array as an equal number of elements in each array is not guaranteed. Shape is (n_sessions, n_states, n_activations) or (n_states, n_activations).

Return type:

list of numpy.ndarray

osl_dynamics.analysis.modes.interval_statistics(state_time_course, sampling_frequency=None)[source]#

Calculate statistics of the interval distribution of each state.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the lifetimes in seconds.

Returns:

  • means (np.ndarray) – Mean interval of each state. Shape is (n_sessions, n_states) or (n_states,).

  • std (np.ndarray) – Standard deviation of each state. Shape is (n_sessions, n_states) or (n_states,).

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

Calculate the mean interval of each state.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If passed returns the intervals in seconds.

Returns:

mlt – Mean interval of each state. Shape is (n_sessions, n_states) or (n_states,).

Return type:

np.ndarray

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

Calculate the fractional occupancy.

Parameters:

state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

Returns:

fo – The fractional occupancy of each state. Shape is (n_sessions, n_states) or (n_states,).

Return type:

np.ndarray

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

Calculate the switching rate.

This is defined as the number of state activations per second.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • sampling_frequency (float, optional) – Sampling frequency in Hz. If None, defaults to 1 Hz.

Returns:

sr – The switching rate of each state. Shape is (n_sessions, n_states) or (n_states,).

Return type:

np.ndarray

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

Calculate mean amplitude for bursts.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • data (list or np.ndarray) – Single channel time series data (before calculating the amplitude envelope). Shape must be (n_sessions, n_samples, 1) or (n_samples, 1).

Returns:

amp – Mean amplitude of the data for each state. Shape is (n_sessions, n_states) or (n_states,).

Return type:

np.ndarray

osl_dynamics.analysis.modes.fano_factor(state_time_course, window_lengths, sampling_frequency=1.0)[source]#

Calculate the Fano factor.

Parameters:

  • state_time_course (list or np.ndarray) – State time course (strictly binary). Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • window_lengths (list or np.ndarray) – Window lengths to use. Must be in samples.

  • sampling_frequency (float, optional) – Sampling frequency in Hz.

Returns:

F – Fano factor. Shape is (n_sessions, n_window_lengths, n_states) or (n_window_lengths, n_states).

Return type:

list of np.ndarray

osl_dynamics.analysis.modes.calc_trans_prob_matrix(state_time_course, n_states=None)[source]#

Calculate session-specific transition probability matrices.

Parameters:

  • state_time_course (list of np.ndarray or np.ndarray) – State time courses. Shape must be (n_sessions, n_samples, n_states) or (n_samples, n_states).

  • n_states (int, optional) – Number of states.

Returns:

trans_prob – Session-specific transition probability matrices. Shape is (n_sessions, n_states, n_states).

Return type:

np.ndarray

osl_dynamics.analysis.modes.simple_moving_average(data, window_length, step_size)[source]#

Calculate imple moving average.

This function can be used to calculate a sliding window fractional occupancy from a state time course. This was done in Baker et al. (2014).

Parameters:

  • data (np.ndarray) – Time series data. Shape must be (n_samples, n_channels).

  • window_length (int) – Number of data points in a window.

  • step_size (int) – Step size for shifting the window.

Returns:

mov_avg – Mean for each window.

Return type:

np.ndarray

osl_dynamics.analysis.modes.partial_covariances(data, alpha)[source]#

Calculate partial covariances.

Returns the multiple regression parameters estimates of the state/mode time courses regressed onto the data from each channel. The regression parameters are referred to as ‘partial covariances’.

We fit the regression:

\[Y_i = X \beta_i + \epsilon\]

where:

  • \(Y_i\) is (n_samples, 1) the data amplitude/envelope/power/absolute time course at channel \(i\).

  • \(X\) is (n_samples, n_states) matrix of the variance normalised state/mode time courses.

  • \(\beta_i\) is an (n_states, 1) vector of multiple regression parameters for channel \(i\).

  • \(\epsilon\) is the error.

Parameters:

  • data (np.ndarray or list of np.ndarray) – Training data for each array. Shape is (n_sessions, n_samples, n_channels) or (n_samples, n_channels).

  • alpha (np.ndarray or list of np.ndarray) – State/mode time courses for each array. Shape is (n_sessions, n_samples, n_states) or (n_samples, n_states).

Returns:

partial_covariances – Matrix of partial covariance (multiple regression parameter estimates, \(\beta\)). Shape is (n_states, n_channels).

Return type:

np.ndarray

Note

  • The regression is done separately for each channel.

  • State/mode time courses are variance normalized so that all amplitude info goes into the partial covariances, \(\beta_i\).

osl_dynamics.analysis.modes.hmm_dual_estimation(data, alpha, zero_mean=False, eps=1e-05, n_jobs=1)[source]#

HMM dual estiation of observation model parameters.

Parameters:

  • data (np.ndarray or list of np.ndarray) – Time series data. Shape must be (n_samples, n_channels) or (n_subjects, n_samples, n_channels).

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

  • zero_mean (bool, optional) – Should we force the state means to be zero?

  • eps (float, optional) – Small value to add to the diagonal of each state covariance.

  • n_jobs (int, optional) – Number of jobs to run in parallel.

Returns:

  • means (np.ndarray or list of np.ndarray) – State means. Shape is (n_states, n_channels) or (n_subjects, n_states, n_channels).

  • covariances (np.ndarray or list of np.ndarray) – State covariances. Shape is (n_states, n_channels, n_channels) or (n_subjects, n_states, n_channels, n_channels).