osl_dynamics.simulation.hmm#

Classes for simulating Hidden Markov Models (HMMs).

Module Contents#

Classes#

HMM

HMM base class.

HMM_MAR

Simulate an HMM with a multivariate autoregressive (MAR) observation

HMM_MVN

Simulate an HMM with a mulitvariate normal observation model.

MDyn_HMM_MVN

Simulate an HMM with a mulitvariate normal observation model.

HMM_Poi

Simulate an HMM with Poisson distribution as the observation model.

MSess_HMM_MVN

Simulate an HMM with multivariate normal observation model for each

HierarchicalHMM_MVN

Hierarchical two-level HMM simulation.
class osl_dynamics.simulation.hmm.HMM(trans_prob, stay_prob=None, n_states=None)[source]#

HMM base class.

Contains the transition probability matrix.

Parameters:

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str ('sequence' or 'uniform') to generate a transition probability matrix.

  • stay_prob (float, optional) – Used to generate the transition probability matrix is trans_prob is a str. Must be between 0 and 1.

  • n_states (int, optional) – Number of states. Needed when trans_prob is a str to construct the transition probability matrix.

static construct_sequence_trans_prob(stay_prob, n_states)[source]#
static construct_uniform_trans_prob(stay_prob, n_states)[source]#
generate_states(n_samples)[source]#
class osl_dynamics.simulation.hmm.HMM_MAR(n_samples, trans_prob, coeffs, covs, stay_prob=None)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulate an HMM with a multivariate autoregressive (MAR) observation model.

Parameters:

  • n_samples (int) – Number of samples to draw from the model.

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str ('sequence' or 'uniform') to generate a transition probability matrix.

  • coeffs (np.ndarray) – Array of MAR coefficients. Shape must be (n_states, n_lags, n_channels, n_channels).

  • covs (np.ndarray) – Variance of \(\epsilon_t\). See simulation.MAR for further details. Shape must be (n_states, n_channels).

  • stay_prob (float, optional) – Used to generate the transition probability matrix is trans_prob is a str. Must be between 0 and 1.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
class osl_dynamics.simulation.hmm.HMM_MVN(n_samples, trans_prob, means, covariances, n_states=None, n_modes=None, n_channels=None, n_covariances_act=1, stay_prob=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulate an HMM with a mulitvariate normal observation model.

Parameters:

  • n_samples (int) – Number of samples to draw from the model.

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str ('sequence' or 'uniform') to generate a transition probability matrix.

  • means (np.ndarray or str) – Mean vector for each state, shape should be (n_states, n_channels). Either a numpy array or 'zero' or 'random'.

  • covariances (np.ndarray or str) – Covariance matrix for each state, shape should be (n_states, n_channels, n_channels). Either a numpy array or 'random'.

  • n_states (int, optional) – Number of states. Can pass this argument with keyword n_modes instead.

  • n_channels (int, optional) – Number of channels.

  • n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.

  • stay_prob (float, optional) – Used to generate the transition probability matrix is trans_prob is a str. Must be between 0 and 1.

  • observation_error (float, optional) – Standard deviation of the error added to the generated data.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
get_instantaneous_covariances()[source]#

Get the ground truth covariances at each time point.

Returns:

inst_covs – Instantaneous covariances. Shape is (n_samples, n_channels, n_channels).

Return type:

np.ndarray

standardize()[source]#
class osl_dynamics.simulation.hmm.MDyn_HMM_MVN(n_samples, trans_prob, means, covariances, n_states=None, n_modes=None, n_channels=None, n_covariances_act=1, stay_prob=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulate an HMM with a mulitvariate normal observation model.

Multi-time-scale version of HMM_MVN.

Parameters:

  • n_samples (int) – Number of samples to draw from the model.

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str ('sequence' or 'uniform') to generate a transition probability matrix.

  • means (np.ndarray or str) – Mean vector for each state, shape should be (n_states, n_channels). Either a numpy array or 'zero' or 'random'.

  • covariances (np.ndarray or str) – Covariance matrix for each state, shape should be (n_states, n_channels, n_channels). Either a numpy array or 'random'.

  • n_states (int, optional) – Number of states. Can pass this argument with keyword n_modes instead.

  • n_channels (int, optional) – Number of channels.

  • n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.

  • stay_prob (float, optional) – Used to generate the transition probability matrix is trans_prob is a str. Must be between 0 and 1.

  • observation_error (float, optional) – Standard deviation of the error added to the generated data.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
get_instantaneous_covariances()[source]#

Get the ground truth covariances at each time point.

Returns:

inst_covs – Instantaneous covariances. Shape is (n_samples, n_channels, n_channels).

Return type:

np.ndarray

standardize()[source]#
class osl_dynamics.simulation.hmm.HMM_Poi(n_samples, trans_prob, rates, n_states=None, n_channels=None, stay_prob=None)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulate an HMM with Poisson distribution as the observation model.

Parameters:

  • n_samples (int) – Number of samples to draw from the model.

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str (‘sequence’, ‘uniform’) to generate a transition probability matrix.

  • rates (np.ndarray) – Amplitude for the sine wave for each state and channel. Shape must be (n_states, n_channels).

  • stay_prob (float) – Used to generate the transition probability matrix is trans_prob is a str.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
class osl_dynamics.simulation.hmm.MSess_HMM_MVN(n_samples, trans_prob, session_means, session_covariances, n_states=None, n_modes=None, n_channels=None, n_covariances_act=1, embedding_vectors=None, n_sessions=None, embeddings_dim=None, spatial_embeddings_dim=None, embeddings_scale=None, n_groups=None, between_group_scale=None, tc_std=0.0, stay_prob=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulate an HMM with multivariate normal observation model for each session.

Parameters:

  • n_samples (int) – Number of samples per session to draw from the model.

  • trans_prob (np.ndarray or str) – Transition probability matrix as a numpy array or a str ('sequence' or 'uniform') to generate a transition probability matrix.

  • session_means (np.ndarray or str) – Session mean vector for each state, shape should be (n_sessions, n_states, n_channels). Either a numpy array or 'zero' or 'random'.

  • session_covariances (np.ndarray or str) – Session covariance matrix for each state, shape should be (n_sessions, n_states, n_channels, n_channels). Either a numpy array or 'random'.

  • n_states (int, optional) – Number of states. Can pass this argument with keyword n_modes instead.

  • n_modes (int, optional) – Number of modes.

  • n_channels (int, optional) – Number of channels.

  • n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.

  • embedding_vectors (np.ndarray, optional) – Embedding vectors for each state, shape should be (n_states, embeddings_dim).

  • n_sessions (int, optional) – Number of sessions.

  • embeddings_dim (int) – Dimension of the embedding vectors.

  • spatial_embeddings_dim (int) – Dimension of the spatial embedding vectors.

  • embeddings_scale (float) – Scale of the embedding vectors.

  • n_groups (int, optional) – Number of groups when session means or covariances are 'random'.

  • between_group_scale (float, optional) – Scale of variability between session observation parameters.

  • stay_prob (float, optional) – Used to generate the transition probability matrix is trans_prob is a str. Must be between 0 and 1.

  • tc_std (float, optional) – Standard deviation when generating session-specific stay probability.

  • observation_error (float, optional) – Standard deviation of the error added to the generated data.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
get_instantaneous_covariances()[source]#

Get the ground truth covariances at each time point.

Returns:

inst_covs – Instantaneous covariances. Shape is (n_samples, n_channels, n_channels).

Return type:

np.ndarray

standardize()[source]#
class osl_dynamics.simulation.hmm.HierarchicalHMM_MVN(n_samples, top_level_trans_prob, bottom_level_trans_probs, means=None, covariances=None, n_states=None, n_modes=None, n_channels=None, n_covariances_act=1, observation_error=0.0, top_level_stay_prob=None, bottom_level_stay_probs=None, top_level_hmm_type='hmm', top_level_gamma_shape=None, top_level_gamma_scale=None)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Hierarchical two-level HMM simulation.

The bottom level HMMs share the same states, i.e. have the same observation model. Only the transition probability matrix changes.

Parameters:

  • n_samples (int) – Number of samples to draw from the model.

  • top_level_trans_prob (np.ndarray or str) – Transition probability matrix of the top level HMM, which selects the bottom level HMM at each time point. Used when top_level_hmm_type='hmm'.

  • bottom_level_trans_prob (list of np.ndarray or str) – Transitions probability matrices for the bottom level HMMs, which generate the observed data.

  • means (np.ndarray or str, optional) – Mean vector for each state, shape should be (n_states, n_channels). Either a numpy array or 'zero' or 'random'.

  • covariances (np.ndarray or str, optional) – Covariance matrix for each state, shape should be (n_states, n_channels, n_channels). Either a numpy array or 'random'.

  • n_states (int, optional) – Number of states. Can pass this argument with keyword n_modes instead.

  • n_channels (int, optional) – Number of channels.

  • n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.

  • observation_error (float, optional) – Standard deviation of random noise to be added to the observations.

  • top_level_stay_prob (float, optional) – The stay_prob for the top level HMM. Used if top_level_trans_prob is a str. Used when top_level_hmm_type='hmm'.

  • bottom_level_stay_probs (list of float, optional) – The list of stay_prob values for the bottom level HMMs. Used when the correspondining entry in bottom_level_trans_prob is a str.

  • top_level_hmm_type (str, optional) – The type of HMM to use at the top level, either 'hmm' or 'hsmm'.

  • top_level_gamma_shape (float, optional) – The shape parameter for the Gamma distribution used by the top level hmm when top_level_hmm_type='hsmm'.

  • top_level_gamma_scale (float, optional) – The scale parameter for the Gamma distribution used by the top level hmm when top_level_hmm_type='hsmm'.

property n_modes[source]#
property mode_time_course[source]#
__getattr__(attr)[source]#
generate_states(n_samples)[source]#
standardize()[source]#