Diagnostics

NIS and NEES consistency checks.

A consistent filter's normalized errors follow chi-squared distributions: the NEES e' P^-1 e (estimation error e against its covariance P) with n degrees of freedom, and the NIS (FilterResult.nis) with m. Averaged over N Monte Carlo runs at each time step, N times the average is chi-squared with N * dof degrees of freedom, which gives the standard bounds (Bar-Shalom, Li & Kirubarajan, 2001, sec. 5.4).

ConsistencyCheck dataclass

ConsistencyCheck(
    average: Array,
    lower: float,
    upper: float,
    confidence: float,
    n_runs: int,
    dof: float,
)

Per-step averages of NIS or NEES over Monte Carlo runs against chi-squared bounds.

inside property

inside: Array

Which steps' averages fall inside the bounds.

fraction_inside property

fraction_inside: float

Should be close to confidence for a consistent filter. Clearly lower values with averages above upper mean an overconfident filter (P too small); below lower, an overcautious one.

NEES is usually strongly correlated from step to step, so excursions come in clusters and this fraction varies much more between Monte Carlo batches than a binomial proportion would (several points below confidence is normal). The time average of average lying inside [lower, upper] is a more robust check.

nees

nees(
    truth: ArrayLike, means: ArrayLike, covs: ArrayLike
) -> Array

Normalized estimation error squared e' P^-1 e with e = truth - means.

Leading dimensions broadcast, so truth and means of shape (..., T, n) with covs of shape (..., T, n, n) give a (..., T) result, e.g. (runs, T).

consistency_check

consistency_check(
    values: ArrayLike, dof: float, confidence: float = 0.95
) -> ConsistencyCheck

Average NIS or NEES values of shape (runs, T) (or (T,) for one run) over the runs and compare each step with the chi-squared bounds.

dof is the state dimension for NEES and the measurement dimension for NIS.

chi2_bounds

chi2_bounds(
    dof: float, n_runs: int = 1, confidence: float = 0.95
) -> tuple[float, float]

Two-sided confidence interval for the average of n_runs independent chi-squared(dof) values.

chi2_ppf

chi2_ppf(p: float, dof: float) -> float

Chi-squared quantile, by bisection on chi2_cdf (accurate to ~1e-12 relative).

chi2_cdf

chi2_cdf(x: float, dof: float) -> float

Chi-squared CDF: the regularized lower incomplete gamma function P(dof/2, x/2).