Package {flowz}

Conditional Flow Forecasts with Spectral Calibration

Description

Fits univariate time series using a selectable EWMA, ARIMA, ARFIMA, or structural baseline and a conditional random-feature velocity field. Produces joint multi-step paths, smooth marginal distributions, spectral dispersion calibration, and rolling-origin diagnostics.

Details

Start with flowz to fit a model, predict.flowz to forecast an updated history, and plot.flowz to inspect the four-panel diagnostic display. Read vignette("flowz-introduction", package = "flowz") for an executable workflow, parameter guidance, and evaluation limitations.

Author(s)

Giancarlo Vercellino

Fit a Conditional Flow Model for a Univariate Time Series

Description

Fits a joint distribution of future levels using a selectable EWMA, ARIMA, ARFIMA, or structural baseline, an extreme learning machine (ELM) velocity field, and spectral dispersion calibration. Returns simulated paths, marginal distribution functions, and rolling-origin evaluation diagnostics.

Usage

flowz(x, horizon = 10L, transform = "none", baseline = "ewma",
  baseline_control = list(), autotune = TRUE,
  drift_lambda = 0.90, vol_lambda = 0.94, min_train = NULL,
  innovation_lags = 8L,
  n_hidden = 300L, lambda = 1e-3, flow_aug = 5L, n_steps = 30L,
  n_sims = 1000L, cal_fraction = 0.20, test_fraction = 0.20,
  cal_sims = 200L, test_sims = 200L, spectral_modes = NULL,
  spectral_spar = 0.65, spectral_shrink_to_one = 0.10,
  spectral_tau_bounds = c(0.15, 2.50),
  distribution_bw_factor = 0.50,
  seed = 123L, n_origins = NULL, parallel = TRUE, n_cores = NULL,
  plot = FALSE, verbose = FALSE)

Arguments

Details

The selected baseline supplies a causal mean trajectory and forecast scale. Training targets are joint, standardized multi-step level errors. Random tanh features and ridge-regression output weights approximate a conditional velocity field. Gaussian starting points are integrated to produce joint residual paths. Calibration adjusts dispersion in a discrete cosine basis around the Flow sample mean, preserving that mean on the fitting scale.

Origins are split chronologically, but forecast windows can overlap within and across split boundaries: the implementation does not enforce a horizon embargo. Test scores should therefore not be interpreted as fully independent holdout estimates. Calibration is empirical and offers no exact nominal coverage guarantee. Baseline specification selection uses only the initial training window. If an alternative model fails at an isolated origin, the failure is recorded and Drift/EWMA is used at that origin.

With transform = "log", forecast means, standard deviations, medians, and quantiles are computed from back-transformed samples. Model parameters, kernel bandwidths, and evaluation diagnostics remain on the fitting (log) scale. Density functions include the change-of-variable Jacobian.

Parallel execution uses PSOCK workers on Windows and forked processes elsewhere. Small workloads may run faster with parallel = FALSE.

Value

An object of class flowz, containing:

Practical checks

Use n_origins = NULL initially. An explicit origin count below 40 cannot leave twenty training origins and two blocks of ten. Check the selected origin count and spacing in metadata$diagnostics$origin_selection. For a change in units, compare diagnostics only between fits made on the same scale. In particular, log-scale RMSE is not a price-unit error. See the vignette for examples of chronological evaluation and joint events.

See Also

predict.flowz, plot.flowz. For a worked tutorial, run vignette("flowz-introduction").

Examples

t <- seq_len(260)
x <- cumsum(sin(t / 4) + cos(t / 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(0.05, 0.50, 0.95))
pr <- predict(fit, x, n_sims = 30, seed = 42)
dim(pr$forecast$calibrated$samples)

Forecast and Prediction Output Structures

Description

flowz_forecast stores the three comparable forecasts in a uniform layout. It is available as fit$forecast. predict() returns a compact flowz_prediction object containing forecast and metadata.

Usage

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

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

Arguments

Details

A forecast has exactly three named components:

calibrated

The final spectrally calibrated Flow forecast.

baseline

The selected EWMA, ARIMA, ARFIMA, or structural baseline forecast. Its exact label is recorded in metadata.

uncalibrated

The Flow forecast before spectral correction.

Every component has the same structure:

summary

A data frame with one row per horizon and columns horizon, mean, median, sd, q05, q25, q75, and q95. Values describe the stored samples on the original data scale.

samples

A numeric matrix with simulated paths in rows and horizons named h1, h2, etc. in columns. Complete rows retain cross-horizon dependence within that model. Rows from different models are not paired scenarios.

pred_fun

Lists named dfun, pfun, qfun, and rfun; each contains functions named h1, h2, etc. Their interfaces follow R's density, distribution, quantile, and random generation conventions. For example:

fit$forecast$calibrated$pred_fun$qfun$h3(c(.05, .95))

Flow functions use smooth kernel-mixture marginals; baseline functions use Gaussian marginals around the selected engine trajectory and scale. All operate on original-scale levels, including for log-transformed fits. Separate marginal random draws do not preserve dependence across horizons.

The flowz_prediction returned by predict() contains:

forecast

A flowz_forecast object with the layout above.

metadata

The origin index, horizon, simulation count, transformation, selected baseline and label, forecast scale, and model scale. The origin is the number of observations in the supplied history, not a date.

Summary quantiles are empirical sample quantiles. The smooth marginal functions can return slightly different quantiles. The interface has no duplicated aliases: choose the model first, then its summary, paths, or marginal functions.

Value

The print methods display the calibrated summary and return x invisibly. Objects are created by flowz() and predict().

See Also

flowz, predict.flowz

Examples

t <- seq_len(260)
x <- cumsum(sin(t / 4) + cos(t / 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))
dim(fit$forecast$calibrated$samples)
next_prediction <- predict(fit, x, n_sims = 30, seed = 42)
next_prediction$metadata
next_prediction$forecast$baseline$summary

Predict, Plot, and Print a Fitted Flow Model

Description

Generate paths from an updated history, draw diagnostic plots, or print a summary of a fitted flowz object.

Usage

## S3 method for class 'flowz'
predict(object, newdata, n_sims = 1000L,
  seed = NULL, plot = FALSE, ...)
## S3 method for class 'flowz'
plot(x, ...)
## S3 method for class 'flowz'
print(x, ...)

Arguments

Details

Prediction updates drift, volatility, and conditioning context using the supplied full history. The fitted velocity field, horizon, and spectral calibration are held fixed; no retraining occurs.

The diagnostic plot uses the history and evaluation results from fitting. It shows the current forecast with a 90 percent band, test RMSE, test coverage, and a probability integral transform (PIT) quantile comparison. Calibrated Flow is a thick solid black line; the selected baseline is dashed gray and identified by its fitted label. Reference lines are dotted. For log-transformed models the forecast panel uses original levels, while RMSE remains on the log scale. PIT values are pooled over test origins and horizons, so the panel may mask horizon-specific deviations. plot(x) does not update after predict(x, newdata).

Value

predict returns a flowz_prediction object with two fields: forecast, which has the same three-model structure as object$forecast, and metadata. Each model owns its summary, samples, and pred_fun; see flowz_forecast. Forecast values use the original data scale. plot and print invisibly return the fitted object.

See Also

flowz

Examples

t <- seq_len(260)
x <- cumsum(sin(t / 4) + cos(t / 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)
t_new <- seq_len(265)
x_new <- cumsum(sin(t_new / 4) + cos(t_new / 11))
prediction <- predict(fit, x_new, n_sims = 30, seed = 42)
prediction$forecast$calibrated$summary
prediction$forecast$calibrated$pred_fun$qfun$h3(c(0.05, 0.95))
plot(fit)