statsmodels.tsa.statespace.kalman_smoother.SmootherResults.smoothed_state_autocovariance

SmootherResults.smoothed_state_autocovariance(lag=1, t=None, start=None, end=None, extend_kwargs=None)

Compute state vector autocovariances, conditional on the full dataset

Computes:

\[Cov(\alpha_t - \hat \alpha_t, \alpha_{t - j} - \hat \alpha_{t - j})\]

where the lag argument gives the value for \(j\). Thus when the lag argument is positive, the autocovariance is between the current and previous periods, while if lag is negative the autocovariance is between the current and future periods.

Parameters:

lagint, optional

The number of period to shift when computing the autocovariance. Default is 1.

tint, optional

A specific period for which to compute and return the autocovariance. Cannot be used in combination with start or end. See the Returns section for details on how this parameter affects what is what is returned.

startint, optional

The start of the interval (inclusive) of autocovariances to compute and return. Cannot be used in combination with the t argument. See the Returns section for details on how this parameter affects what is what is returned. Default is 0.

endint, optional

The end of the interval (exclusive) autocovariances to compute and return. Note that since it is an exclusive endpoint, the returned autocovariances do not include the value at this index. Cannot be used in combination with the t argument. See the Returns section for details on how this parameter affects what is what is returned and what the default value is.

extend_kwargsdict, optional

Keyword arguments containing updated state space system matrices for handling out-of-sample autocovariance computations in time-varying state space models.

Returns:

acovndarray

Array of autocovariance matrices. If the argument t is not provided, then it is shaped (k_states, k_states, n), while if t given then the third axis is dropped and the array is shaped (k_states, k_states).

The output under the default case differs somewhat based on the state space model and the sign of the lag. To see how these cases differ, denote the output at each time point as Cov(t, t-j). Then:

• If lag > 0 (and the model is either time-varying or time-invariant), then the returned array is shaped (*, *, nobs) and each entry [:, :, t] contains Cov(t, t-j). However, the model does not have enough information to compute autocovariances in the pre-sample period, so that we cannot compute Cov(1, 1-lag), Cov(2, 2-lag), …, Cov(lag, 0). Thus the first lag entries have all values set to NaN.

• If the model is time-invariant and lag < -1 or if lag is 0 or -1, and the model is either time-invariant or time-varying, then the returned array is shaped (*, *, nobs) and each entry [:, :, t] contains Cov(t, t+j). Moreover, all entries are available (i.e. there are no NaNs).

• If the model is time-varying and lag < -1 and extend_kwargs is not provided, then the returned array is shaped (*, *, nobs - lag + 1).

• However, if the model is time-varying and lag < -1, then extend_kwargs can be provided with lag - 1 additional matrices so that the returned array is shaped (*, *, nobs) as usual.

More generally, the dimension of the last axis will be start - end.

Notes

This method computes:

\[Cov(\alpha_t - \hat \alpha_t, \alpha_{t - j} - \hat \alpha_{t - j})\]

where the lag argument determines the autocovariance order \(j\), and lag is an integer (positive, zero, or negative). This method cannot compute values associated with time points prior to the sample, and so it returns a matrix of NaN values for these time points. For example, if start=0 and lag=2, then assuming the output is assigned to the variable acov, we will have acov[…, 0] and acov[…, 1] as matrices filled with NaN values.

Based only on the “current” results object (i.e. the Kalman smoother applied to the sample), there is not enough information to compute Cov(t, t+j) for the last lag - 1 observations of the sample. However, the values can be computed for these time points using the transition equation of the state space representation, and so for time-invariant state space models we do compute these values. For time-varying models, this can also be done, but updated state space matrices for the out-of-sample time points must be provided via the extend_kwargs argument.

See [1], Chapter 4.7, for all details about how these autocovariances are computed.

The t and start/end parameters compute and return only the requested autocovariances. As a result, using these parameters is recommended to reduce the computational burden, particularly if the number of observations and/or the dimension of the state vector is large.

References

[1]

Durbin, James, and Siem Jan Koopman. 2012. Time Series Analysis by State Space Methods: Second Edition. Oxford University Press.