make_regime_switching_var

kooplearn.datasets.make_regime_switching_var(X0, phi1, phi2, transition, n_steps=100, dt=1.0, noise=0.0, random_state=None)[source]

Generate a trajectory from a regime-switching vector autoregressive (VAR) process.

This model alternates between two linear dynamical regimes according to a Markov transition matrix. At each step, the system evolves according to one of two dynamics matrices phi1 or phi2, with optional Gaussian noise.

Mathematically, the system evolves as:

\[x_{t+1} = \Phi_{s_t} x_t + \epsilon_t, \quad \epsilon_t \sim \mathcal{N}(0, \sigma^2 I)\]

where s_t is the active regime (0 or 1), evolving according to a 2x2 Markov transition matrix P such that

\[P_{ij} = \mathbb{P}(s_{t+1} = j \mid s_t = i).\]
Parameters:

  • X0 (array-like of shape (n_features,)) – Initial state of the system.

  • phi1 (ndarray of shape (n_features, n_features)) – Dynamics matrix for regime 0.

  • phi2 (ndarray of shape (n_features, n_features)) – Dynamics matrix for regime 1.

  • transition (ndarray of shape (2, 2)) – Row-stochastic Markov transition matrix defining the probabilities of switching between regimes. transition[i, j] gives the probability of transitioning from regime i to j.

  • n_steps (int, default 100) – Number of discrete time steps to simulate.

  • dt (float, default 1.0) – Time step size for discrete simulation. Added as metadata in the output.

  • noise (float, default 0.0) – Standard deviation of Gaussian noise added at each step.

  • random_state (int, RandomState instance or None, default None) – Controls the random number generation for the noise. Pass an int for reproducible output across multiple function calls.

Returns:

df – Generated trajectory with columns ['x0', 'x1', ..., 'x{n_features-1}'] and n_steps + 1 samples. Has a MultiIndex with levels ['step', 'time'].

The following metadata are stored in df.attrs:

  • 'generator': 'make_regime_switching_var';

  • 'X0': initial state;

  • 'params': dictionary with all model parameters;

  • 'regimes': integer array of active regimes over time.

Return type:

pandas.DataFrame

Examples

>>> import numpy as np
>>> from kooplearn.datasets import make_regime_switching_var
>>> phi1 = np.array([[0.9, 0.1], [0.0, 0.8]])
>>> phi2 = np.array([[0.5, -0.2], [0.3, 0.7]])
>>> transition = np.array([[0.95, 0.05], [0.1, 0.9]])
>>> X0 = np.zeros(2)
>>> df = make_regime_switching_var(X0, phi1, phi2, transition, n_steps=100, noise=0.01)