osl_dynamics.simulation.hmm#

Classes for simulating Hidden Markov Models (HMMs).

Classes#

`HMM`	HMM base class.
`HMM_MAR`	Simulate an HMM with a multivariate autoregressive (MAR) observation model.
`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 session.
`HierarchicalHMM_MVN`	Hierarchical two-level HMM simulation.
`HMM_OscillatoryBursts`	Simulate an HMM with oscillatory burst observation model.
`HMM_TDECovs`	Simulate an HMM with TDE covariance observation model.

Module Contents#

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.

n_states[source]#

static construct_sequence_trans_prob(stay_prob, n_states)[source]#

Parameters:

stay_prob (float)
n_states (int)

Return type:

numpy.ndarray

static construct_uniform_trans_prob(stay_prob, n_states)[source]#

Parameters:

stay_prob (float)
n_states (int)

Return type:

numpy.ndarray

generate_states(n_samples)[source]#

Parameters:: n_samples (int)
Return type:: numpy.ndarray

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 osl_dynamics.simulation.mar.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.

obs_mod[source]#

n_states[source]#

n_channels[source]#

hmm[source]#

state_time_course[source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

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.
n_modes (Optional[int])

obs_mod[source]#

n_states[source]#

n_channels[source]#

hmm[source]#

state_time_course[source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

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]#

Return type:: None

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.
n_modes (Optional[int])

obs_mod[source]#

n_states[source]#

n_channels[source]#

alpha_hmm[source]#

beta_hmm[source]#

state_time_course[source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

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]#

Return type:: None

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.
n_states (Optional[int])
n_channels (Optional[int])

obs_mod[source]#

n_states[source]#

n_channels[source]#

hmm[source]#

state_time_course[source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

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.

obs_mod[source]#

n_states[source]#

n_channels[source]#

n_sessions[source]#

state_time_course = [][source]#

hmm = [][source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

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]#

Return type:: None

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'.
bottom_level_trans_probs (List[Union[numpy.ndarray, str]])
n_modes (Optional[int])

obs_mod[source]#

n_states[source]#

n_channels[source]#

n_bottom_level_hmms[source]#

bottom_level_hmms[source]#

state_time_course[source]#

time_series[source]#

property n_modes: int[source]#

Return type:: int

property mode_time_course: numpy.ndarray[source]#

Return type:: numpy.ndarray

generate_states(n_samples)[source]#

Parameters:: n_samples (int)
Return type:: numpy.ndarray

standardize()[source]#

Return type:: None

class osl_dynamics.simulation.hmm.HMM_OscillatoryBursts(n_samples, n_subjects=1, n_groups=1, true_freqs=None, group_freq_shift=0.5, channel_activity=None, n_modes=4, n_channels_per_mode=8, sampling_frequency=100, snr=4, stay_prob=0.98)[source]#

Simulate an HMM with oscillatory burst observation model.

Uses an HMM to generate state time courses, then fills active periods with sinusoidal oscillations at specified frequencies. Each mode has a set of active channels and a characteristic frequency. An extra “background” state (silence) is included automatically.

Multiple subjects can be simulated with optional group-level frequency shifts.

Parameters:

n_samples (int) – Number of time points per subject.
n_subjects (int, optional) – Number of subjects.
n_groups (int, optional) – Number of subject groups. n_subjects must be divisible by n_groups.
true_freqs (np.ndarray, optional) – Frequencies for each mode in Hz. Shape: (n_modes,). If not provided, n_modes frequencies are linearly spaced between 8 and 25 Hz.
group_freq_shift (float, optional) – Frequency shift between groups in Hz.
channel_activity (np.ndarray, optional) – Binary matrix indicating active channels per mode. Shape: (n_modes, n_channels). If not provided, an identity-like matrix is created with n_channels_per_mode channels per mode.
n_modes (int, optional) – Number of frequency modes. Ignored if channel_activity is given.
n_channels_per_mode (int, optional) – Channels per mode when auto-generating channel_activity.
sampling_frequency (float, optional) – Sampling frequency in Hz.
snr (float, optional) – Signal-to-noise ratio.
stay_prob (float, optional) – HMM state stay probability.

n_samples[source]#

n_subjects = 1[source]#

n_groups = 1[source]#

n_subjects_per_group = 1[source]#

sampling_frequency = 100[source]#

snr = 4[source]#

stay_prob = 0.98[source]#

true_freqs[source]#

hmm[source]#

property time_series[source]#

(n_subjects, n_samples, n_channels).

Type:: np.ndarray
Type:: Simulated data. Shape

property state_time_course[source]#

(n_subjects, n_samples, n_modes + 1).

Type:: np.ndarray
Type:: State time courses. Shape

class osl_dynamics.simulation.hmm.HMM_TDECovs(n_samples, true_tde_covs, n_subjects=1, n_embeddings=1, stay_prob=0.98, rho=0.1)[source]#

Simulate an HMM with TDE covariance observation model.

Uses an HMM to generate state time courses, then generates time series data from TDE covariance matrices using conditional multivariate normal sampling. Each mode is defined by a TDE covariance matrix that encodes both spectral and cross-channel structure.

Multiple subjects can be simulated, each with independent state time courses.

Parameters:

n_samples (int) – Number of time points per subject.
true_tde_covs (list of np.ndarray) – List of n_modes TDE covariance matrices, each of shape (n_channels * n_embeddings, n_channels * n_embeddings).
n_subjects (int, optional) – Number of subjects.
n_embeddings (int, optional) – Number of time-delay embeddings.
stay_prob (float, optional) – HMM state stay probability.
rho (float, optional) – Regularisation parameter for inverting the covariance.

n_samples[source]#

n_subjects = 1[source]#

obs_mod[source]#

n_modes[source]#

n_channels[source]#

hmm[source]#

property time_series[source]#

(n_subjects, n_samples, n_channels).

Type:: np.ndarray
Type:: Simulated data. Shape

property state_time_course[source]#

(n_subjects, n_samples, n_modes).

Type:: np.ndarray
Type:: State time courses. Shape