Predict from an exact Gaussian-process regression model — predict

Computes the posterior mean and uncertainty at new input locations. Latent function uncertainty and future-observation uncertainty are reported separately. The stored Cholesky factor from model fitting is reused; no covariance-matrix inverse is formed.

Usage

predict_gp(
  model,
  x,
  interval_level = 0.95,
  include_covariance = FALSE,
  variance_tolerance = sqrt(.Machine$double.eps),
  observation_noise_variance = NULL,
  block_size = NULL
)

Arguments

model: A fitted gaussianprocesses_model, or a state-space model from fit_time_series_gp(), which is predicted by Kalman smoothing at inputs on its time-index scale (block_size does not apply; memory is linear in the number of inputs).
x: Numeric vector or matrix of prediction inputs. Matrix rows are observations and columns must match the fitted input dimension.
interval_level: Probability level for latent credible intervals and noisy-observation prediction intervals.
include_covariance: If TRUE, return the full latent and observation posterior covariance matrices. Otherwise only marginal variances are returned.
variance_tolerance: Relative tolerance used when deciding whether a small negative posterior variance is floating-point error or a material numerical failure.
observation_noise_variance: Optional non-negative scalar or vector giving observation-noise variance at the prediction inputs. It defaults to the fitted scalar noise variance for homoscedastic models. Models fitted with observation-specific training noise require this argument.
block_size: Number of prediction inputs processed together when include_covariance = FALSE. NULL (the default) chooses the largest block whose training-by-block cross-covariance holds at most $2^{20}$ values (8 MiB). Results do not depend on the block size. It is ignored when include_covariance = TRUE.

Value

An object of class gaussianprocesses_prediction. Its fields are shared by every prediction in the package: predict_sparse_gp(), predict_heteroscedastic_gp(), and forecast_gp() return the same fields with the same meaning, and may add their own.

x: The prediction inputs as a matrix.
mean: The posterior mean of the latent function.
latent_variance, latent_sd: The posterior variance and standard deviation of the latent function.
observation_noise_variance: The noise variance of a new observation.
observation_variance, observation_sd: The variance and standard deviation of a new noisy observation: latent_variance + observation_noise_variance.
interval_level, latent_interval, prediction_interval: The interval level and the intervals for the latent function and for a new observation.
latent_covariance, observation_covariance: The full covariance matrices, only with include_covariance = TRUE.

Details

With $n$ training and $m$ prediction inputs, $C = R^\top R$ the factorized training covariance, and $V = R^{-\top} K(X, X_*)$, the latent posterior variance at prediction input $j$ is $$\mathrm{Var}[f(x_{*j}) \mid y] = k(x_{*j}, x_{*j}) - \sum_i V_{ij}^2.$$ This is exact. The default marginal prediction evaluates only the cross-covariance $K(X, X_*)$, in blocks of block_size prediction inputs, and the prior variances $k(x_{*j}, x_{*j})$ with kernel_diagonal(). It takes $O(n^2 m)$ time and $O(n b)$ memory for blocks of $b$ inputs, beyond the $O(n^2)$ fitted factor.

include_covariance = TRUE also forms the $m \times m$ prior covariance and the latent and observation posterior covariances, which takes $O(n^2 m + n m^2)$ time and $O(m^2)$ memory. Each $m \times m$ matrix takes $8 m^2$ bytes, 512 MB for 8000 inputs, and several are held at once. It is opt-in because pointwise means, variances, and intervals do not need it; joint quantities such as function draws (sample_gp_posterior()) do.

A parametric mean contributes $h(x_*)^\top \beta$ with its fixed, estimated, or posterior-mean coefficients. Estimated coefficients are plugged in. Marginalized coefficients add their uncertainty, $R_* (B^{-1} + H^\top C^{-1} H)^{-1} R_*^\top$ with $R_* = H_* - V^\top R^{-\top} H$, to the latent variances and covariances (mean_coefficients).

Stability

Stable: from version 1.0.0 this interface changes incompatibly only in a major release, after a deprecation period. Results and options that concern an experimental model class, kernel, or argument follow that interface's tier. See gaussianprocesses-package for the policy.

Examples

x <- seq(-2, 2, length.out = 15)
model <- fit_gp(
  x,
  sin(2 * x),
  kernel = rbf_kernel(length_scale = 0.6),
  noise_variance = 0.01
)

prediction <- predict_gp(model, c(0, 3))

# Latent-function and noisy-observation uncertainty are reported separately;
# both grow away from the data.
prediction$latent_sd
#> [1] 0.07286796 0.91754142
prediction$observation_sd
#> [1] 0.1237325 0.9229747
prediction$prediction_interval
#>           lower     upper
#> [1,] -0.2425113 0.2425113
#> [2,] -2.1455780 1.4724163