Metadata-Version: 2.4
Name: viking_kalman
Version: 0.1.0
Summary: Viking: Variational bayesIan variance tracKING. A Python package for variational inference in state-space models.
Home-page: https://github.com/EDF-Lab/viking_kalman
Author: Louis Viennot, Ismaïl El Azzaoui, Antoine Gourbilleau, Athir Hamadieh, Yann Allioux
License: LGPL-3.0-or-later
Project-URL: Bug Tracker, https://github.com/EDF-Lab/viking_kalman/issues
Project-URL: Source Code, https://github.com/EDF-Lab/viking_kalman
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: pandas
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# viking_kalman
[![PyPI version](https://badge.fury.io/py/viking-kalman.svg)](https://badge.fury.io/py/viking-kalman)
[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)

**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:
```bash
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
```python
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](https://cran.r-project.org/web/packages/viking/index.html)
*   **PhD Thesis**: DE VILMAREST, Joseph. *State-space models for time series forecasting. Application to the electricity markets*. 2022. PhD Thesis. Sorbonne University. [Available here](https://theses.hal.science/tel-03716104/)
*   **Research Paper (VIKING)**: J. de Vilmarest, O. Wintenberger (2021), *Viking: Variational Bayesian Variance Tracking*. [arXiv:2104.10777](https://arxiv.org/abs/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.
