Forecast or interpolate from a time-aware GP model — forecast

Converts future time values using the training model's original time origin and units, then evaluates the GP posterior: exactly, or by Kalman smoothing for state-space models. Each requested point is labelled as interpolation, backward extrapolation, or forward forecast.

Usage

forecast_gp(
  model,
  future_time,
  interval_level = 0.95,
  include_covariance = FALSE,
  variance_tolerance = sqrt(.Machine$double.eps),
  observation_noise_variance = NULL
)

Arguments

model: A model fitted by fit_time_series_gp() or optimize_time_series_gp().
future_time: Numeric, Date, or POSIXt values matching the training time type and supplied in strictly increasing order.
interval_level: Probability level for posterior intervals.
include_covariance: If TRUE, include full posterior covariance matrices.
variance_tolerance: Relative tolerance for posterior variances.
observation_noise_variance: Optional non-negative scalar or vector of observation-noise variances at future_time, passed to predict_gp(). Required when the model was fitted with observation-specific training noise.

Value

An object of class gaussianprocesses_time_forecast.

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

time <- as.Date("2026-01-01") + 0:23
model <- fit_time_series_gp(
  time,
  sin(2 * pi * (0:23) / 12),
  kernel = time_series_kernel(period = 12),
  noise_variance = 0.05
)

forecast <- forecast_gp(model, as.Date("2026-01-01") + c(10.5, 25, 30))
data.frame(
  region = forecast$region,
  mean = forecast$mean,
  forecast$prediction_interval
)
#>          region       mean     lower     upper
#> 1 interpolation -0.6962863 -1.659359 0.2667868
#> 2      forecast  0.2065849 -2.303192 2.7163623
#> 3      forecast -0.1593709 -2.842194 2.5234518