Package {rollcast}

rollcast: Probabilistic Forecasting with Adaptive Mixtures of Rolling Statistics

Description

The rollcast package implements probabilistic forecasting using adaptive mixtures of rolling statistical anchors, causal proper-score gating, optional state-conditional residual sampling, and recursive predictive mixtures.

Details

Use rollcast to fit a model and predict() to generate probabilistic forecasts.

Author(s)

Giancarlo Vercellino

Plot Rollcast Probabilistic Forecasts and Diagnostics

Description

Plots either a predictive fan or a compact diagnostic dashboard containing forecast uncertainty and state-dynamics information.

Usage

## S3 method for class 'rollcast_prediction'
plot(
  x,
  type = c("diagnostic", "fan"),
  ...
)

plot_rollcast_fan(
  prediction,
  levels = c(0.50, 0.80, 0.90, 0.95),
  history = TRUE,
  n_history = 150L,
  smooth = FALSE,
  spar = 0.60,
  enforce_nested = TRUE,
  col = NULL,
  history_col = "black",
  median_col = "black",
  history_lwd = 1.5,
  median_lwd = 2,
  median_lty = 1,
  boundary_lty = 3,
  main = "Rollcast probabilistic forecast",
  xlab = "Time",
  ylab = "Level",
  legend = TRUE,
  legend_outside = TRUE,
  legend_cex = 0.62,
  legend_inset = 0.20,
  legend_bty = "n",
  ...
)

plot_rollcast_diagnostic(
  prediction,
  levels = c(0.50, 0.80, 0.90, 0.95),
  history = TRUE,
  n_history = 180L,
  smooth = FALSE,
  spar = 0.60,
  enforce_nested = TRUE,
  dispersion_level = 0.90,
  transition_smooth = TRUE,
  transition_spar = 0.55,
  transition_min_segment = 3L,
  fan_palette = NULL,
  history_col = "#252525",
  median_col = "#111111",
  main = "Rollcast forecast diagnostics",
  ...
)

Arguments

Details

The uncertainty transition horizon fits the continuous segmented model

W_h = a + b_1 h + \Delta b (h-h^*)_+

to predictive interval width W_h. The breakpoint h^* estimates a change in the rate of forecast-uncertainty expansion.

Value

The plotting functions return their diagnostic quantities invisibly.

Generate Probabilistic Forecasts from a Rollcast Model

Description

Recursively simulates an explicit all-anchor predictive mixture and returns marginal and joint probabilistic forecasts.

Usage

## S3 method for class 'rollcast'
predict(
  object,
  horizon = 20L,
  nsim = 3000L,
  probs = c(
    0.01, 0.025, 0.05, 0.10, 0.25, 0.50,
    0.75, 0.90, 0.95, 0.975, 0.99
  ),
  resampling = c("anchor_stratified", "systematic", "multinomial"),
  keep_components = FALSE,
  seed = NULL,
  ...
)

Arguments

Value

An object of class "rollcast_prediction" containing recursive paths, anchor probabilities, explicit marginal mixture values and weights, forecast summaries, and predictive functions dfun, pfun, qfun, and rfun.

Examples

set.seed(2)
y <- 100 + cumsum(rnorm(150, sd = 0.5))

fit <- rollcast(
  y,
  window = 30, tau = 0.25, lambda = 0.01,
  conditional_k = 10, state_bw = 1,
  residual_bw = 0.35, error_scale = 0,
  residual_smoothing = 0.03,
  rho_min = 0.05, rho_max = 0.90, rho_decay = 1,
  min_history = 10, maxit = 60
)

pred <- predict(fit, horizon = 5, nsim = 100, seed = 2)
pred$qfun(c(0.1, 0.5, 0.9), h = 1)

Print Rollcast Model and Prediction Summaries

Description

Compact print methods for fitted Rollcast models and probabilistic forecasts.

Usage

## S3 method for class 'rollcast'
print(x, ...)
## S3 method for class 'rollcast_prediction'
print(x, ...)

Arguments

Value

The input object, invisibly.

Fit a Rollcast Probabilistic Forecasting Model

Description

Fits a probabilistic time-series forecasting model based on adaptive mixtures of rolling statistical anchors. Numeric hyperparameters use a unified interface: a scalar fixes the parameter, while a vector requests causal validation-based search over those candidate values.

Usage

rollcast(
  ts,
  window = c(20L, 30L, 45L, 60L, 90L, 120L),
  tau = c(0.15, 0.25, 0.40),
  lambda = c(0.001, 0.01, 0.05),
  conditional_k = c(20L, 40L, 80L),
  state_bw = c(0.60, 1.00, 1.60),
  residual_bw = c(0.20, 0.35, 0.55),
  error_scale = c(0, 0.10, 0.25, 0.50, 0.75, 1),
  residual_smoothing = c(0.01, 0.03, 0.06),
  rho_min = c(0, 0.05, 0.10),
  rho_max = c(0.80, 0.90, 0.97),
  rho_decay = c(0.50, 1, 2),
  quantiles = c(0.05, 0.10, 0.25, 0.75, 0.90, 0.95),
  feature_type = c("relative", "raw"),
  min_history = 20L,
  score_floor_bw = 0.05,
  validation_fraction = 0.25,
  search_passes = 1L,
  search_maxit = 120L,
  maxit = 500L,
  tolerance = 1e-8,
  verbose = FALSE,
  na_action = c("fail", "omit")
)

Arguments

Details

For rolling window \mathcal H_t, the model constructs an anchor vector containing the rolling mean, median, minimum, maximum, fitted regression endpoint, and user-specified quantiles. With robust scale s_t, the default state feature for anchor j is

X_{t,j} = (S_{t,j} - y_t) / s_t.

Historical soft anchor responsibilities are based on

d_{t,j} = |y_{t+1}-S_{t,j}|/s_t

and a temperature-controlled softmax.

Forecast candidates are

Y_{h,b,j} = S_{h,b,j} + \gamma s_{h,b} E_{h,b,j},

where \gamma is error_scale. Every particle and anchor contributes to the explicit predictive mixture before recursive resampling.

If a tunable numeric argument is supplied as a scalar, it is fixed. If it is supplied as a vector, candidate values are compared using cached coordinate search on common causal validation origins.

Value

An object of class "rollcast" containing fitted gating parameters, selected hyperparameters, rolling states, residual information, current anchor probabilities, validation diagnostics, and search metadata.

Examples

set.seed(1)
y <- 100 + cumsum(rnorm(160, sd = 0.6))

fit <- rollcast(
  y,
  window = 30,
  tau = 0.25,
  lambda = 0.01,
  conditional_k = 10,
  state_bw = 1,
  residual_bw = 0.35,
  error_scale = 0,
  residual_smoothing = 0.03,
  rho_min = 0.05,
  rho_max = 0.90,
  rho_decay = 1,
  min_history = 10,
  maxit = 60
)

fit