viking_kalman

Viking: Variational bayesIan variance tracKING. A Python package for variational inference in state-space models.

This project is a complete Python port of the R package viking, originally developed by Joseph de Vilmarest as part of his PhD thesis. It brings these powerful statistical algorithms natively to the Python ecosystem.

Main Features

• State-Space Models: A high-level StateSpaceModel scikit-learn-style API to build, update, and visualize models.
• VIKING Algorithm: A state-of-the-art variational Bayesian approach to track the evolution of state and observation noise variances.
• Kalman Filtering & Smoothing: Classic, robust implementations for accurate state estimation.
• Hyperparameter Estimation:
  • expectation_maximization: Uses the EM algorithm to estimate constant noise variances.
  • iterative_grid_search: An optimized grid search to find hyperparameters by maximizing log-likelihood.
• Built-in Diagnostics: An integrated .plot() method to instantly analyze model behavior (bias, RMSE, state evolution, and Q-Q plots).

Installation

The package is available on PyPI. Install it using pip:

pip install viking_kalman

🛠️ Build & Distribution Guide

This project uses a dual-layer architecture to ensure both blazing-fast computations and maximum cross-platform compatibility.

1. Automated Binary Distribution (Wheels)

Pre-compiled, high-performance C-extension wheels are automatically provided for:

• Windows (AMD64)
• macOS (Apple Silicon & Intel)
• Linux (Manylinux)

Standard users running pip install viking-kalman will automatically receive the high-performance C-extension. You do not need a C compiler, Visual Studio, or GSL installed on your machine.

2. Graceful Pure-Python Fallback

If you install from source on an unsupported architecture or restrict environments (e.g., standard corporate setups without admin rights), the installation will still succeed!

Our installer includes a graceful safety net:

1. It attempts to compile the C-extensions locally.
2. If the compilation fails (due to a missing compiler or libraries), it catches the error and seamlessly installs a 100% functional, pure-Python implementation.
3. The package works perfectly, though grid search optimizations will run slightly slower.

Quick Start

import numpy as np
from viking_kalman import StateSpaceModel

# 1. Simulate data
np.random.seed(1)
n, d = 100, 5
Q = np.diag([0, 0, 0.25, 0.25, 0.25]) # Process noise covariance
sig = 1 # Measurement noise standard deviation
X = np.hstack([np.random.randn(n, d - 1), np.ones((n, 1))])

theta = np.random.randn(d, 1)
theta_arr = np.zeros((n, d))
for t in range(n):
    theta_arr[t, :] = theta.flatten()
    theta = theta + np.random.multivariate_normal(np.zeros(d), Q).reshape((d, 1))
    
y = np.sum(X * theta_arr, axis=1) + np.random.normal(0, sig, size=n)

# 2. Build the model and visualize diagnostics
ssm = StateSpaceModel(X, y, kalman_params={'Q': Q, 'sig': sig})
ssm.plot()

📚 API Reference

Below are the primary functions and classes exposed by the package:

• StateSpaceModel(X, y, ...): Initializes a state-space model object.
  • .predict(newX, ...): Generates predictions in online or offline modes.
  • .plot(...): Renders analysis plots (bias, RMSE, state evolution, Q-Q plot of residuals).
• viking(...): Applies the core VIKING algorithm, generalizing the Kalman filter to handle variance uncertainty.
• iterative_grid_search(...): Estimates hyperparameters via an optimized iterative grid search.
• expectation_maximization(...): Estimates hyperparameters via the Expectation-Maximization (EM) algorithm.
• kalman_filtering(...): Computes the filtered estimation of parameters theta and P.
• kalman_smoothing(...): Computes the smoothed estimation using the full dataset.
• loglik(...): Computes the model log-likelihood for a given set of hyperparameters.

🎓 Acknowledgements & Origin

This package is a reimplementation and extension in Python of the original work by Joseph de Vilmarest.

• Original R Package: viking on CRAN
• PhD Thesis: DE VILMAREST, Joseph. State-space models for time series forecasting. Application to the electricity markets. 2022. PhD Thesis. Sorbonne University. Available here
• Research Paper (VIKING): J. de Vilmarest, O. Wintenberger (2021), Viking: Variational Bayesian Variance Tracking. arXiv:2104.10777

The development of this Python port was supervised by Yann Allioux.

👥 Authors & Contributors

• Original Author (R Package & Theory): Joseph de Vilmarest
• Project Lead, Packaging, and Supervisor: Yann Allioux
• Algorithm Porting (v0.0.1): Louis Viennot, Ismaïl El Azzaoui, Antoine Gourbilleau (CentraleSupélec student project led by Yann Allioux, thanks to the CentraleSupélec Academic Supervisors Céline Hudelot and Wassila Ouerdane)
• Performance Optimization & C-Extensions (v0.0.2): Athir Hamadieh (6-month internship tutored by Yann Allioux)
• Open Source Release, CI/CD, & Dynamic Compilation (v0.1.0): Yann Allioux

📄 License

This project is distributed under the GNU Lesser General Public License v3 (LGPLv3), inherited from the original R package. The full license text is available in the LICENSE file in the repository.