geossm.ssm.StateSpaceResults

class geossm.ssm.StateSpaceResults(model, y_hat, Sigma_y_hat=None, tdelta_hat=None, params=None, params_names=None, params_dim=None, y_obs=None, yname=None, Xbeta=None, backend=None, dtype=None, llf=None, time_filter=0.0, time_smoother=0.0, time_expectation=0.0, time_total=0.0, x_filtered=None, P_filtered=None, x_pred=None, P_pred=None, K=None, x_smoothed=None, P_smoothed=None, P_pred_smoothed=None, S11=None, S10=None, S00=None)

Bases: object

Container for state-space model estimation results (filter and/or smoother outputs), with convenience methods for residuals, error metrics, confidence intervals, diagnostics and a printable summary.

Instances are normally created by geossm.ssm.statespace.StateSpaceModel.filter, geossm.ssm.statespace.StateSpaceModel.smoother or geossm.ssm.statespace.StateSpaceModel.estimate, not directly by user code. All array-valued attributes are stored as NumPy arrays (converted from JAX arrays on construction, see to_numpy) in the dtype of the originating model.

model

The geossm.ssm.statespace.StateSpaceModel (or subclass) instance that produced these results.

Type:

object or None

y_obs

Observed data used for fitting (may contain NaN).

Type:

numpy.ndarray, shape (p, T)

y_hat

Predicted/fitted observation means.

Type:

numpy.ndarray, shape (p, T)

Sigma_y_hat

State-driven predictive covariance of y_hat (excludes observation noise R); see geossm.ssm.statespace._compute_predict_kernel_JAX.

Type:

numpy.ndarray, shape (p, p, T) or None

x_filtered, P_filtered

Filtered state means/covariances (None when unavailable, e.g. after smoother(..., light=True)).

Type:

numpy.ndarray or None

x_pred, P_pred

One-step-ahead predicted state means/covariances from the filter.

Type:

numpy.ndarray or None

K

Kalman gain at the final time step.

Type:

numpy.ndarray or None

x_smoothed, P_smoothed

Smoothed state means/covariances.

Type:

numpy.ndarray or None

P_pred_smoothed

Smoothed lag-one state covariances.

Type:

numpy.ndarray or None

S11, S10, S00

EM sufficient statistics; see geossm.ssm.statespace._compute_expected_values_kernelJAX.

Type:

numpy.ndarray or None

llf

Model log-likelihood.

Type:

float or None

time_filter, time_smoother, time_expectation, time_total

Wall-clock runtimes (seconds) of the filter, smoother, expected- value/sufficient-statistics computation, and their sum.

Type:

float

Methods

as_dict	Return a plain dict snapshot of the main results.
conf_int_state	Compute pointwise Gaussian confidence intervals for the latent state.
conf_int_y	Compute pointwise Gaussian confidence/prediction intervals for the predicted observations y_hat.
coverage_probability	Empirical coverage probability of the conf_int_y prediction intervals.
diagnostics	Compute standard residual-normality/autocorrelation diagnostics.
generate_summary	Build the two small key/value tables (model identity/config and fit runtime on the left, fit-quality/residual diagnostics on the right) used by summary.
mse	Mean squared error of the residuals.
rmse	Root mean squared error of the residuals.
summary	Build a statsmodels-style structured summary of the fit: model identity/shape/runtime, log-likelihood, MSE/RMSE, coverage probability and residual diagnostics (Jarque-Bera, Omnibus, skewness, kurtosis, Durbin-Watson).
to_numpy	Convert array-like attributes to numpy arrays in the results' dtype (the model's dtype, by default), so results stay numerically consistent with the precision the model was fit in.
update	Return a new StateSpaceResults with some fields replaced.

Attributes

backend	JAX compute device any further computation on these results runs on (defaults to the originating model's geossm.ssm.statespace.StateSpaceModel.backend).
dtype	Floating-point precision results are stored in (defaults to the originating model's dtype).
residuals	Observation residuals, or None if unavailable.

property backend

JAX compute device any further computation on these results runs on (defaults to the originating model’s geossm.ssm.statespace.StateSpaceModel.backend).

Type:

jax.Device

property dtype

Floating-point precision results are stored in (defaults to the originating model’s dtype).

Type:

numpy.dtype

to_numpy()

Convert array-like attributes to numpy arrays in the results’ dtype (the model’s dtype, by default), so results stay numerically consistent with the precision the model was fit in.

update(**kwargs)

Return a new StateSpaceResults with some fields replaced.

Copies every current public (non-underscore-prefixed) attribute except today, overrides the ones given in kwargs, and constructs a new instance from the result. Does not mutate self.

Parameters:

**kwargs – Attribute name/value pairs to override; each key must already be a public attribute of this instance.

Returns:

StateSpaceResults – A new instance with the requested fields updated.

Raises:

AttributeError – If a key in kwargs is not an existing public attribute.

Return type:

StateSpaceResults

property residuals: ndarray | None

Observation residuals, or None if unavailable.

Returns:

numpy.ndarray or None – y_obs - y_hat, shape (p, T) (NaN where y_obs is missing), or None if either y_obs or y_hat is unavailable.

mse(which='global')

Mean squared error of the residuals.

Parameters:

which ({'global', 'space', 'time'}, default 'global') – Aggregation axis: 'global' averages over all (non-missing) entries; 'space' averages over time, returning one value per observed location/variable, shape (p,); 'time' averages over space, returning one value per time step, shape (T,). NaN residuals (missing observations) are ignored.

Returns:

float or numpy.ndarray – Mean squared error, aggregated as requested.

Raises:

ValueError – If which is not one of 'global', 'space', 'time'.

Return type:

float

rmse(which='global')

Root mean squared error of the residuals.

Parameters:

which ({'global', 'space', 'time'}, default 'global') – Aggregation axis; forwarded to mse.

Returns:

float or numpy.ndarray – Square root of mse, aggregated as requested.

Return type:

float

conf_int_state(which='smoothed', alpha=0.05)

Compute pointwise Gaussian confidence intervals for the latent state.

For each time step, uses the marginal state mean/variance (\(x_t\), \(\mathrm{diag}(P_t)\)) and a two-sided Normal quantile: \(x_t \pm z_{1-\alpha/2} \sqrt{\mathrm{diag}(P_t)}\). Does not account for cross-state covariances (only the marginal per-component variance is used).

Parameters:

• which ({'smoothed', 'filtered'}, default 'smoothed') – Whether to use the smoothed (x_smoothed/P_smoothed) or filtered (x_filtered/P_filtered) state estimates.

• alpha (float, default 0.05) – Significance level; the interval has nominal coverage 1 - alpha.

Returns:

lower, upper (numpy.ndarray, shape (q, T+1)) – Lower and upper confidence bounds for the state mean.

Raises:

ValueError – If which is invalid, or the required state means/ covariances are not available on this results object.

Return type:

Tuple[ndarray, ndarray]

conf_int_y(alpha=0.05, prediction=False)

Compute pointwise Gaussian confidence/prediction intervals for the predicted observations y_hat.

For each time step, uses \(\hat y_t \pm z_{1-\alpha/2} \sqrt{\mathrm{diag}(\Sigma_{\hat y, t})}\), where \(\Sigma_{\hat y, t}\) is Sigma_y_hat (the state-driven predictive covariance, excluding observation noise) plus, when prediction=True, the observation noise covariance R read from self.model - turning a confidence interval for the mean response into a prediction interval for a new observation.

Parameters:

• alpha (float, default 0.05) – Significance level; the interval has nominal coverage 1 - alpha.

• prediction (bool, default False) – If True, add the model’s observation noise covariance R to Sigma_y_hat before computing the interval (prediction interval); if False, use Sigma_y_hat alone (confidence interval for the mean).

Returns:

lower, upper (numpy.ndarray, shape (p, T)) – Lower and upper interval bounds for y_hat.

Raises:

ValueError – If y_hat or Sigma_y_hat is not available on this results object.

Return type:

Tuple[ndarray, ndarray]

coverage_probability(alpha=0.05, which='global')

Empirical coverage probability of the conf_int_y prediction intervals.

Computes the fraction of observed values y_obs that fall within the 1 - alpha prediction interval from conf_int_y(alpha, prediction=True); for a well-calibrated model this should be close to 1 - alpha.

Parameters:

• alpha (float, default 0.05) – Significance level used for the prediction interval.

• which ({'global', 'space', 'time'}, default 'global') – Aggregation axis: 'global' averages over all entries; 'space' averages over time (shape (p,)); 'time' averages over space (shape (T,)).

Returns:

float or numpy.ndarray – Empirical coverage probability in [0, 1], aggregated as requested.

diagnostics()

Compute standard residual-normality/autocorrelation diagnostics.

Flattens the (non-missing) residuals and computes:

• Jarque-Bera test statistic and p-value (jb/jb_pvalue) for normality, based on sample skewness and kurtosis.

• Omnibus normality test statistic and p-value (omni/omni_pvalue, statsmodels’ omni_normtest).

• Sample skewness and excess kurtosis (skew/kurtosis).

• Durbin-Watson statistic (dw) for first-order autocorrelation (values near 2 indicate little autocorrelation).

Returns:

dict of str to float – Keys jb, jb_pvalue, omni, omni_pvalue, dw, skew, kurtosis.

Return type:

Dict[str, float]

generate_summary()

Build the two small key/value tables (model identity/config and fit runtime on the left, fit-quality/residual diagnostics on the right) used by summary.

As a side effect, sets self.nobs, self.nspace, self.ntime and self.missing from y_obs.

Returns:

tuple of list – (gen_top_left, gen_top_right), each a list of (label, [value]) pairs suitable for statsmodels.iolib.summary.Summary.add_table_2cols.

summary()

Build a statsmodels-style structured summary of the fit: model identity/shape/runtime, log-likelihood, MSE/RMSE, coverage probability and residual diagnostics (Jarque-Bera, Omnibus, skewness, kurtosis, Durbin-Watson).

Returns:

statsmodels.iolib.summary.Summary – Printable summary table; str()/repr() of this results object render this summary.

Return type:

Summary

as_dict()

Return a plain dict snapshot of the main results.

Ensures all array attributes are NumPy arrays first (via to_numpy). Useful for serialization or for passing results to code that should not depend on the StateSpaceResults class.

Returns:

dict – Keys: y_obs, y_hat, Sigma_y_hat, x_filtered, P_filtered, x_smoothed, P_smoothed, llf, mse (global), rmse (global), diagnostics (see diagnostics), S11, S10, S00.

Return type:

Dict[str, Any]