Skip to content

Commit 9bb3b90

Browse files
Kleyt0nKleyt0n
committed
minor fixes and docs update
1 parent 31feef4 commit 9bb3b90

8 files changed

Lines changed: 479 additions & 32 deletions

File tree

‎docs/api/index.rst‎

Lines changed: 32 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,38 @@ API Reference
33

44
Complete reference for all public classes and functions in dynaris.
55

6-
+------------------+-------------------------------------------------------------+
7-
| Module | Description |
8-
+==================+=============================================================+
9-
| :doc:`ssm` | Unified ``SSM`` class with automatic filter selection |
10-
+------------------+-------------------------------------------------------------+
11-
| :doc:`dlm` | High-level ``DLM`` class (fit, smooth, forecast, plot) |
12-
+------------------+-------------------------------------------------------------+
13-
| :doc:`components` | Six composable building blocks (``LocalLevel``, etc.) |
14-
+------------------+-------------------------------------------------------------+
15-
| :doc:`models` | Built-in nonlinear models (stochastic vol, tracking, etc.) |
16-
+------------------+-------------------------------------------------------------+
17-
| :doc:`factor` | Dynamic Factor Models (DFMModel, loadings, rotation) |
18-
+------------------+-------------------------------------------------------------+
19-
| :doc:`core` | ``StateSpaceModel``, ``GaussianState``, result containers |
20-
+------------------+-------------------------------------------------------------+
21-
| :doc:`filters` | Kalman, EKF, UKF, and Particle filters |
22-
+------------------+-------------------------------------------------------------+
23-
| :doc:`switching` | Markov-switching models, Hamilton filter, Kim smoother |
24-
+------------------+-------------------------------------------------------------+
25-
| :doc:`smoothers` | Rauch-Tung-Striebel backward smoother |
26-
+------------------+-------------------------------------------------------------+
27-
| :doc:`estimation` | MLE, EM algorithm, diagnostics, model selection |
28-
+------------------+-------------------------------------------------------------+
29-
| :doc:`forecast` | Multi-step forecasting and batch processing |
30-
+------------------+-------------------------------------------------------------+
31-
| :doc:`plotting` | Visualization functions for all plot kinds |
32-
+------------------+-------------------------------------------------------------+
33-
| :doc:`datasets` | Built-in dataset loaders |
34-
+------------------+-------------------------------------------------------------+
6+
.. list-table::
7+
:header-rows: 1
8+
:widths: 20 80
9+
10+
* - Module
11+
- Description
12+
* - :doc:`ssm`
13+
- Unified ``SSM`` class with automatic filter selection
14+
* - :doc:`dlm`
15+
- High-level ``DLM`` class (fit, smooth, forecast, plot)
16+
* - :doc:`components`
17+
- Six composable building blocks (``LocalLevel``, etc.)
18+
* - :doc:`models`
19+
- Built-in nonlinear models (stochastic vol, tracking, etc.)
20+
* - :doc:`factor`
21+
- Dynamic Factor Models (DFMModel, loadings, rotation)
22+
* - :doc:`core`
23+
- ``StateSpaceModel``, ``GaussianState``, result containers
24+
* - :doc:`filters`
25+
- Kalman, EKF, UKF, and Particle filters
26+
* - :doc:`switching`
27+
- Markov-switching models, Hamilton filter, Kim smoother
28+
* - :doc:`smoothers`
29+
- Rauch-Tung-Striebel backward smoother
30+
* - :doc:`estimation`
31+
- MLE, EM, Bayesian, diagnostics, model selection
32+
* - :doc:`forecast`
33+
- Multi-step forecasting and batch processing
34+
* - :doc:`plotting`
35+
- Visualization functions for all plot kinds
36+
* - :doc:`datasets`
37+
- Built-in dataset loaders
3538

3639
.. toctree::
3740
:maxdepth: 2

‎docs/comparison.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
Comparison Guide
2+
================
3+
4+
How dynaris compares to other state-space / Kalman filter libraries.
5+
6+
.. list-table::
7+
:header-rows: 1
8+
:widths: 20 15 15 15 15 15
9+
10+
* - Feature
11+
- **dynaris**
12+
- dynamax
13+
- statsmodels
14+
- filterpy
15+
- pykalman
16+
* - Backend
17+
- JAX
18+
- JAX
19+
- NumPy/Cython
20+
- NumPy
21+
- NumPy
22+
* - GPU/TPU
23+
- Yes
24+
- Yes
25+
- No
26+
- No
27+
- No
28+
* - JIT compilation
29+
- Yes
30+
- Yes
31+
- No
32+
- No
33+
- No
34+
* - Autodiff (gradients)
35+
- Yes (full)
36+
- Yes
37+
- Limited
38+
- No
39+
- No
40+
* - Kalman filter
41+
- Yes
42+
- Yes
43+
- Yes
44+
- Yes
45+
- Yes
46+
* - RTS smoother
47+
- Yes
48+
- Yes
49+
- Yes
50+
- Yes
51+
- Yes
52+
* - Extended KF
53+
- Yes
54+
- Yes
55+
- No
56+
- Yes
57+
- No
58+
* - Unscented KF
59+
- Yes
60+
- Yes
61+
- No
62+
- Yes
63+
- No
64+
* - Particle filter
65+
- Yes
66+
- Yes (via Blackjax)
67+
- No
68+
- Yes
69+
- No
70+
* - Hamilton filter
71+
- Yes
72+
- Yes
73+
- Yes
74+
- No
75+
- No
76+
* - DLM components
77+
- Yes (6 types)
78+
- No
79+
- Yes (via UnobservedComponents)
80+
- No
81+
- No
82+
* - Model composition (+)
83+
- Yes
84+
- No
85+
- No
86+
- No
87+
- No
88+
* - Dynamic Factor Models
89+
- Yes
90+
- No
91+
- Yes
92+
- No
93+
- No
94+
* - Bayesian (MCMC)
95+
- Yes (NumPyro)
96+
- No (manual)
97+
- No
98+
- No
99+
- No
100+
* - MLE estimation
101+
- Yes (JAX grad)
102+
- Yes
103+
- Yes (scipy)
104+
- No
105+
- Yes (EM only)
106+
* - EM estimation
107+
- Yes
108+
- Yes
109+
- No
110+
- No
111+
- Yes
112+
* - Batch (vmap)
113+
- Yes
114+
- Yes
115+
- No
116+
- No
117+
- No
118+
* - Missing data
119+
- Yes (NaN)
120+
- Yes
121+
- Yes
122+
- Manual
123+
- No
124+
* - Forecast
125+
- Yes
126+
- Yes
127+
- Yes
128+
- Manual
129+
- No
130+
* - Plotting
131+
- Yes (matplotlib)
132+
- No
133+
- Yes
134+
- No
135+
- No
136+
* - pandas integration
137+
- Yes
138+
- No
139+
- Yes
140+
- No
141+
- No
142+
143+
When to use dynaris
144+
-------------------
145+
146+
- You want **composable DLM components** (trend + seasonal + regression via ``+``)
147+
- You need **gradient-based optimization** through the filter (MLE, Bayesian)
148+
- You want **GPU/TPU acceleration** for large-scale or batch inference
149+
- You need **nonlinear filters** (EKF, UKF, particle) alongside linear DLMs
150+
- You want **regime-switching models** with the Hamilton filter
151+
- You need **Bayesian estimation** with NUTS/HMC via NumPyro
152+
153+
When to use alternatives
154+
------------------------
155+
156+
- **dynamax**: If you want a general-purpose JAX state-space library with
157+
more model types (HMMs, LDS) and variational inference.
158+
- **statsmodels**: If you need a mature, well-tested library with extensive
159+
econometric functionality and don't need GPU/autodiff.
160+
- **filterpy**: If you need a lightweight, NumPy-only library for real-time
161+
tracking applications (robotics, navigation).
162+
- **pykalman**: If you need a simple EM-based Kalman filter with minimal
163+
dependencies and don't need nonlinear filters or GPU.

‎docs/examples/index.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,16 @@ Economics & Finance
2828
US quarterly GDP growth. Local level plus AR(2) to capture business
2929
cycle dynamics.
3030

31+
**Stochastic Volatility** --- ``stochastic_volatility.py``
32+
Particle filter on a stochastic volatility model for financial returns.
33+
Compares EKF, UKF, and particle filter on latent log-volatility recovery
34+
using the Kim-Shephard-Chib linearization.
35+
36+
**Regime Switching** --- ``regime_switching.py``
37+
Hamilton filter and Kim smoother detecting volatility regimes. Simulates
38+
a 2-regime process (calm vs volatile) and tracks filtered and smoothed
39+
regime probabilities over time.
40+
3141
Natural Sciences
3242
----------------
3343

@@ -43,6 +53,41 @@ Natural Sciences
4353
Annual temperature anomaly (1880--2023). Linear trend detection in climate
4454
data.
4555

56+
Nonlinear Filtering
57+
-------------------
58+
59+
**Lorenz Attractor Tracking** --- ``lorenz_tracking.py``
60+
Compares EKF, UKF, and particle filter on the chaotic Lorenz system.
61+
Simulates a 3D trajectory with partial (2D) noisy observations and
62+
tracks the full state. Plots per-component tracking accuracy.
63+
64+
**Bearings-Only Tracking** --- ``bearings_tracking.py``
65+
EKF on a 2D target tracking problem with nonlinear bearing-angle
66+
observations. Demonstrates the classic radar/sonar tracking scenario
67+
where the sensor measures only the angle to the target.
68+
69+
Bayesian Estimation
70+
-------------------
71+
72+
**Bayesian Airline Passengers** --- ``bayesian_nile.py``
73+
Full Bayesian inference for a trend + seasonal model on log-transformed
74+
airline data using NumPyro's NUTS sampler. Compares posterior with MLE,
75+
generates posterior predictive forecasts with credible intervals, and
76+
runs prior predictive checks.
77+
78+
Dynamic Factor Models
79+
---------------------
80+
81+
**Macroeconomic Nowcasting** --- ``macro_nowcasting.py``
82+
Extracts 2 latent factors from a panel of 10 simulated macroeconomic
83+
indicators via DFM-EM. Plots factor time series, loading matrix heatmap,
84+
explained variance, and multivariate forecasts.
85+
86+
**Multi-Sensor Fusion** --- ``sensor_fusion.py``
87+
Fuses 5 noisy temperature sensors into a single optimal estimate using
88+
a 1-factor DFM. Demonstrates how the DFM weights sensors by their
89+
reliability (inverse noise variance).
90+
4691
Advanced
4792
--------
4893

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ through ``jax.vmap``.
8787
:caption: Theory
8888

8989
math
90+
comparison
9091

9192
.. toctree::
9293
:maxdepth: 1

0 commit comments

Comments
 (0)