DynaBayes

Dynamic Bayesian Inference for Coupled Phase Oscillators

DynaBayes is a Python package for simulation and time-evolving Bayesian inference of parameters in networks of coupled phase oscillators. The package provides a compact interface for a phase model containing direct phase terms and phase-difference coupling, together with posterior uncertainty and noise-covariance diagnostics.

---

Model formulation

The current model is

$$\frac{d\phi_i}{dt} = \omega_i(t) + \sum_{j=1}^{N} A_{ij}(t)\sin(\phi_j) + \sum_{j=1}^{N} B_{ij}(t)\sin(\phi_j - \phi_i) + \xi_i(t)$$

with stochastic terms described by

$$\langle \xi_i(t)\xi_j(t') \rangle = E_{ij}\,\delta(t-t')$$

Here:

• phi_i is the phase of oscillator i;
• omega_i(t) is its time-dependent intrinsic frequency;
• A_ij(t) multiplies the direct phase term sin(phi_j);
• B_ij(t) multiplies the phase-difference term sin(phi_j - phi_i);
• E is the inferred noise covariance matrix.

Because

$$B_{ii}\sin(\phi_i-\phi_i) = 0$$

the diagonal B_ii terms are structural zeros. They are retained in the historical output layout for clarity and compatibility, but they are not included in the inverse problem.

---

Methodology and validation

DynaBayes is an independent Python implementation of the time-evolving dynamical Bayesian inference methodology described in:

Stankovski, T., Ticcinelli, V., McClintock, P. V. E. & Stefanovska, A. (2014). A tutorial on time-evolving dynamical Bayesian inference. European Physical Journal Special Topics, 222, 2467–2485. https://doi.org/10.1140/epjst/e2014-02286-7

The sequential inference implementation uses midpoint discretization, iterative estimation of the full noise covariance matrix, a fixed prior during the internal parameter/noise iteration, and posterior-to-prior covariance propagation between consecutive non-overlapping windows.

The numerical behaviour of the implementation has been cross-validated against the independently developed MODA reference software and against synthetic systems with known time-varying parameters. MODA source code is not incorporated into DynaBayes and MODA is not a package dependency.

Automated regression tests verify parameter tracking, passage of a coupling coefficient through zero, noise-covariance recovery, structural zeros, convergence, and public-API behaviour.

---

Installation

Install the released package from PyPI:

pip install dynabayes

For development from GitHub:

git clone https://github.com/p3dr0id/DynaBayes.git
cd DynaBayes
pip install -e .

To run the development test suite:

pip install -r requirements-dev.txt
pytest -q

---

Quick example

The example below uses the two-oscillator model associated with the tutorial benchmark, with a time-varying frequency and a time-varying direct phase coefficient.

import numpy as np
import dynabayes as db

# Time-dependent model parameters
omega = [
    lambda t: 2 - 0.5 * np.sin(2 * np.pi * 0.00151 * t),
    db.const(4.53),
]

A = [
    [
        db.const(0.8),
        lambda t: 0.8 - 0.3 * np.sin(2 * np.pi * 0.0012 * t),
    ],
    [db.const(0.0), db.const(0.6)],
]

B = [
    [db.const(0.0), db.const(0.0)],
    [db.const(0.0), db.const(0.0)],
]

# Simulate synthetic phase data
phi, true_funcs, t = db.simulate_model(
    omega,
    A,
    B,
    E=[0.03, 0.01],
    t_max=2000,
    dt=0.01,
)

# Sequential dynamic Bayesian inference
result = db.run_inference(
    phi,
    dt=0.01,
    t=t,
    window_seconds=40.0,
    pr=0.20,
)

# Parameter evolution with posterior uncertainty
db.plot_parameters(
    result,
    true_funcs=true_funcs,
    uncertainty="95",
)

# Statistical summary across all windows
summary = db.show_summary(
    result,
    true_funcs=true_funcs,
)

# Inferred noise covariance and normalized cross-noise correlation
db.plot_noise(result)

The returned InferenceResult contains, among other fields:

result.params
result.time
result.sigma
result.covariance
result.E
result.iterations
result.criterion
result.pr
result.p_internal

For a window duration T_w, the propagation parameter used internally is

$$p_{\mathrm{internal}} = T_w p_r$$

For example, window_seconds=40 and pr=0.20 correspond to

$$p_{\mathrm{internal}} = 8$$

---

Inference from external phase data

If phase time series have already been extracted from empirical signals, they can be supplied directly:

# phi shape: (n_oscillators, n_time_points)
result = db.run_inference(
    phi,
    dt=0.1,
    t=your_time_vector,
    window_seconds=40.0,
    pr=0.20,
)

db.plot_parameters(result, uncertainty="sd")
db.plot_noise(result)
summary = db.show_summary(result)

Sequential posterior propagation currently uses consecutive non-overlapping windows. This avoids repeatedly propagating information from strongly overlapping observations as though those observations were independent new data.

---

Backward compatibility

The previous two-value unpacking remains temporarily available:

params, centers = db.run_inference(...)

The old pw argument is accepted as a deprecated alias for pr and emits a DeprecationWarning.

The old E_true inference argument is also accepted temporarily for compatibility, but it is ignored because the full noise covariance matrix is now inferred internally.

New code should use the InferenceResult interface.

---

Networks with 3+ oscillators

The inference code is written for a general number of phase oscillators. For each equation, the active basis contains

$$1,\qquad \sin(\phi_j),\qquad \sin(\phi_j-\phi_i),\quad j\ne i$$

The package preserves the full historical [omega_i, A_i1, ..., A_iN, B_i1, ..., B_iN] output layout, explicitly marking B_ii as structural zeros.

---

Development and continuous integration

Tests are executed automatically through GitHub Actions on supported development Python versions. The suite contains both API-level regression tests and independent synthetic scientific benchmarks.

Before merging changes to the inference core, all CI checks should pass.

---

License

MIT License.

The MIT license covers DynaBayes source code. Scientific methods implemented by the package should be cited through their original methodological references.