Fits conditional flow-matching models to univariate time series.
Combines a selectable exponentially weighted moving average (EWMA),
autoregressive integrated moving average (ARIMA), autoregressive
fractionally integrated moving average (ARFIMA), or structural time-series
baseline with direct multi-step residual paths and a random-feature extreme
learning machine (ELM) velocity field. Spectral dispersion calibration uses
a chronological calibration block, with a separate test block for forecast
scoring. Provides simulated forecast paths and smooth marginal
distributions. Methodological background is given by Lipman et al. (2023)
Conditional flow forecasting with spectral dispersion calibration for finite, chronologically ordered univariate series.
library(flowz)
x <- cumsum(sin(seq_len(260) / 4) + cos(seq_len(260) / 11))
fit <- flowz(x, horizon = 3, n_hidden = 10, flow_aug = 1,
n_steps = 3, n_sims = 30, cal_sims = 30, test_sims = 30,
parallel = FALSE)
fit$forecast$calibrated$summary
fit$forecast$calibrated$pred_fun$qfun$h3(c(.05, .5, .95))
fit$forecast$calibrated$samples
plot(fit)
Choose the baseline engine independently of the Flow layer:
fit_arima <- flowz(x, baseline = "arima", autotune = TRUE)
fit_arfima <- flowz(x, baseline = "arfima", autotune = TRUE)
fit_structural <- flowz(x, baseline = "structural", autotune = TRUE)
fit_arima$metadata$baseline_label
Available baselines are "ewma" (the default), "arima", "arfima", and
"structural". Autotuning uses only the initial training window; the selected
specification is refitted using the information available at each historical
forecast origin. Use baseline_control for fixed ARIMA orders, ARFIMA search
ranges, or a structural "level"/"trend" choice.
The fitted object has five visible sections:
fit
|- forecast
| |- calibrated
| |- baseline
| `- uncalibrated
|- evaluation
|- calibration
|- model
`- metadata
Every model under forecast has the same fields: summary, samples, and
pred_fun. The latter contains dfun, pfun, qfun, and rfun, with
horizons named h1, h2, and so on. calibrated is the final Flow forecast,
baseline is the selected baseline forecast, and uncalibrated is Flow before
spectral correction. The chosen model name is in fit$metadata$baseline_label.
predict() returns only a new forecast and its metadata:
pr <- predict(fit, x, n_sims = 100, seed = 42)
pr$forecast$calibrated$summary
pr$forecast$baseline$pred_fun$qfun$h3(.5)
For strictly positive price series, use transform = "log". Fitting and
evaluation use log values; forecast summaries, paths, and marginal functions
are returned on the original price scale.
See ?flowz, ?flowz_forecast, and
vignette("flowz-introduction", package = "flowz") for the full interface,
method, evaluation design, and calibration limitations. Calibration is
empirical and does not guarantee nominal coverage under serial dependence.
The help pages are hand-written. devtools::document() regenerates only
NAMESPACE. Run devtools::test() for source tests or
Rscript --vanilla tools/check.R for the installed-package tests, vignette,
manual, and CRAN-style checks. Windows source tests skip the PSOCK comparison;
the full check runs it against the installed package.
Author and maintainer: Giancarlo Vercellino. License: GPL-3.