osl_dynamics.simulation#

Simulations for time series data.

This subpackage provides tools for generating synthetic time series data with known ground truth dynamics. Simulations are built by combining a state model (how states evolve over time) with an observation model (how data is generated given the active state).

State models#

HMM — Hidden Markov Model. Generates discrete state sequences with Markovian transitions.
HSMM — Hidden Semi-Markov Model. Like HMM but state lifetimes follow a Gamma distribution rather than a geometric distribution.
MixedSine — Sinusoidal soft mixtures. Generates smooth, overlapping mode time courses using softmax-normalised sinusoids.

Observation models#

MVN — Multivariate normal. Each state has a mean vector and covariance matrix.
MAR — Multivariate autoregressive. Each state has a set of autoregressive coefficients and an error covariance.
OscillatoryBursts — Oscillatory bursts. Each state has a frequency and a set of active channels; generates sinusoidal signals during active periods.
TDECovs — TDE covariance. Each state has a TDE covariance matrix; generates autoregressive data via conditional sampling.
Poisson — Poisson. Each state has a rate vector.

Combined simulation classes#

These combine a state model with an observation model:

HMM_MVN — HMM + MVN.
HMM_MAR — HMM + MAR.
HMM_OscillatoryBursts — HMM + oscillatory bursts.
HMM_TDECovs — HMM + TDE covariances.
HMM_Poi — HMM + Poisson.
HSMM_MVN — HSMM + MVN.
MixedHSMM_MVN — HSMM with overlapping states + MVN.
MixedSine_MVN — Sinusoidal mixing + MVN.

Variants#

MDyn_ prefix — Multi-time-scale dynamics (separate HMMs for power and connectivity): MDyn_HMM_MVN.
MSess_ prefix — Multi-session data with session-specific parameters: MSess_HMM_MVN, MSess_MixedSine_MVN.
HierarchicalHMM_MVN — Two-level hierarchical HMM where a top-level HMM selects which bottom-level HMM is active.

Python example scripts#

Simulation

Classes#

`Simulation`	Simulation base class.
`MAR`	Class that generates data from a multivariate autoregressive (MAR) model.
`MVN`	Class that generates data from a multivariate normal distribution.
`MDyn_MVN`	Class that generates data from a multivariate normal distribution.
`MSess_MVN`	Class that generates data from a multivariate normal distribution for multiple sessions.
`OscillatoryBursts`	Oscillatory burst observation model.
`Poisson`	Class that generates Poisson time series data.
`TDECovs`	Time-delay embedded covariance observation model.
`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.
`HMM_OscillatoryBursts`	Simulate an HMM with oscillatory burst observation model.
`HMM_TDECovs`	Simulate an HMM with TDE covariance observation model.
`MDyn_HMM_MVN`	Simulate an HMM with a mulitvariate normal observation model.
`HierarchicalHMM_MVN`	Hierarchical two-level HMM simulation.
`MSess_HMM_MVN`	Simulate an HMM with multivariate normal observation model for each session.
`HMM_Poi`	Simulate an HMM with Poisson distribution as the observation model.
`HSMM`	HSMM base class.
`HSMM_MVN`	Hidden Semi-Markov Model Simulation.
`MixedHSMM_MVN`	Hidden Semi-Markov Model Simulation with a mixture of states at each time point.
`MixedSine`	Simulates sinusoidal oscilations in mode time courses.
`MixedSine_MVN`	Simulates sinusoidal alphas with a multivariable normal observation model.
`MSess_MixedSine_MVN`	Simulates sinusoidal alphas with a multivariable normal observation model for each session.

Package Contents#

class osl_dynamics.simulation.Simulation(n_samples)[source]#

Simulation base class.

Parameters:: n_samples (int) – Number of time points to generate.

n_samples#

time_series = None#

standardize(axis=0)[source]#

Parameters:: axis (int)
Return type:: None

class osl_dynamics.simulation.MAR(coeffs, covs)[source]#

Class that generates data from a multivariate autoregressive (MAR) model.

A \(p\)-order MAR model can be written as

\[x_t = A_1 x_{t-1} + ... + A_p x_{t-p} + \epsilon_t\]

where \(\epsilon_t \sim N(0, \Sigma)\). The MAR model is therefore parameterized by the MAR coefficients (\(A\)) and covariance (\(\Sigma\)).

Parameters:

coeffs (np.ndarray) – Array of MAR coefficients, \(A\). Shape must be (n_states, n_lags, n_channels, n_channels).
covs (np.ndarray) – Covariance of the error \(\epsilon_t\). Shape must be (n_states, n_channels) or (n_states, n_channels, n_channels).

Note

This model is also known as VAR or MVAR.

coeffs#

covs#

order#

n_states#

n_channels#

simulate_data(state_time_course)[source]#

Simulate time series data.

We simulate MAR data based on the hidden state at each time point.

Parameters:: state_time_course (np.ndarray) – State time course. Shape must be (n_samples, n_states). States must be mutually exclusive.
Returns:: data – Simulated data. Shape is (n_samples, n_channels).
Return type:: np.ndarray

class osl_dynamics.simulation.MVN(means, covariances, n_modes=None, n_channels=None, n_covariances_act=1, observation_error=0.0)[source]#

Class that generates data from a multivariate normal distribution.

Parameters:

means (np.ndarray or str) – Mean vector for each mode, shape should be (n_modes, n_channels). Either a numpy array or 'zero' or 'random'.
covariances (np.ndarray or str) – Covariance matrix for each mode, shape should be (n_modes, n_channels, n_channels). Either a numpy array or 'random'.
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.
observation_error (float, optional) – Standard deviation of the error added to the generated data.

n_covariances_act = 1#

observation_error = 0.0#

create_means(option, mu=0, sigma=0.2)[source]#

Parameters:

option (str)
mu (float)
sigma (float)

Return type:

numpy.ndarray

create_covariances(option, activation_strength=1, eps=1e-06)[source]#

Parameters:

option (str)
activation_strength (float)
eps (float)

Return type:

numpy.ndarray

simulate_data(state_time_course)[source]#

Simulate time series data.

Parameters:: state_time_course (np.ndarray) – 2D array containing state activations. Shape must be (n_samples, n_states).
Returns:: data – Time series data. Shape is (n_samples, n_channels).
Return type:: np.ndarray

get_instantaneous_covariances(state_time_course)[source]#

Get the ground truth covariance at each time point.

Parameters:: state_time_course (np.ndarray) – 2D array containing state activations. Shape must be (n_samples, n_states).
Returns:: inst_covs – Instantaneous covariances. Shape is (n_samples, n_channels, n_channels).
Return type:: np.ndarray

class osl_dynamics.simulation.MDyn_MVN(means, covariances, n_modes=None, n_channels=None, n_covariances_act=1, observation_error=0.0)[source]#

Bases: MVN

Class that generates data from a multivariate normal distribution.

Multi-time-scale version of MVN.

Parameters:

means (np.ndarray or str) – Mean vector for each mode, shape should be (n_modes, n_channels). Either a numpy array or 'zero' or 'random'.
covariances (np.ndarray or str) – Covariance matrix for each mode, shape should be (n_modes, n_channels, n_channels). Either a numpy array or 'random'.
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.
observation_error (float, optional) – Standard deviation of the error added to the generated data.

stds#

corrs#

simulate_data(state_time_courses)[source]#

Simulates data.

Parameters:: state_time_courses (np.ndarray) – Should contain two time courses: one for the mean and standard deviations and another for functional connectiivty. Shape is (2, n_samples, n_modes).
Returns:: data – Simulated data. Shape is (n_samples, n_channels).
Return type:: np.ndarray

get_instantaneous_covariances(state_time_courses)[source]#

Get the ground truth covariance at each time point.

Parameters:: state_time_courses (np.ndarray) – Should contain two time courses: one for the mean and standard deviations and another for functional connectiivty. Shape is (2, n_samples, n_modes).
Returns:: inst_covs – Instantaneous covariances. Shape is (n_samples, n_channels, n_channels).
Return type:: np.ndarray

class osl_dynamics.simulation.MSess_MVN(session_means, session_covariances, 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, observation_error=0.0)[source]#

Bases: MVN

Class that generates data from a multivariate normal distribution for multiple sessions.

Parameters:

session_means (np.ndarray or str) – Mean vector for each mode for each session, shape should be (n_sessions, n_modes, n_channels). Either a numpy array or 'zero' or 'random'.
session_covariances (np.ndarray or str) – Covariance matrix for each mode for each session, shape should be (n_sessions, n_modes, n_channels, n_channels). Either a numpy array or 'random'.
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 session, shape should be (n_sessions, embeddings_dim).
n_sessions (int, optional) – Number of sessions.
embeddings_dim (int, optional) – Dimension of embeddings.
spatial_embeddings_dim (int, optional) – Dimension of spatial embeddings.
embeddings_scale (float, optional) – Standard deviation when generating embeddings with a normal distribution.
n_groups (int, optional) – Number of groups when generating embeddings.
between_group_scale (float, optional) – Standard deviation when generating centroids of groups of embeddings.
observation_error (float, optional) – Standard deviation of the error added to the generated data.

n_covariances_act = 1#

observation_error = 0.0#

embeddings_dim = None#

spatial_embeddings_dim = None#

embeddings_scale = None#

n_groups = None#

between_group_scale = None#

validate_embedding_parameters(embedding_vectors)[source]#

Parameters:: embedding_vectors (Optional[numpy.ndarray])
Return type:: None

create_embeddings(embedding_vectors)[source]#

Parameters:: embedding_vectors (Optional[numpy.ndarray])
Return type:: None

create_linear_transform(input_dim, output_dim, scale=0.1)[source]#

Parameters:

input_dim (int)
output_dim (int)
scale (float)

Return type:

numpy.ndarray

create_session_means_deviations()[source]#

Return type:: None

create_session_covariances_deviations()[source]#

Return type:: None

create_session_means(option)[source]#

Parameters:: option (str)
Return type:: numpy.ndarray

create_session_covariances(eps=1e-06)[source]#

Parameters:: eps (float)
Return type:: numpy.ndarray

simulate_session_data(session, mode_time_course)[source]#

Simulate single session data.

Parameters:

session (int) – Session number.
mode_time_course (np.ndarray) – Mode time course. Shape is (n_samples, n_modes).

Returns:

data – Simulated data. Shape is (n_samples, n_channels).

Return type:

np.ndarray

get_session_instantaneous_covariances(session, mode_time_course)[source]#

Get ground truth covariances at each time point for a particular session.

Parameters:

session (int) – Session number.
mode_time_course (np.ndarray) – Mode time course. Shape is (n_samples, n_modes).

Returns:

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

Return type:

np.ndarray

get_instantaneous_covariances(mode_time_courses)[source]#

Get ground truth covariance at each time point for each session.

Parameters:: mode_time_courses (np.ndarray) – Mode time courses. Shape is (n_sessions, n_samples, n_modes).
Returns:: inst_covs – Instantaneous covariances. Shape is (n_sessions, n_samples, n_channels, n_channels).
Return type:: np.ndarray

simulate_multi_session_data(mode_time_courses)[source]#

Simulates data.

Parameters:: mode_time_courses (np.ndarray) – It contains n_sessions time courses. Shape is (n_sessions, n_samples, n_modes).
Returns:: data – Simulated data for sessions. Shape is (n_sessions, n_samples, n_channels).
Return type:: np.ndarray

class osl_dynamics.simulation.OscillatoryBursts(n_modes, n_channels, true_freqs, channel_activity, sampling_frequency=100, snr=4)[source]#

Oscillatory burst observation model.

Generates sinusoidal oscillatory bursts at specified frequencies. Each mode has an associated frequency and a set of active channels defined by a channel activity matrix. During active periods (determined by the state time course), channels produce sinusoidal signals at the mode’s frequency with a slowly varying phase offset.

Parameters:

n_modes (int) – Number of frequency modes.
n_channels (int) – Number of channels.
true_freqs (np.ndarray) – Frequencies for each mode in Hz. Shape: (n_modes,).
channel_activity (np.ndarray) – Binary matrix indicating which channels are active for each mode. Shape: (n_modes, n_channels).
sampling_frequency (float, optional) – Sampling frequency in Hz. Default: 100.
snr (float, optional) – Signal-to-noise ratio. Default: 4.

n_modes#

n_channels#

true_freqs#

channel_activity#

sampling_frequency = 100#

snr = 4#

simulate_data(state_time_course)[source]#

Simulate oscillatory burst data for a single subject.

Parameters:

state_time_course (np.ndarray) – One-hot encoded state time course. Shape: (n_samples, n_states). The first n_modes columns correspond to the oscillatory modes. Any additional columns (e.g. a “background” state) are ignored.

Returns:

data (np.ndarray) – Simulated data with noise. Shape: (n_samples, n_channels).
true_signal (np.ndarray) – Clean signal without noise. Shape: (n_samples, n_channels).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

class osl_dynamics.simulation.Poisson(rates, n_states=None, n_channels=None)[source]#

Class that generates Poisson time series data.

The time series for each channel is a single Poisson observation. The rate of the poisson observation can be different for different states and channels.

Parameters:

rates (np.ndarray or str) – Rate vector for each mode, shape should be (n_states, n_channels). Either a numpy array or ‘random’.
n_channels (int) – Number of channels.
n_modes (int) – Number of modes.
n_states (Optional[int])

create_rates(option, eps=0.01)[source]#

Parameters:

option (str)
eps (float)

Return type:

numpy.ndarray

simulate_data(state_time_course)[source]#

Parameters:: state_time_course (numpy.ndarray)
Return type:: numpy.ndarray

class osl_dynamics.simulation.TDECovs(true_tde_covs, n_embeddings=1, rho=0.1)[source]#

Time-delay embedded covariance observation model.

Generates time series data from TDE covariance matrices using conditional multivariate normal sampling. Each mode is defined by a CE x CE covariance matrix (where C is the number of channels and E is the number of embeddings). At each time point, the current sample is drawn conditioned on the previous E-1 samples.

Parameters:

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). The row/column ordering is assumed to be blocks of E x E matrices (i.e. channel-major ordering).
n_embeddings (int, optional) – Number of time-delay embeddings.
rho (float, optional) – Regularisation parameter for inverting the covariance.

true_tde_covs#

n_embeddings = 1#

rho = 0.1#

n_channels#

n_modes#

simulate_data(state_time_course)[source]#

Simulate time series data.

For each mode, generates a full-length time series from the mode’s TDE covariance, then masks it by the state time course.

Parameters:: state_time_course (np.ndarray) – One-hot encoded state time course. Shape: (n_samples, n_modes).
Returns:: data – Simulated data. Shape: (n_samples, n_channels).
Return type:: np.ndarray

class osl_dynamics.simulation.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#

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

n_states#

n_channels#

hmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

Return type:: numpy.ndarray

class osl_dynamics.simulation.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#

n_states#

n_channels#

hmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

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

n_subjects = 1#

n_groups = 1#

n_subjects_per_group = 1#

sampling_frequency = 100#

snr = 4#

stay_prob = 0.98#

true_freqs#

hmm#

property time_series#

(n_subjects, n_samples, n_channels).

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

property state_time_course#

(n_subjects, n_samples, n_modes + 1).

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

class osl_dynamics.simulation.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#

n_subjects = 1#

obs_mod#

n_modes#

n_channels#

hmm#

property time_series#

(n_subjects, n_samples, n_channels).

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

property state_time_course#

(n_subjects, n_samples, n_modes).

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

class osl_dynamics.simulation.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#

n_states#

n_channels#

alpha_hmm#

beta_hmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

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

n_states#

n_channels#

n_bottom_level_hmms#

bottom_level_hmms#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

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

n_states#

n_channels#

n_sessions#

state_time_course = []#

hmm = []#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

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

n_states#

n_channels#

hmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

Return type:: numpy.ndarray

class osl_dynamics.simulation.HSMM(gamma_shape, gamma_scale, off_diagonal_trans_prob=None, full_trans_prob=None, state_vectors=None, n_states=None)[source]#

HSMM base class.

Contains the probability distribution function for sampling state lifetimes. Uses a Gamma distribution for the probability distribution function.

Parameters:

gamma_shape (float) – Shape parameter for the Gamma distribution of state lifetimes.
gamma_scale (float) – Scale parameter for the Gamma distribution of state lifetimes.
off_diagonal_trans_prob (np.ndarray, optional) – Transition probabilities for out of state transitions.
full_trans_prob (np.ndarray, optional) – A transition probability matrix, the diagonal of which will be ignored.
n_states (int, optional) – Number of states.
state_vectors (np.ndarray, optional) – Mode vectors define the activation of each components for a state. E.g. state_vectors=[[1,0,0],[0,1,0],[0,0,1]] are mutually exclusive states. state_vector.shape[0] must be more than n_states.

off_diagonal_trans_prob = None#

full_trans_prob = None#

gamma_shape#

gamma_scale#

construct_off_diagonal_trans_prob()[source]#

Return type:: None

generate_states(n_samples)[source]#

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

class osl_dynamics.simulation.HSMM_MVN(n_samples, gamma_shape, gamma_scale, off_diagonal_trans_prob=None, full_trans_prob=None, means=None, covariances=None, n_states=None, n_modes=None, n_channels=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Hidden Semi-Markov Model Simulation.

We sample the state using a transition probability matrix with zero probability for self-transitions. The lifetime of each state is sampled from a Gamma distribution.

Parameters:

n_samples (int) – Number of samples to draw from the model.
gamma_shape (float) – Shape parameter for the Gamma distribution of state lifetimes.
gamma_scale (float) – Scale parameter for the Gamma distribution of state lifetimes.
off_diagonal_trans_prob (np.ndarray, optional) – Transition probabilities for out of state transitions.
full_trans_prob (np.ndarray, optional) – A transition probability matrix, the diagonal of which will be ignored.
means (np.ndarray or str, optional) – Mean vector for each state, shape should be (n_states, n_channels). Or 'zero' or 'random'.
covariances (numpy.ndarray or str, optional) – Covariance matrix for each state, shape should be (n_states, n_channels, n_channels). 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 in the observation model.
observation_error (float, optional) – Standard deviation of random noise to be added to the observations.
n_modes (Optional[int])

obs_mod#

n_states#

n_channels#

hsmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

Return type:: numpy.ndarray

standardize()[source]#

Return type:: None

class osl_dynamics.simulation.MixedHSMM_MVN(n_samples, gamma_shape, gamma_scale, mixed_state_vectors=None, mixed_mode_vectors=None, off_diagonal_trans_prob=None, full_trans_prob=None, means=None, covariances=None, n_channels=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Hidden Semi-Markov Model Simulation with a mixture of states at each time point.

Each mixture of states has it’s own row/column in the transition probability matrix. The lifetime of each state mixture is sampled from a Gamma distribution.

state_mixing_vectors is a 2D numpy array containing mixtures of the the states that can be simulated, e.g. with n_states=3 we could have state_mixing_vectors=[[0.5, 0.5, 0], [0.1, 0, 0.9]].

Parameters:

n_samples (int) – Number of samples to draw from the model.
gamma_shape (float) – Shape parameter for the Gamma distribution of state lifetimes.
gamma_scale (float) – Scale parameter for the Gamma distribution of state lifetimes.
mixed_state_vectors (np.ndarray, optional) – Vectors containing mixing factors for mixed states.
mixed_mode_vectors (np.ndarray, optional) – Vectors containing mixing factors for mixed states.
off_diagonal_trans_prob (np.ndarray, optional) – Transition probabilities for out of state transitions.
full_trans_prob (np.ndarray, optional) – A transition probability matrix, the diagonal of which will be ignored.
means (np.ndarray or str, optional) – Mean vector for each state, shape should be (n_states, n_channels). Or 'zero' or 'random'.
covariances (numpy.ndarray or str, optional) – Covariance matrix for each state, shape should be (n_states, n_channels, n_channels). Or 'random'.
n_channels (int, optional) – Number of channels in the observation model.
observation_error (float, optional) – Standard deviation of random noise to be added to the observations.

n_states#

n_mixed_states#

mixed_state_vectors = None#

obs_mod#

n_channels#

hsmm#

state_time_course#

time_series#

property n_modes: int#

Return type:: int

property mode_time_course: numpy.ndarray#

Return type:: numpy.ndarray

construct_state_vectors(n_states)[source]#

Parameters:: n_states (int)
Return type:: None

standardize()[source]#

Return type:: None

class osl_dynamics.simulation.MixedSine(n_modes, relative_activation, amplitudes, frequencies, sampling_frequency)[source]#

Simulates sinusoidal oscilations in mode time courses.

Parameters:

n_modes (int) – Number of modes.
relative_activation (np.ndarray or list) – Average value for each sine wave. Note, this might not be the mean value for each mode time course because there is a softmax operation. This argument can use use to change the relative values of each mode time course.
amplitudes (np.ndarray or list) – Amplitude of each sinusoid.
frequencies (np.ndarray or list) – Frequency of each sinusoid.
sampling_frequency (float) – Sampling frequency.

n_modes#

relative_activation#

amplitudes#

frequencies#

sampling_frequency#

generate_modes(n_samples)[source]#

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

class osl_dynamics.simulation.MixedSine_MVN(n_samples, relative_activation, amplitudes, frequencies, sampling_frequency, means, covariances, n_covariances_act=1, n_modes=None, n_channels=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulates sinusoidal alphas with a multivariable normal observation model.

Parameters:

n_samples (int) – Number of samples to draw from the model.
relative_activation (np.ndarray or list) – Average value for each sine wave. Note, this might not be the mean value for each mode time course because there is a softmax operation. This argument can use use to change the relative values of each mode time course. Shape must be (n_modes,).
amplitudes (np.ndarray or list) – Amplitude of each sinusoid. Shape must be (n_modes,).
frequencies (np.ndarray or list) – Frequency of each sinusoid. Shape must be (n_modes,).
sampling_frequency (float) – Sampling frequency.
means (np.ndarray or str) – Mean vector for each mode, shape should be (n_modes, n_channels). Either a numpy array or 'zero' or 'random'.
covariances (np.ndarray or str) – Covariance matrix for each mode, shape should be (n_modes, n_channels, n_channels). Either a numpy array or 'random'.
n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.
n_modes (int, optional) – Number of modes.
n_channels (int, optional) – Number of channels.
observation_error (float, optional) – Standard deviation of the error added to the generated data.

obs_mod#

n_modes#

n_channels#

sm#

mode_time_course#

time_series#

standardize()[source]#

Return type:: None

class osl_dynamics.simulation.MSess_MixedSine_MVN(n_samples, relative_activation, amplitudes, frequencies, sampling_frequency, session_means, session_covariances, n_covariances_act=1, n_modes=None, n_channels=None, n_sessions=None, embeddings_dim=None, spatial_embeddings_dim=None, embeddings_scale=None, n_groups=None, between_group_scale=None, observation_error=0.0)[source]#

Bases: osl_dynamics.simulation.base.Simulation

Simulates sinusoidal alphas with a multivariable normal observation model for each session.

Parameters:

n_samples (int) – Number of samples per session to draw from the model.
relative_activation (np.ndarray or list) – Average value for each sine wave. Note, this might not be the mean value for each mode time course because there is a softmax operation. This argument can use use to change the relative values of each mode time course. Shape must be (n_modes,).
amplitudes (np.ndarray or list) – Amplitude of each sinusoid. Shape must be (n_modes,).
frequencies (np.ndarray or list) – Frequency of each sinusoid. Shape must be (n_modes,).
sampling_frequency (float) – Sampling frequency.
session_means (np.ndarray or str) – Session mean vector for each mode, shape should be (n_sessions, n_modes, n_channels). Either a numpy array or 'zero' or 'random'.
session_covariances (np.ndarray or str) – Session covariance matrix for each mode, shape should be (n_sessions, n_modes, n_channels, n_channels). Either a numpy array or 'random'.
n_covariances_act (int, optional) – Number of iterations to add activations to covariance matrices.
n_modes (int, optional) – Number of modes.
n_channels (int, optional) – Number of channels.
n_sessions (int, optional) – Number of sessions.
embeddings_dim (int, optional) – Number of dimensions for embedding vectors.
spatial_embeddings_dim (int, optional) – Number of dimensions for spatial embedding vectors.
embeddings_scale (float, optional) – Scale of variability between session observation parameters.
n_groups (int, optional) – Number of groups when session means or covariances are 'random'.
between_group_scale (float, optional) – Scale of variability between groups.
observation_error (float, optional) – Standard deviation of the error added to the generated data.

obs_mod#

n_modes#

n_channels#

n_sessions#

mode_time_course = []#

sm = []#

time_series#

standardize()[source]#

Return type:: None