Skip to content

Kinematic Kalman Filter

ML Features kalman adaptive kinematic momentum lag-reduction

A 2D Kalman filter tracking price and velocity to reduce lag in trends.

Visual Example

Kinematic Kalman Filter — annotated preview mapping to core implementation

Synthetic ideal per library logic. Generated 2026-07-01 IST via docs/generate_all_previews.py (reproducible; maps to core Next<T> implementation).

Description

A 2D Kalman filter tracking price and velocity to reduce lag in trends.

Optimized for trend-following strategies where lag reduction is critical. q_pos controls price sensitivity, q_vel controls momentum sensitivity, and r controls overall smoothing.

Research-oriented feature for ML pipelines; validated for batch ↔ streaming parity.

The Kinematic Kalman Filter extends the 1D model by incorporating a velocity state. This allows the filter to 'anticipate' the next price based on current momentum, providing a zero-lag-like response during strong trends while maintaining smoothness via its optimal error-correction logic.

Typical applications:

  • Fade extremes in ranges; trade with trend on recoveries from oversold/overbought
  • Use divergences as early warning — confirm with structure or volume
  • Parameter default 0.001 — shorten for sensitivity, lengthen for stability
  • Drop into build_feature_matrix() for ML research

QuantWave implements this via the universal Next<T> trait — bit-identical across Rust streaming, Python streaming, and Polars .ta() batch plugins.

Formula / Specification

Implementation (quantwave-core/src/indicators/kinematic_kalman.rs):

[ \hat{x}{k|k-1} = \Phi \hat{x} ] [ P_{k|k-1} = \Phi P_{k-1|k-1} \Phi^T + Q ] [ K_k = P_{k|k-1} H^T (H P_{k|k-1} H^T + R)^{-1} ] [ \hat{x}{k|k} = \hat{x}} + K_k (z_k - H \hat{x{k|k-1}) ] [ P ]} = (I - K_k H) P_{k|k-1

Gold-standard parity vectors: quantwave-core/tests/gold_standard/kinematic_kalman.json.

Parameters

Parameter Default Description
q_pos 0.001 Process noise for position (price)
q_vel 0.0001 Process noise for velocity (momentum)
r 0.1 Measurement noise (smoothing strength)

Usage Examples

Streaming (Rust)

use quantwave_core::indicators::KINEMATIC_KALMAN;
use quantwave_core::traits::Next;

let mut ind = KINEMATIC_KALMAN::new(0.001);
for price in &prices {
    let value = ind.next(price);
}

Streaming (Python)

from quantwave import KINEMATIC_KALMAN

ind = KINEMATIC_KALMAN(0.001)
for price in prices:
    value = ind.next(price)

Polars Batch (Python)

import polars as pl
import quantwave as qw

def apply_kinematic_kalman_filter(series: pl.Series) -> pl.Series:
    ind = qw.KINEMATIC_KALMAN(0.001)
    return pl.Series([ind.next(float(v)) for v in series.to_list()])

df = (
    pl.read_csv('ohlcv.csv')
    .lazy()
    .with_columns(
        pl.col("close").map_batches(apply_kinematic_kalman_filter, return_dtype=pl.Float64).alias("kinematic_kalman_filter")
    )
    .collect()
)

All surfaces are bit-identical via the single Next<T> implementation and proptests.

Edge Cases & Limitations

  • Warm-up: first 0.001 bars may return NaN or partial state per implementation.
  • Parameter sensitivity: smaller periods increase noise; larger periods increase lag.
  • Sudden gaps or bad ticks can distort rolling windows — consider pre-filtering.
  • Single-series indicators ignore volume unless otherwise documented.
  • Validated via proptests against gold-standard vectors where available.
  • No look-ahead bias; streaming and Polars batch paths are bit-identical.

Boundary Behavior

Condition Behavior
Warm-up Leading bars return NaN until warmup_bars is satisfied.
period > len When period exceeds series length, output is all NaN.
NaN inputs NaN in input propagates to output (NaN out).
Invalid params Non-positive period or missing required params raise ValueError.
Empty data Empty input returns an empty result series.

Sources & References

Primary Source: https://www.cs.unc.edu/~welch/kalman/media/pdf/Kalman1960.pdf

Implementation: quantwave-core/src/indicators/kinematic_kalman.rs (KINEMATIC_KALMAN / KINEMATIC_KALMAN_METADATA). Parity: quantwave-core/tests/gold_standard/kinematic_kalman.json

Provenance: Standards bulk upgrade 2026-07-01 IST — see docs/DOCUMENTATION_STANDARDS.md.