Result types

Every estimator in sid returns a frozen dataclass. The dataclasses are re-exported from the top-level sid namespace, but their definitions live in sid._results.

CompareResult

CompareResult dataclass

CompareResult(predicted: ndarray, measured: ndarray, fit: ndarray, residual: ndarray, method: str)

Result from model output comparison (compare).

Contains the predicted and measured outputs, the NRMSE fit metric per channel, and the residual.

predicted instance-attribute

predicted: ndarray

Model-predicted output, shape (N, ny).

measured instance-attribute

measured: ndarray

Measured output (copy), shape (N, ny).

fit instance-attribute

fit: ndarray

NRMSE fit percentage per channel, shape (ny,). 100% = perfect, 0% = no better than mean predictor.

residual instance-attribute

residual: ndarray

Residual measured - predicted, shape (N, ny).

method instance-attribute

method: str

Method identifier of the source model.

FreqMapResult

FreqMapResult dataclass

FreqMapResult(time: ndarray, frequency: ndarray, frequency_hz: ndarray, response: ndarray | None, response_std: ndarray | None, noise_spectrum: ndarray, noise_spectrum_std: ndarray, coherence: ndarray | None, sample_time: float, segment_length: int, overlap: int, window_size: int | None, algorithm: str, num_trajectories: int | ndarray, method: str)

Result from time-varying frequency response map (freq_map).

time instance-attribute

time: ndarray

Center time of each segment in seconds, shape (K,).

frequency instance-attribute

frequency: ndarray

Frequency vector in rad/sample, shape (nf,).

frequency_hz instance-attribute

frequency_hz: ndarray

Frequency vector in Hz, shape (nf,).

response instance-attribute

response: ndarray | None

Time-varying frequency response, shape (nf, K) or (nf, K, ny, nu). None in time-series mode.

response_std instance-attribute

response_std: ndarray | None

Standard deviation of response, same shape.

noise_spectrum instance-attribute

noise_spectrum: ndarray

Time-varying noise spectrum, shape (nf, K) or (nf, K, ny, ny).

noise_spectrum_std instance-attribute

noise_spectrum_std: ndarray

Standard deviation of noise spectrum.

coherence instance-attribute

coherence: ndarray | None

Squared coherence, shape (nf, K). SISO only; None otherwise.

sample_time instance-attribute

sample_time: float

Sample time in seconds.

segment_length instance-attribute

segment_length: int

Segment length L.

overlap instance-attribute

overlap: int

Overlap P between segments.

window_size instance-attribute

window_size: int | None

BT lag window size M, or None for Welch.

algorithm instance-attribute

algorithm: str

'bt' or 'welch'.

num_trajectories instance-attribute

num_trajectories: int | ndarray

Number of trajectories used.

Scalar int when every segment uses the same number of trajectories (uniform-length input, or variable-length input where all trajectories happen to span every segment). A (K,) ndarray of intp values otherwise — one entry per segment, giving the number of trajectories that spanned that segment (SPEC.md §6.8).

method instance-attribute

method: str

Always 'freq_map'.

FreqResult

FreqResult dataclass

FreqResult(frequency: ndarray, frequency_hz: ndarray, response: ndarray | None, response_std: ndarray | None, noise_spectrum: ndarray, noise_spectrum_std: ndarray, coherence: ndarray | None, sample_time: float, window_size: int | ndarray, data_length: int, num_trajectories: int, method: str)

Result from frequency-domain estimation (freq_bt, freq_etfe, freq_btfdr).

All array shapes shown for the SISO case. For MIMO, response has shape (nf, ny, nu) and noise_spectrum has shape (nf, ny, ny).

frequency instance-attribute

frequency: ndarray

Frequency vector in rad/sample, shape (nf,).

frequency_hz instance-attribute

frequency_hz: ndarray

Frequency vector in Hz, shape (nf,).

response instance-attribute

response: ndarray | None

Complex frequency response, shape (nf,) or (nf, ny, nu). None in time-series mode.

response_std instance-attribute

response_std: ndarray | None

Standard deviation of response, same shape. None in time-series mode.

noise_spectrum instance-attribute

noise_spectrum: ndarray

Noise (or output) power spectrum, shape (nf,) or (nf, ny, ny).

noise_spectrum_std instance-attribute

noise_spectrum_std: ndarray

Standard deviation of noise_spectrum, same shape.

coherence instance-attribute

coherence: ndarray | None

Squared coherence, shape (nf,). SISO only; None for MIMO or time-series.

sample_time instance-attribute

sample_time: float

Sample time in seconds.

window_size instance-attribute

window_size: int | ndarray

Lag window size M (scalar for BT/ETFE, array for BTFDR).

data_length instance-attribute

data_length: int

Number of samples N per trajectory.

num_trajectories instance-attribute

num_trajectories: int

Number of trajectories used.

method instance-attribute

method: str

Estimation method identifier ('freq_bt', 'freq_etfe', 'freq_btfdr').

FrozenResult

FrozenResult dataclass

FrozenResult(frequency: ndarray, frequency_hz: ndarray, time_steps: ndarray, response: ndarray, response_std: ndarray | None, sample_time: float, method: str)

Result from frozen transfer function computation (ltv_disc_frozen).

Contains the instantaneous (frozen) frequency response G(w, k) computed from time-varying state-space matrices A(k), B(k), along with optional uncertainty propagation.

frequency instance-attribute

frequency: ndarray

Frequency vector in rad/sample, shape (nf,).

frequency_hz instance-attribute

frequency_hz: ndarray

Frequency vector in Hz, shape (nf,).

time_steps instance-attribute

time_steps: ndarray

Selected time step indices (0-based), shape (nk,).

response instance-attribute

response: ndarray

Complex frozen transfer function, shape (nf, p, q, nk).

response_std instance-attribute

response_std: ndarray | None

Standard deviation of response, shape (nf, p, q, nk). None when the input LTVResult has no uncertainty.

sample_time instance-attribute

sample_time: float

Sample time in seconds.

method instance-attribute

method: str

Always 'ltv_disc_frozen'.

LTVIOResult

LTVIOResult dataclass

LTVIOResult(a: ndarray, b: ndarray, x: ndarray | list, h: ndarray, r: ndarray, cost: ndarray, iterations: int, lambda_: ndarray, data_length: int, state_dim: int, output_dim: int, input_dim: int, num_trajectories: int, a_std: ndarray | None, b_std: ndarray | None, p_cov: ndarray | None, noise_cov: ndarray | None, noise_cov_estimated: bool | None, noise_variance: float | None, degrees_of_freedom: float | None, algorithm: str, method: str)

Result from LTV input-output identification (ltv_disc_io).

Contains the identified time-varying system matrices A(k), B(k), estimated state trajectories, and optional Bayesian uncertainty estimates. All array shapes use the convention (rows, cols, time) consistent with MATLAB's (:, :, k) indexing.

a instance-attribute

a: ndarray

Time-varying dynamics matrices, shape (n, n, N).

b instance-attribute

b: ndarray

Time-varying input matrices, shape (n, q, N).

x instance-attribute

x: ndarray | list

Estimated state trajectories, shape (N+1, n, L) or list of (N_l+1, n) arrays for variable-length trajectories.

h instance-attribute

h: ndarray

Observation matrix, shape (py, n) (copy).

r instance-attribute

r: ndarray

Measurement noise covariance, shape (py, py) (copy).

cost instance-attribute

cost: ndarray

Cost history at each iteration, shape (n_iter,).

iterations instance-attribute

iterations: int

Number of alternating iterations.

lambda_ instance-attribute

lambda_: ndarray

Regularization values used, shape (N-1,).

data_length instance-attribute

data_length: int

Number of time steps N.

state_dim instance-attribute

state_dim: int

State dimension n.

output_dim instance-attribute

output_dim: int

Output dimension py.

input_dim instance-attribute

input_dim: int

Input dimension q.

num_trajectories instance-attribute

num_trajectories: int

Number of trajectories L.

a_std instance-attribute

a_std: ndarray | None

Standard deviation of a entries, shape (n, n, N). None when uncertainty was not computed.

b_std instance-attribute

b_std: ndarray | None

Standard deviation of b entries, shape (n, q, N). None when uncertainty was not computed.

p_cov instance-attribute

p_cov: ndarray | None

Row-wise posterior covariance blocks, shape (d, d, N) where d = n + q. None when uncertainty was not computed.

noise_cov instance-attribute

noise_cov: ndarray | None

Noise covariance matrix, shape (n, n). None when uncertainty was not computed.

noise_cov_estimated instance-attribute

noise_cov_estimated: bool | None

True if noise_cov was estimated from residuals. None when uncertainty was not computed.

noise_variance instance-attribute

noise_variance: float | None

Scalar noise variance trace(noise_cov) / n. None when uncertainty was not computed.

degrees_of_freedom instance-attribute

degrees_of_freedom: float | None

Effective degrees of freedom used in noise covariance estimation. None when uncertainty was not computed.

algorithm instance-attribute

algorithm: str

Identification algorithm ('cosmic').

method instance-attribute

method: str

Always 'ltv_disc_io'.

LTVResult

LTVResult dataclass

LTVResult(a: ndarray, b: ndarray, a_std: ndarray | None, b_std: ndarray | None, p_cov: ndarray | None, noise_cov: ndarray | None, noise_cov_estimated: bool | None, noise_variance: float | None, degrees_of_freedom: float | None, lambda_: ndarray, cost: ndarray, data_length: int, state_dim: int, input_dim: int, num_trajectories: int, algorithm: str, preconditioned: bool | str, method: str)

Result from LTV state-space identification (ltv_disc).

Contains the identified time-varying system matrices A(k), B(k) and optional Bayesian uncertainty estimates. All array shapes use the convention (rows, cols, time) consistent with MATLAB's (:, :, k) indexing.

a instance-attribute

a: ndarray

Time-varying dynamics matrices, shape (p, p, N).

b instance-attribute

b: ndarray

Time-varying input matrices, shape (p, q, N).

a_std instance-attribute

a_std: ndarray | None

Standard deviation of a entries, shape (p, p, N). None when uncertainty was not requested.

b_std instance-attribute

b_std: ndarray | None

Standard deviation of b entries, shape (p, q, N). None when uncertainty was not requested.

p_cov instance-attribute

p_cov: ndarray | None

Row-wise posterior covariance blocks, shape (d, d, N) where d = p + q. None when uncertainty was not requested.

noise_cov instance-attribute

noise_cov: ndarray | None

Noise covariance matrix, shape (p, p). None when uncertainty was not requested.

noise_cov_estimated instance-attribute

noise_cov_estimated: bool | None

True if noise_cov was estimated from residuals, False if user-provided. None when uncertainty was not requested.

noise_variance instance-attribute

noise_variance: float | None

Scalar noise variance trace(noise_cov) / p. None when uncertainty was not requested.

degrees_of_freedom instance-attribute

degrees_of_freedom: float | None

Effective degrees of freedom used in noise covariance estimation. NaN when noise_cov was user-provided. None when uncertainty was not requested.

lambda_ instance-attribute

lambda_: ndarray

Regularization values used, shape (N-1,).

cost instance-attribute

cost: ndarray

Cost vector [total, fidelity, regularization], shape (3,).

data_length instance-attribute

data_length: int

Number of time steps N.

state_dim instance-attribute

state_dim: int

State dimension p.

input_dim instance-attribute

input_dim: int

Input dimension q.

num_trajectories instance-attribute

num_trajectories: int

Number of trajectories L.

algorithm instance-attribute

algorithm: str

Identification algorithm ('cosmic').

preconditioned instance-attribute

preconditioned: bool | str

Whether block-diagonal preconditioning was applied.

False when not requested, 'not_implemented' when requested but disabled (v1.0), or True when implemented and applied.

method instance-attribute

method: str

Always 'ltv_disc'.

ResidualResult

ResidualResult dataclass

ResidualResult(residual: ndarray, auto_corr: ndarray, auto_corr_all: ndarray, cross_corr: ndarray, confidence_bound: float, whiteness_pass: bool, whiteness_pass_all: ndarray, independence_pass: bool, independence_pass_all: ndarray | None, data_length: int)

Result from residual analysis (residual).

Contains the model residuals, normalised auto- and cross-correlation functions, and whiteness/independence diagnostic test outcomes.

residual instance-attribute

residual: ndarray

Residual time series, shape (N, ny).

auto_corr instance-attribute

auto_corr: ndarray

Normalised autocorrelation of the first output channel, shape (max_lag + 1,).

auto_corr_all instance-attribute

auto_corr_all: ndarray

Per-channel normalised autocorrelation, shape (max_lag + 1, ny).

cross_corr instance-attribute

cross_corr: ndarray

Normalised cross-correlation between residuals and inputs, shape (2 * max_lag + 1, ny * nu). Empty array for time-series.

confidence_bound instance-attribute

confidence_bound: float

99% confidence bound 2.58 / sqrt(N).

whiteness_pass instance-attribute

whiteness_pass: bool

True if all channels pass the whiteness test.

whiteness_pass_all instance-attribute

whiteness_pass_all: ndarray

Per-channel whiteness test result, shape (ny,).

independence_pass instance-attribute

independence_pass: bool

True if all (output, input) pairs pass the independence test.

independence_pass_all instance-attribute

independence_pass_all: ndarray | None

Per-pair independence test result, shape (ny * nu,). None for time-series mode.

data_length instance-attribute

data_length: int

Number of samples used.

SpectrogramResult

SpectrogramResult dataclass

SpectrogramResult(time: ndarray, frequency: ndarray, frequency_rad: ndarray, power: ndarray, power_db: ndarray, complex_stft: ndarray, sample_time: float, window_length: int, overlap: int, nfft: int, num_trajectories: int, method: str)

Result from short-time FFT spectrogram (spectrogram).

time instance-attribute

time: ndarray

Center time of each segment in seconds, shape (K,).

frequency instance-attribute

frequency: ndarray

Frequency vector in Hz, shape (n_bins,).

frequency_rad instance-attribute

frequency_rad: ndarray

Frequency vector in rad/s, shape (n_bins,).

power instance-attribute

power: ndarray

Power spectral density, shape (n_bins, K) or (n_bins, K, n_ch).

power_db instance-attribute

power_db: ndarray

Power in dB (10 * log10(power)), same shape.

complex_stft instance-attribute

complex_stft: ndarray

Complex STFT coefficients, same shape.

sample_time instance-attribute

sample_time: float

Sample time in seconds.

window_length instance-attribute

window_length: int

Segment length L.

overlap instance-attribute

overlap: int

Overlap P between segments.

nfft instance-attribute

nfft: int

FFT length.

num_trajectories instance-attribute

num_trajectories: int

Number of trajectories used.

method instance-attribute

method: str

Always 'spectrogram'.

Exceptions

SidError

SidError(code: str, message: str)

Bases: Exception

Base exception for sid toolbox errors.

Parameters:

Name	Type	Description	Default
code	str	Machine-readable error code (e.g. 'too_short', 'non_finite').	required
message	str	Human-readable error description.	required

Attributes:

Name	Type	Description
code	str	The error code passed at construction time.