Calls the Finn forecast framework to automatically forecast any historical time series.
forecast_time_series(
run_info = NULL,
input_data,
combo_variables,
target_variable,
date_type,
forecast_horizon,
external_regressors = NULL,
hist_start_date = NULL,
hist_end_date = NULL,
combo_cleanup_date = NULL,
fiscal_year_start = 1,
clean_missing_values = TRUE,
clean_outliers = FALSE,
back_test_scenarios = NULL,
back_test_spacing = NULL,
modeling_approach = "accuracy",
forecast_approach = "bottoms_up",
parallel_processing = NULL,
inner_parallel = FALSE,
num_cores = NULL,
negative_forecast = FALSE,
fourier_periods = NULL,
lag_periods = NULL,
rolling_window_periods = NULL,
recipes_to_run = NULL,
pca = NULL,
models_to_run = NULL,
models_not_to_run = NULL,
run_global_models = NULL,
run_local_models = TRUE,
run_ensemble_models = NULL,
average_models = TRUE,
max_model_average = 3,
feature_selection = FALSE,
weekly_to_daily = TRUE,
seed = 123,
run_model_parallel = FALSE,
return_data = TRUE,
run_name = "finnts_forecast",
custom_models = NULL,
stationary = TRUE
)Run info using set_run_info()
A data frame or tibble of historical time series data. Can also include external regressors for both historical and future data.
List of column headers within input data to be used to separate individual time series.
The column header formatted as a character value within input data you want to forecast.
The date granularity of the input data. Finn accepts the following as a character string day, week, month, quarter, year.
Number of periods to forecast into the future.
List of column headers within input data to be used as features in multivariate models.
Date value of when your input_data starts. Default of NULL is to use earliest date value in input_data.
Date value of when your input_data ends.Default of NULL is to use the latest date value in input_data.
Date value to remove individual time series that don't contain non-zero values after that specified date. Default of NULL is to not remove any time series and attempt to forecast all of them.
Month number of start of fiscal year of input data, aids in building out date features. Formatted as a numeric value. Default of 1 assumes fiscal year starts in January.
If TRUE, cleans missing values. Only impute values for missing data within an existing series, and does not add new values onto the beginning or end, but does provide a value of 0 for said values. Turned off when running hierarchical forecasts.
If TRUE, outliers are cleaned and inputted with values more in line with historical data
Number of specific back test folds to run when determining the best model. Default of NULL will automatically choose the number of back tests to run based on historical data size, which tries to always use a minimum of 80% of the data when training a model.
Number of periods to move back for each back test scenario. Default of NULL moves back 1 period at a time for year, quarter, and month data. Moves back 4 for week and 7 for day data.
How Finn should approach your data. Current default and only option is 'accuracy'. In the future this could evolve to other areas like optimizing for interpretability over accuracy.
How the forecast is created. The default of 'bottoms_up' trains models for each individual time series. 'grouped_hierarchy' creates a grouped time series to forecast at while 'standard_hierarchy' creates a more traditional hierarchical time series to forecast, both based on the hts package.
Default of NULL runs no parallel processing and forecasts each individual time series one after another. 'local_machine' leverages all cores on current machine Finn is running on. 'spark' runs time series in parallel on a spark cluster in Azure Databricks or Azure Synapse.
Run components of forecast process inside a specific time series in parallel. Can only be used if parallel_processing is set to NULL or 'spark'.
Number of cores to run when parallel processing is set up. Used when running parallel computations on local machine or within Azure. Default of NULL uses total amount of cores on machine minus one. Can't be greater than number of cores on machine minus 1.
If TRUE, allow forecasts to dip below zero.
List of values to use in creating fourier series as features. Default of NULL automatically chooses these values based on the date_type.
List of values to use in creating lag features. Default of NULL automatically chooses these values based on date_type.
List of values to use in creating rolling window features. Default of NULL automatically chooses these values based on date type.
List of recipes to run on multivariate models that can run different recipes. A value of NULL runs all recipes, but only runs the R1 recipe for weekly and daily date types, and also for global models to prevent memory issues. A value of "all" runs all recipes, regardless of date type or if it's a local/global model. A list like c("R1") or c("R2") would only run models with the R1 or R2 recipe. "C1" is the raw recipe for custom models and is added automatically when custom models are selected; c("C1") alone runs only custom models.
If TRUE, run principle component analysis on any lagged features to speed up model run time. Default of NULL runs PCA on day and week date types across all local multivariate models, and also for global models across all date types.
List of models to run. Default of NULL runs all models.
List of models not to run, overrides values in models_to_run. Default of NULL doesn't turn off any model.
If TRUE, run multivariate models on the entire data set (across all time series) as a global model. Can be override by models_not_to_run. Default of NULL runs global models for all date types except week and day.
If TRUE, run models by individual time series as local models.
If TRUE, run ensemble models. Default of NULL runs ensemble models only for quarter and month date types.
If TRUE, create simple averages of individual models.
Max number of models to average together. Will create model averages for 2 models up until input value or max number of models ran.
Implement feature selection before model training.
This requires the optional Boruta, corrr, ranger, and vip packages.
vip is available from https://bgreenwell.r-universe.dev and requires R
4.1 or newer.
If TRUE, convert a week forecast down to day by evenly splitting across each day of week. Helps when aggregating up to higher temporal levels like month or quarter.
Set seed for random number generator. Numeric value.
If TRUE, runs model training in parallel, only works when parallel_processing is set to 'local_machine' or 'spark'. Recommended to use a value of FALSE and leverage inner_parallel for new features.
If TRUE, return the forecast results. Used to be backwards compatible
with previous finnts versions. Recommended to use a value of FALSE and leverage
get_forecast_data() for new features.
Name used when submitting jobs to external compute like Azure Batch. Formatted as a character string.
Named list of experimental approved custom-model envelopes,
enrolled through models_to_run. A NULL models_to_run runs all built-in
models plus every supplied custom model; an explicit models_to_run must
name every supplied custom model, otherwise an error is raised. See prep_models() for the envelope
contract and supported profile. Selected custom models add the raw C1
recipe to recipes_to_run and may run alone or alongside built-in models.
Their declared drivers come from eligible original input columns, not just
external_regressors. Supply required future values through the horizon.
Incompatible explicit custom settings error before data preparation. Use
create_custom_model() for reviewed authoring.
Apply differencing during preparation; retains the existing TRUE default. Applies only to built-in R1/R2 recipes; custom models always use the raw, original-scale C1 recipe.
A list of three separate data sets: the future forecast, the back test results, and the best model per time series.
Final selection uses the deterministic accuracy and future-plausibility
checks documented in final_models(). It selects from the models already
produced; an invalid forecast is not repaired into a zero forecast or replaced
by an additional model fit. When normal selection has no winner, a complete
finite candidate may be selected with a least-issues plausibility fallback
and a warning. No structurally usable candidate still results in an error.
The saved nonwinning average uses the same ranking among eligible averages.
Hierarchical forecasts use the selected base forecasts as input to the existing
reconciliation solver. Reconciled future outputs are not evaluated to choose
a replacement set or trigger additional model fitting.
Reviewed custom hierarchy models require a shared explicitly mixed custom/FinnTS pool, local-only C1 execution and no external regressors. Model averages and ensembles may include custom forecasts. Eligibility uses requested candidates, not the eventual winning models. Custom-only forecasts require a compatible bottom-up definition instead; no model is automatically added and no requested approach is changed.
# \donttest{
run_info <- set_run_info()
#> Finn Submission Info
#> • Project Name: finn_project
#> • Run Name: finn_fcst-20261020T013409Z
#>
finn_forecast <- forecast_time_series(
run_info = run_info,
input_data = m750 %>% dplyr::rename(Date = date),
combo_variables = c("id"),
target_variable = "value",
date_type = "month",
forecast_horizon = 3,
back_test_scenarios = 6,
run_model_parallel = FALSE,
models_to_run = c("arima", "ets", "snaive"),
return_data = FALSE
)
#> ℹ Prepping Data
#> ✔ Prepping Data [1.1s]
#>
#> ℹ Creating Model Workflows
#> ✔ Creating Model Workflows [218ms]
#>
#> ℹ Creating Model Hyperparameters
#> ✔ Creating Model Hyperparameters [97ms]
#>
#> ℹ Creating Train Test Splits
#> ℹ Turning ensemble models off since no multivariate models were chosen to run.
#> ℹ Creating Train Test Splits
#> ✔ Creating Train Test Splits [2.9s]
#>
#> ℹ Training Individual Models
#> ℹ Turning global models off since no multivariate models were chosen to run.
#> ℹ Training Individual Models
#> ✔ Training Individual Models [12s]
#>
#> ℹ Training Ensemble Models
#> ℹ Ensemble models have been turned off.
#> ℹ Training Ensemble Models
#> ✔ Training Ensemble Models [38ms]
#>
#> ℹ Selecting Best Models
#> ✔ Selecting Best Models [415ms]
#>
fcst_tbl <- get_forecast_data(run_info)
models_tbl <- get_trained_models(run_info)
# }