QuadraticKalman.jl

A Julia package implementing Kalman filtering and smoothing for state-space models with quadratic measurement equations, based on the methodology developed in Monfort et. al. (2013, Journal of Econometrics).

The package implements filtering and smoothing for the following state-space model with Gaussian noise:

State equation:

\(X_{t} = \mu + \Phi X_{t-1} + \Omega \epsilon_t\), where \(\epsilon_t \sim \mathcal{N}(0, I)\)

Measurement equation:

\(Y_t = A + B X_t + \alpha Y_{t-1} + \sum_{i=1}^M X_t^\prime C_i X_t + D \eta_t\), where \(\eta_t \sim \mathcal{N}(0, I)\)

📖 Documentation

👉 Read the Docs

Check out the latest documentation for installation, API reference, and usage examples.

Installation

using Pkg
Pkg.add("QuadraticKalman")

Quick Start

| code-fold: false
using QuadraticKalman, Random, Plots, LinearAlgebra
Random.seed!(2314)

# Define model parameters
N = 2  # Number of states
M = 2  # Number of measurements

# Generate stable state transition parameters
μ = [0.1, 0.2]                 # N x 1 vector
Φ = [0.5 0.1; 0.1 0.3]        # N x N matrix
Σ = [0.6 0.15; 0.15 0.4]    # N x N matrix
Ω = cholesky(Σ).L     

# Generate measurement parameters
A = [0.0, 0.0]                  # M x 1 vector
B = [1.0 0.0; 0.0 1.0]          # M x N matrix
C = [[0.2 0.1; 0.1 0.0],        # M x 1 vector of N x N matrices
     [0.0 0.1; 0.1 0.2]]    
V = [0.2 0.0; 0.0 0.2]          # M x M matrix
D = cholesky(V).L
α = zeros(M, M)             # M x M matrix

# Simulate data
T = 100
X = zeros(N, T)
Y = zeros(M, T)
X[:, 1] = randn(N)
for t in 2:T
    X[:, t] = μ + Φ * X[:, t-1] + Ω * randn(N)
    Y[:, t] = A + B * X[:, t] + α * Y[:, t-1] + D * randn(M)
    for i in 1:M
        Y[i, t] += X[:, t]' * C[i] * X[:, t]
    end
end

# Create model and run filter/smoother
model = QKModel(N, M, μ, Φ, Ω, A, B, C, D, α)
data = QKData(Y)
results_filter = qkf_filter(data, model)
results_smoother = qkf_smoother(results_filter, model)
 


# Visualize smoothed states
p = plot(kalman_smoother_truth_plot(X, results_smoother))
savefig(p, "smoother_example.png")  # Save plot for README


# Parameter estimation example
params = model_to_params(model)
nll(p) = qkf_negloglik(p, data, N, M)
grad = ForwardDiff.gradient(nll, params)

Quadratic Kalman Smoother Results

Features

• Kalman filtering and smoothing for quadratic state-space models.
• Extends original implementation by allowing for autoregressive measurement equations.
• Gradiant and hessian of negative log-likelihood computed using automatic differentiation using ForwardDiff.jl.
• Visualization tools for filtered and smoothed states.
• Efficient parameter-model conversion for optimization.
• Automatically reparametrizes model parameters to ensure positive-definiteness of covariance matrices in an unconstrained parameter space.
• 8.8x faster than R code in the same example.
• Numerically stable implementation.
• TODO: Add support for state-dependent measurement noise.

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.