osl_dynamics.simulation.obs_mod#

Observation models for simulations.

Classes#

`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.
`MAR`	Class that generates data from a multivariate autoregressive (MAR) model.
`OscillatoryBursts`	Oscillatory burst observation model.
`Poisson`	Class that generates Poisson time series data.
`TDECovs`	Time-delay embedded covariance observation model.

Module Contents#

class osl_dynamics.simulation.obs_mod.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[source]#

observation_error = 0.0[source]#

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.obs_mod.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[source]#

corrs[source]#

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.obs_mod.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[source]#

observation_error = 0.0[source]#

embeddings_dim = None[source]#

spatial_embeddings_dim = None[source]#

embeddings_scale = None[source]#

n_groups = None[source]#

between_group_scale = None[source]#

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.obs_mod.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[source]#

covs[source]#

order[source]#

n_states[source]#

n_channels[source]#

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.obs_mod.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[source]#

n_channels[source]#

true_freqs[source]#

channel_activity[source]#

sampling_frequency = 100[source]#

snr = 4[source]#

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.obs_mod.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.obs_mod.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[source]#

n_embeddings = 1[source]#

rho = 0.1[source]#

n_channels[source]#

n_modes[source]#

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