trajectory_forecast: Fit Smooth Forecast Distributions for Trajectory Draws

In CRAFT: Conditional Regime Analog Forecasting with Trajectories

Fit Smooth Forecast Distributions for Trajectory Draws

Description

Fits one smoothed empirical forecast distribution per column in a data frame of sampled future-trajectory draws. Optionally reconstructs returns or differences into forecast levels.

Usage

trajectory_forecast(
  trajectory_draws,
  last_level = NULL,
  recon_mode = NULL,
  probs = seq(0.001, 0.999, length.out = 1000),
  spar = NULL,
  density_spar = NULL,
  eps = 1e-06,
  enforce_monotone = TRUE,
  plot_result = FALSE,
  min_obs = 10L,
  min_unique = 10L,
  jitter_if_needed = TRUE,
  jitter_scale = 1e-08,
  zero_density_outside = TRUE,
  seed = 1L,
  verbose = FALSE,
  return_diagnostics = TRUE
)

Arguments

trajectory_draws	Data frame of sampled future-trajectory draws, with one variable per column.
last_level	Optional scalar or vector of latest observed levels used to reconstruct forecast levels.
recon_mode	Optional reconstruction mode: "differences", "scaled_growth", "log_growth", or NULL.
probs	Probability grid passed to smooth_quantile_distribution().
spar	Optional quantile smoothing parameter.
density_spar	Optional density smoothing parameter.
eps	Small positive numerical tolerance.
enforce_monotone	Logical. If TRUE, enforce monotone quantile fits.
plot_result	Logical. If TRUE, plot fitted distributions.
min_obs	Minimum observations used for each fitted distribution. Shorter samples are bootstrapped.
min_unique	Minimum unique values before jittering is considered.
jitter_if_needed	Logical. If TRUE, add small jitter to discrete or constant samples.
jitter_scale	Scale of jitter relative to the sample scale.
zero_density_outside	Logical. If TRUE, return zero density outside the fitted support.
seed	Optional random seed used for augmentation and jitter.
verbose	Logical. If TRUE, emit fitting progress messages.
return_diagnostics	Logical. If TRUE, attach diagnostics as an attribute.

Value

A named list of distribution objects. Diagnostics and settings are attached as attributes when requested.

Examples

set.seed(1)
trajectory_draws <- data.frame(a = rnorm(40, 0.01, 0.02), b = rnorm(40, -0.01, 0.03))
fc <- trajectory_forecast(
  trajectory_draws,
  probs = seq(0.05, 0.95, length.out = 30),
  verbose = FALSE
)
fc$a$qfun(0.5)

CRAFT documentation built on Nov. 2, 2026, 9:06 a.m.