Quick Start Guide

1. Bring Data

Data used in Finn needs to follow a few requirements, called out below.

• Data is tabular, formatted as data frame, tibble, or spark data frame.
• Needs a time stamp or date column, which needs to be formatted as a date and labeled as “Date”. The date values need to start at the beginning of the period. For example, a monthly data set needs to have each date period started on the first day of each month. For a quarterly forecast, the first day of the quarter, etc.
• Contains at least one unique label to identify one time series from another. These are sometimes referred to as “data combos” or “combo variables” in Finn. For example, a monthly forecast by country should have a column with country names to help Finn split out each country into separate time series.
• No duplicate rows at the intersection of data combos and date.
• Column headers should contain only letters, numbers, and underscores. They should also start with a letter, not a number. These requirements ensure that R/Python handle your data frame correctly without any errors.
• External regressors are optional, they’re not required to produce a Finn forecast. To learn more about how to use them, please check out the vignette on external regressors.

A good example to use when producing your first Finn forecast is to leverage existing data examples from the timetk package. Let’s take a monthly example and trim it down to speed up the run time of your first Finn forecast.

library(finnts)

hist_data <- timetk::m4_monthly %>%
  dplyr::filter(date >= "2013-01-01") %>%
  dplyr::rename(Date = date) %>%
  dplyr::mutate(id = as.character(id))

print(hist_data)
#> # A tibble: 120 × 3
#>    id    Date       value
#>    <chr> <date>     <dbl>
#>  1 M1    2013-01-01  9120
#>  2 M1    2013-02-01  8280
#>  3 M1    2013-03-01  7860
#>  4 M1    2013-04-01  7150
#>  5 M1    2013-05-01  8110
#>  6 M1    2013-06-01 10860
#>  7 M1    2013-07-01 10730
#>  8 M1    2013-08-01  9610
#>  9 M1    2013-09-01  8270
#> 10 M1    2013-10-01  9200
#> # ℹ 110 more rows

print(unique(hist_data$id))
#> [1] "M1"    "M2"    "M750"  "M1000"

The above data set contains 4 individual time series, identified using the “id” column.

2. Create Finn Forecast

Before we call the Finn forecast function. Let’s first set up some run information using set_run_info(), this helps log all components of our Finn forecast successfully.

run_info <- set_run_info(
  experiment_name = "finn_forecast",
  run_name = "test_run"
)

Calling the “forecast_time_series” function is the easiest part. In this example we will be running just two models.

# no need to assign it to a variable, since all of the outputs are written to disk :)
forecast_time_series(
  run_info = run_info,
  input_data = hist_data,
  combo_variables = c("id"),
  target_variable = "value",
  date_type = "month",
  forecast_horizon = 3,
  back_test_scenarios = 6,
  models_to_run = c("arima", "ets"),
  return_data = FALSE
)

3. Get Forecast Outputs

finn_output_tbl <- get_forecast_data(run_info = run_info)

print(finn_output_tbl)

future_forecast_tbl <- finn_output_tbl %>%
  dplyr::filter(Run_Type == "Future_Forecast")

print(future_forecast_tbl)

back_test_tbl <- finn_output_tbl %>%
  dplyr::filter(Run_Type == "Back_Test")

print(back_test_tbl)

best_model_tbl <- finn_output_tbl %>%
  dplyr::filter(Best_Model == "Yes") %>%
  dplyr::select(Combo, Model_ID, Model_Name, Model_Type, Recipe_ID) %>%
  dplyr::distinct()

print(best_model_tbl)

trained_model_tbl <- get_trained_models(run_info = run_info)

print(trained_model_tbl)

R1_prepped_data_tbl <- get_prepped_data(
  run_info = run_info,
  recipe = "R1"
)

print(R1_prepped_data_tbl)

R2_prepped_data_tbl <- get_prepped_data(
  run_info = run_info,
  recipe = "R2"
)

print(R2_prepped_data_tbl)

run_info_tbl <- get_run_info(experiment_name = "finn_forecast")

print(run_info_tbl)