pyhctsa.operations.model_fit.state_space_n4sid

pyhctsa.operations.model_fit.state_space_n4sid(y, ord=2, ptrain=0.5, steps=1)

A fitted state-space model of the series, and how well it predicts the later part of the series.

First fits the model to the whole time series, then trains it on the first portion and tries to predict the rest (hctsa’s MF_StateSpace_n4sid; the subspace algorithm N4SID is implemented directly). The state-space model has the form (discrete time, no input, sampling interval 1) x(t+1) = A x(t) + K e(t), y(t) = C x(t) + e(t), for state-transition matrix A and output matrix C, noise-input vector K, vector of states x and disturbance (noise) e. The model fitted to the first ptrain proportion of the series is used to predict the remaining samples steps ahead, and the prediction residuals (prediction minus data) are summarized with residual_analysis().

Parameters:
y : array-like

The input time series.

ord : int or 'best', optional

The order of the state-space model (the number of states), or 'best' to choose the order from 1 to 10 that minimizes Akaike’s information criterion. Default is 2.

ptrain : float, optional

The proportion of the time series to use for training. Default is 0.5.

steps : int, optional

The number of steps ahead to predict. Default is 1.

Returns:

All outputs NaN if the model cannot be fitted (e.g. a series too short for the order). Otherwise, from the model fitted to the entire time series:

  • A_1, …, A_(ord^2): the entries of the state-transition matrix A, counted down each column in turn

  • k_1, …, k_ord: the entries of the noise-input vector K

  • c_1, …, c_ord: the entries of the output vector C

  • x0mod: the length of the least-squares initial state of the one-step predictor (descriptive: how far from rest the series starts; the predictions below start from a diffuse initial state)

  • np: the number of parameters fitted

  • Ts: the sampling interval of the model (always 1)

  • noisevar: the estimated noise variance

  • lossfn: the loss function (the estimated prediction-error variance)

  • fpe: Akaike’s final prediction error

  • bestorder: the order chosen (only when ord is 'best')

From the residuals of the predictions of the held-out portion (see residual_analysis(), 'full'): meane, meanabs, stde, maxonstd, ac1, ac2, ac3, propbth, ftbth, taurat, sws, swm, normksstat, popt, minsbc; and ac1diff, the absolute lag-1 autocorrelation of the whole time series minus that of the prediction residuals.

Return type:

dict

Notes

The individual entries of A, K and C depend on the (arbitrary) coordinates of the hidden state, so they are not directly comparable between time series. Here the sign of each state is fixed so that C has no negative entries (the sign of a singular vector depends on the linear algebra library). The loss, fpe and the residual summaries do not depend on the coordinates.

The model has 2 n free parameters once the freedom in the choice of coordinates is removed, which is the count in noisevar and fpe. Predictions start from a diffuse initial state (_prediction_errors()), and the loss and the residual summaries average over the samples predicted (all but the first order samples).

The residuals are prediction minus data. The held-out portion starts at sample floor(ptrain*N), overlapping the training portion by one sample.