pyhctsa.operations.model_fit.residual_analysis

pyhctsa.operations.model_fit.residual_analysis(e, y=None, level='full')

Canonical summary of the residuals from a model fit.

The shared residual-summary contract of the model-fitting and forecasting operations (hctsa’s MF_ResidualAnalysis): every operation that produces a residual series reports it through this function, so the same quantity carries the same name everywhere. Two levels are available: 'core' is cheap (no test and no model fit), 'full' adds diagnostics that need extra machinery.

Parameters:
e : array-like

The residuals, as prediction minus data (e = yp - y).

y : array-like, optional

The original time series the model was fitted to. It is only used for taurat, which compares the residual timescale to the data timescale; taurat is NaN if y is not supplied. Default is None.

level : {'full', 'core'}, optional

The summary level. Default is 'full'.

Returns:

'core' (11 fields):

  • meane: mean residual

  • meanabs: mean absolute residual

  • stde: standard deviation of the residuals

  • maxonstd: largest absolute residual, in units of the residual standard deviation

  • ac1, ac2, ac3: residual autocorrelation at lags 1 to 3

  • propbth: proportion of the first 25 autocorrelations within the significance band, 2.6/sqrt(N)

  • taurat: residual decorrelation time (first zero crossing of the ACF) divided by that of the data (NaN without y, or if the data timescale is 0 or undefined)

  • sws, swm: stationarity of the residual standard deviation and mean across 5 windows

'full' adds 4 fields:

  • ftbth: first lag at which the autocorrelation drops below significance (26 if it never does)

  • normksstat: Kolmogorov-Smirnov statistic against a standard normal

  • popt: order of the SBC-selected zero-mean AR model (orders 1 to 10, fitted with the ARFIT algorithm) of the z-scored residuals (NaN if the fit fails)

  • minsbc: the corresponding Schwarz criterion (NaN if the fit fails)

Return type:

dict

Notes

Residuals that do not vary beyond the level of rounding error (an exactly predictable series: std(e) <= 1e-9 max(std(y), mean(|e|)), with std(y) taken as 0 if y is not given, _is_rounding_level()) carry no information on their shape: then only meane, meanabs and stde (which have meaningful limiting values) are returned and every other field is NaN.

Callers: local_simple ('core'), ar_cov ('core'), ar_fit ('core', on the negated ARFIT residuals), exp_smoothing ('full') and nonlinearity.nlpe ('full', hctsa’s NL_nlpe passes the series as y: residual_analysis(res, y, 'full'); the one-argument call still works but leaves taurat NaN).