compare¶

MATLAB equivalent: sidCompare

compare ¶

Compare model predicted output to measured data.

compare(model: object, y: ndarray, u: ndarray | None = None, *, initial_state: ndarray | None = None, plot: bool = False) -> CompareResult

Compare model predicted output to measured data.

This is the Python port of sidCompare.m.

Simulates the model's predicted output given the input signal and compares it to the measured output using the NRMSE fit metric:

.. math::

\text{fit} = 100 \left(1 -
    \frac{\|y - \hat y\|}{\|y - \bar y\|}\right)

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`
`initial_state`	`ndarray or None`	Initial state vector for state-space simulation, shape `(p,)`. Default: first row of y.	`None`
`plot`	`bool`	If `True`, display a comparison plot (requires matplotlib). Default: `False`.	`False`

Returns:

Type	Description
`CompareResult`	Frozen dataclass with attributes: predicted -- `(N, ny)` model-predicted output. measured -- `(N, ny)` measured output (copy). fit -- `(ny,)` NRMSE fit percentage per channel. 100% is perfect, 0% is no better than the mean, negative values indicate worse than the mean. residual -- `(N, ny)` residual `y - y_pred`. method -- str, method of the source model.

Raises:

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

Examples:

>>> import sid
>>> G = sid.freq_bt(y, u)
>>> result = sid.compare(G, y, u)

Notes

Specification: (Model output comparison -- not yet in SPEC.md)

For state-space models, the simulation propagates:

.. math::

x(k+1) = A(k)\,x(k) + B(k)\,u(k)

from the initial state x0 (default: first row of y). For multi-trajectory data the fit is averaged across trajectories.