osl_dynamics.models

Generative models.

This subpackage contains all the models implemented in osl-dynamics. Each model module (e.g. hmm.py, dynemo.py) defines a Config dataclass and a Model class.

Code structure

The code is organised into three layers:

1. Base layer (mod_base.py)

• BaseModelConfig — Common configuration shared by all models (learning rate, batch size, number of modes/states, etc.).

• ModelBase — Abstract base class that wraps a Keras model. Provides the training loop (fit), initialisation, checkpointing, and attribute delegation to the underlying Keras model. Subclasses must implement build_model().

2. Inference layer (inf_mod_base.py)

Two parallel branches extend ModelBase for different inference paradigms:

• Variational inference — For models with continuous latent variables (mode mixing coefficients inferred by an RNN). Adds KL annealing and alpha temperature handling.

  • VariationalInferenceModelConfig

  • VariationalInferenceModelBase

  • Used by: DyNeMo, M-DyNeMo, SC-DyNeMo, DIVE, DyNeStE.

• Markov state inference — For models with discrete hidden states (state sequence inferred by the Baum-Welch algorithm). Adds transition probability learning and state initialisation.

  • MarkovStateInferenceModelConfig

  • MarkovStateInferenceModelBase

  • Used by: HMM, HMM-Poisson, HIVE.

3. Full model

Each model combines a Config (via multiple inheritance from BaseModelConfig + an inference config) and a Model (inheriting from the appropriate inference base class):

Model	Inference	Description
hmm	Markov	Hidden Markov Model with MVN observations. See model description.
hmm_poi	Markov	HMM with Poisson observations.
hive	Markov	HMM with Integrated Variability Estimation (session-specific parameters via embeddings). See model description.
dynemo	Variational	Dynamic Network Modes (continuous mode mixing via RNN). See model description.
mdynemo	Variational	Multi-Dynamic Network Modes (separate dynamics for power and connectivity). See model description.
sc_dynemo	Variational	Single-Channel DyNeMo (extends DyNeMo).
dive	Variational	DyNeMo with Integrated Variability Estimation.
dyneste	Variational	Dynamic Network States (discrete states with non-Markovian temporal model). See model description.

Utilities (obs_mod.py)

Shared functions for getting/setting observation model parameters (means, covariances, embeddings, regularizers).

Tutorials

• HMM Training

• DyNeMo Training

• Getting Inferred Parameters

Python example scripts

• Simulation

• MEG analysis

• fMRI analysis

Attributes

models

Functions

load(dirname[, single_gpu])

Load model.

Package Contents

osl_dynamics.models.models

osl_dynamics.models.load(dirname, single_gpu=True)

Load model.

Parameters:

• dirname (str) – Path to directory where the config.yml and weights are stored.

• single_gpu (bool, optional) – Should we compile the model on a single GPU?

Returns:

model – Model object.

Return type:

osl-dynamics model