pyhctsa.operations.model_fit.gp_hyperparameters

pyhctsa.operations.model_fit.gp_hyperparameters(y, cov_func='covSEiso_covNoise', squish_or_squash=1, max_n=500, resample_how='resample', random_seed=0, num_draws=20)

Fits a Gaussian process to the series and reports its fitted kernel parameters and goodness of fit.

Models the series as a smooth function of time using a Gaussian process (GP). A zero-mean GP with a Gaussian likelihood is fitted using the covariance function cov_func, e.g., (i) a sum of squared exponential and noise terms, or (ii) a sum of squared exponential, periodic, and noise terms. The log hyperparameters are found by maximizing the marginal likelihood to convergence (_gp_fit_converged()), with the noise standard deviation and signal amplitudes bounded below by 1% of that of the data and the length scales between the sampling interval and the span of the series. The length scales are reported only when the fitted model beats its white-noise special case in a likelihood-ratio test (_gp_beats_white_noise()), as otherwise they are not identified: they are then the sampling interval, the bound the data allow (periods and shape parameters are then NaN). The other outputs are always reported, and approach those of white noise as the structure vanishes. Goodness of fit is summarized by the per-point negative log marginal likelihood, the error of the fitted mean, and the GP’s predictive standard deviation.

Fitting is O(N^3), so the model is fitted to at most max_n samples from the time series, chosen by (i) resampling the time series down to this many points, (ii) taking the first max_n samples, or (iii) taking random samples. Times are the sample indices (squish_or_squash = 1), so length scales and periods are in samples of the cut series. The output is NaN if the fit fails, or if the values fitted are constant to within round-off (see _gp_roundoff_constant()).

Parameters:
y : array-like

The input time series (should be z-scored).

cov_func : str or list, optional

The covariance function: the names of the components of a gpml covSum joined with underscores ('covSEiso_covNoise', 'covSEiso_covPeriodic_covNoise', 'covMaterniso3_covNoise', 'covRQiso_covNoise'), or the gpml form ['covSum', ['covSEiso', 'covNoise']] (['covMaterniso', 3] for a component with a degree). Default is 'covSEiso_covNoise'.

squish_or_squash : int, optional

How to set the time index: if nonzero (default), t = 0, …, N - 1; if zero, t is spread across the unit interval.

max_n : int, float or 'full', optional

The maximum length of time series to consider – longer inputs are cut down to max_n samples. A value below 1 is a proportion of the length. 0 or 'full' disables the cut and uses the whole series. Default is 500.

resample_how : str, optional

How to cut time series longer than max_n down to max_n points:

  • 'resample' (default): resample the whole series down (scipy.signal.resample_poly),

  • 'first': take the first max_n samples,

  • 'random_i': take max_n random samples (unevenly spaced),

  • 'random_consec': take max_n consecutive samples from a random position,

  • 'random_both': take max_n consecutive samples from a random position, then a random fifth of them.

random_seed : int, 'default', 'none' or None, optional

The seed of the random numbers, for the settings of resample_how that use them, as hctsa’s BF_RandomSeed: a number, 'default' or None for seed 0, or 'none' for a seed drawn from NumPy’s global state. The draws come from the portable generator (pyhctsa.robust.bf_random()), so they are hctsa’s. Default is 0.

num_draws : int, optional

The number of independent random samples to fit, for the settings of resample_how that use random numbers (draw d uses the seed 2*num_draws*seed + 2*(d - 1), so that different seeds share no draws). The outputs are the means over the draws that gave a valid fit (NaN if fewer than half did): a single random sample of a few tens of points is dominated by which points were drawn. Default is 20.

Returns:

  • logh1, logh2, …: the log hyperparameters of the fitted covariance function, in the order of its components (the number depends on cov_func): covSEiso: [log length scale, log amplitude]; covPeriodic: [log length scale, log period, log amplitude]; covMaterniso(3): [log length scale, log amplitude]; covRQiso: [log length scale, log amplitude, log shape parameter alpha]; covNoise: [log noise standard deviation],

  • nlml: the negative log marginal likelihood of the fitted model, divided by the number of points it was fitted to,

  • stde: root-mean-square error of the GP mean at the sampled times,

  • meanabs_std: mean absolute error of the GP mean, in units of the GP’s predictive standard deviation at each sampled time,

  • std_mu_data: standard deviation of the GP mean at the sampled times (if not close to one, the GP has not followed the z-scored data),

  • std_S_data: standard deviation of the GP’s predictive standard deviation at the sampled times (informative only for irregularly sampled times, as with 'random_i': for evenly spaced times the predictive standard deviation is constant except near the ends),

  • maxS, minS, meanS: maximum, minimum, and mean of the GP’s predictive standard deviation over 1000 equally spaced times spanning the sampled series,

  • oosmedabserr: out-of-sample error, for the random-subsample settings of resample_how ('random_i', 'random_both'): the median absolute difference between the series and the GP mean at the times between the first and last sampled time that were not sampled (so are not seen by the fit), in units of the series’ standard deviation; NaN when every point in that span was sampled (e.g., 'first', 'resample', or a series no longer than max_n).

Return type:

dict