residual¶

MATLAB equivalent: sidResidual

residual ¶

Model residual analysis and diagnostic tests.

residual ¶

residual(model: object, y: ndarray, u: ndarray | None = None, *, max_lag: int | None = None, plot: bool = False) -> ResidualResult

Compute model residuals and perform diagnostic tests.

This is the Python port of sidResidual.m.

Computes residuals from an estimated model and performs whiteness (autocorrelation) and independence (cross-correlation) tests to assess model quality.

Parameters:

Name	Type	Description	Default
`model`	`object`	Result from any `sid` estimator. Must have either `a` and `b` attributes (state-space / COSMIC) or a `response` attribute (frequency-domain).	required
`y`	ndarray, shape ``(N, ny)`` or ``(N+1, p, L)``	Measured output data. For state-space models the array contains state trajectories `(N+1, p)` or `(N+1, p, L)`.	required
`u`	`ndarray or None`	Input data, shape `(N, nu)` or `(N, q, L)`. `None` for time-series models (no input).	`None`
`max_lag`	`int or None`	Maximum lag for correlation tests. Default: `min(25, N // 5)`.	`None`
`plot`	`bool`	If `True`, display a diagnostic plot (requires matplotlib). Default: `False`.	`False`

Returns:

Type Description

ResidualResult

Frozen dataclass with attributes:

residual -- (N, ny) residual time series.
auto_corr -- (max_lag+1,) normalised autocorrelation of the first channel.
auto_corr_all -- (max_lag+1, ny) per-channel autocorrelation.
cross_corr -- (2*max_lag+1, ny*nu) normalised cross-correlation, or empty array for time-series.
confidence_bound -- scalar 99% bound 2.58/sqrt(N).
whiteness_pass -- bool, True if all channels pass.
whiteness_pass_all -- (ny,) bool array, per-channel.
independence_pass -- bool, True if all pairs pass (always True for time-series).
independence_pass_all -- (ny*nu,) bool array, or None for time-series.
data_length -- int, effective number of samples N.

Raises:

Type	Description
`SidError`	If the model type cannot be determined (code: `'bad_model'`).

Examples:

>>> import sid
>>> G = sid.freq_bt(y, u)
>>> res = sid.residual(G, y, u)

Notes

Specification: (Model residual analysis -- not yet in SPEC.md)

The whiteness test checks that the normalised autocorrelation |r_ee(tau)| < 2.58 / sqrt(N) for tau = 1, ..., max_lag. The independence test checks the same bound for the normalised cross-correlation between residuals and inputs at all lags in [-max_lag, max_lag]. Both tests use a 99% confidence level.