craft_fit: Fit a Trajectory-Aware Regime Forecast
In CRAFT: Conditional Regime Analog Forecasting with Trajectories

craft_fit

R Documentation

Fit a Trajectory-Aware Regime Forecast

Description

Runs the CRAFT end-to-end workflow: trajectory embedding, past and future regime detection, transition probability estimation, future-trajectory sampling, correlation diagnostics, distribution fitting, and optional internal backtesting.

Usage

craft_fit(
  series,
  volumes = NULL,
  window = 20,
  n_draws = 1000,
  n_factors = 3,
  var_threshold = 0.95,
  horizon = NULL,
  seed = 42,
  transition_alpha = 1,
  transition_min_count = 1,
  transition_key_sep = "\r",
  valid_frac = 0.2,
  valid_split = c("last", "random", "blocked"),
  n_testing = 0L,
  backtest_parallel = TRUE,
  backtest_workers = NULL,
  backtest_min_train = NULL,
  sampler_weight = c("uniform", "weighted_bal_acc", "bal_acc", "weighted_acc", "acc"),
  tail_penalty_lambda = 0,
  tail_penalty_threshold = 3,
  tail_penalty_power = 2,
  tail_penalty_aggregation = c("mean", "max", "sum"),
  tail_penalty_scope = c("forecast", "all"),
  volume_alpha = 1,
  max_regimes_per_factor = 6,
  factor_selection = "fixed",
  min_segment = 30L,
  past_regime_args = list(),
  future_regime_args = list(),
  return_train_probs = TRUE,
  verbose = TRUE
)

Arguments

`series`	A data frame or matrix of numeric time series in columns.
`volumes`	Optional matrix or data frame of volumes with the same dimensions as `series`.
`window`	Trajectory window length used for lag and lead embeddings.
`n_draws`	Number of future-trajectory rows to sample.
`n_factors`	Number of SVD factors when fixed factor selection is used.
`var_threshold`	Cumulative variance threshold for variance-based factor selection.
`horizon`	Optional forecast horizon. If `NULL`, all horizons from 1 to `window` are retained.
`seed`	Optional random seed.
`transition_alpha`	Additive smoothing parameter for transition probabilities.
`transition_min_count`	Minimum count for memorized transition rows before fallback to global probabilities.
`transition_key_sep`	Internal separator used for transition-state keys.
`valid_frac`	Fraction of rows reserved for transition-model validation.
`valid_split`	Validation split strategy.
`n_testing`	Number of internal backtest origins. Use zero to skip backtesting.
`backtest_parallel`	Logical. If `TRUE`, run internal backtests in parallel when possible.
`backtest_workers`	Optional number of parallel workers.
`backtest_min_train`	Optional minimum training length for backtest origins.
`sampler_weight`	Metric used to weight target regimes during future-trajectory sampling.
`tail_penalty_lambda`	Strength of the optional tail penalty applied to candidate rows.
`tail_penalty_threshold`	Robust z-score threshold for tail penalties.
`tail_penalty_power`	Power applied to excess robust z-scores.
`tail_penalty_aggregation`	Aggregation used for row-level tail penalties.
`tail_penalty_scope`	Whether the tail penalty uses forecast-horizon columns or all forward-trajectory columns.
`volume_alpha`	Exponent for volume-derived time weights.
`max_regimes_per_factor`	Maximum regimes per SVD factor.
`factor_selection`	SVD factor selection strategy passed to `svd_changepoint_regimes()`.
`min_segment`	Minimum segment length for changepoint regime detection.
`past_regime_args`	Additional arguments passed to past-trajectory regime detection.
`future_regime_args`	Additional arguments passed to future-trajectory regime detection.
`return_train_probs`	Logical. If `TRUE`, include training transition probabilities.
`verbose`	Logical. If `TRUE`, emit progress messages.

Value

An object of class craft_fit, represented as a list containing trajectories, regime models, labels, transition probabilities, sampled trajectory draws, fitted return and level distributions, diagnostics, classifier details, optional backtest results, validation metrics, and the information needed by craft_predict(), including trajectory_draws.

Examples


set.seed(1)
series <- data.frame(
  a = cumprod(1 + rnorm(80, 0.001, 0.01)),
  b = cumprod(1 + rnorm(80, 0.0005, 0.012))
)
fit <- craft_fit(
  series,
  window = 5,
  n_draws = 50,
  n_factors = 1,
  min_segment = 5,
  max_regimes_per_factor = 3,
  n_testing = 0,
  verbose = FALSE
)
names(fit$return_dists)

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