This vignette explains the data requirements for using any of the
core functions of nixtlar:
# Core functions of `nixtlar`
- nixtlar::nixtla_client_forecast()
- nixtlar::nixtla_client_historic()
- nixtlar::nixtla_client_detect_anomalies()
- nixtlar::nixtla_client_cross_validation()
- nixtlar::nixtla_client_plot()1. Input Requirements
nixtlar now supports the following data structures: data
frames, tibbles, and tsibbles. The output format will always be a data
frame.
Regardless of your data structure, the following two columns must
always be included when using any core functions of
nixtlar:
Date Column: This column must contain timestamps formatted as
YYYY-MM-DDorYYYY-MM-DD hh:mm:ss, either as characters or date-time objects. For date-time objects, we recommend using theas.POSIX*functions from base R, althoughas.Dateis also supported. The default name for this column isds. If your dataset uses a different name, please specify it by setting the parametertime_col="your_time_column_name".Target Column: This column should contain the numeric target variable for forecasting. The default name for this column is
y. If your dataset uses a different name, specify it by setting the parametertarget_col="your_target_column_name".
2. Multiple Series
If you are working with multiple series, you must include a column
with a unique identifier for each series. This column can contain
characters or integers, and its default name is unique_id.
If your dataset uses a different name for the identifier column, please
specify it by setting the parameter
id_col="your_id_column_name". If your dataset contains only
one series and does not need an identifier, set id_col to
NULL.
Please be aware that in earlier versions of nixtlar, the
default name for id_col was NULL, but it is
now unique_id.
# sample valid input
df <- nixtlar::electricity
head(df)
#> unique_id ds y
#> 1 BE 2016-10-22 00:00:00 70.00
#> 2 BE 2016-10-22 01:00:00 37.10
#> 3 BE 2016-10-22 02:00:00 37.10
#> 4 BE 2016-10-22 03:00:00 44.75
#> 5 BE 2016-10-22 04:00:00 37.10
#> 6 BE 2016-10-22 05:00:00 35.61
str(df)
#> 'data.frame': 8400 obs. of 3 variables:
#> $ unique_id: chr "BE" "BE" "BE" "BE" ...
#> $ ds : chr "2016-10-22 00:00:00" "2016-10-22 01:00:00" "2016-10-22 02:00:00" "2016-10-22 03:00:00" ...
#> $ y : num 70 37.1 37.1 44.8 37.1 ...3. Exogenous Variables
When using exogenous variables, nixtlar distinguishes
between historical and future exogenous variables:
Historical Exogenous Variables: These should be included in the input data immediately following the
id_col,ds, andycolumns. If your dataset contains additional columns that are not exogenous variables, you must remove them before using any core functions ofnixtlar.Future Exogenous Variables: These correspond to the
X_dfparameter and should cover the entire forecast horizon. This dataset must include columns with the appropriate timestamps and, if applicable, unique identifiers, formatted as described in the previous sections.
# sample valid input with exogenous variables
df <- nixtlar::electricity_exo_vars
head(df)
#> unique_id ds y Exogenous1 Exogenous2 day_0 day_1 day_2
#> 1 BE 2016-10-22 00:00:00 70.00 49593 57253 0 0 0
#> 2 BE 2016-10-22 01:00:00 37.10 46073 51887 0 0 0
#> 3 BE 2016-10-22 02:00:00 37.10 44927 51896 0 0 0
#> 4 BE 2016-10-22 03:00:00 44.75 44483 48428 0 0 0
#> 5 BE 2016-10-22 04:00:00 37.10 44338 46721 0 0 0
#> 6 BE 2016-10-22 05:00:00 35.61 44504 46303 0 0 0
#> day_3 day_4 day_5 day_6
#> 1 0 0 1 0
#> 2 0 0 1 0
#> 3 0 0 1 0
#> 4 0 0 1 0
#> 5 0 0 1 0
#> 6 0 0 1 0
future_exo_vars <- nixtlar::electricity_future_exo_vars
head(future_exo_vars)
#> unique_id ds Exogenous1 Exogenous2 day_0 day_1 day_2 day_3
#> 1 BE 2016-12-31 00:00:00 64108 70318 0 0 0 0
#> 2 BE 2016-12-31 01:00:00 62492 67898 0 0 0 0
#> 3 BE 2016-12-31 02:00:00 61571 68379 0 0 0 0
#> 4 BE 2016-12-31 03:00:00 60381 64972 0 0 0 0
#> 5 BE 2016-12-31 04:00:00 60298 62900 0 0 0 0
#> 6 BE 2016-12-31 05:00:00 60339 62364 0 0 0 0
#> day_4 day_5 day_6
#> 1 0 1 0
#> 2 0 1 0
#> 3 0 1 0
#> 4 0 1 0
#> 5 0 1 0
#> 6 0 1 0To learn more about how to use exogenous variables, please refer to the Exogenous variables vignette.
4. Missing values
When using TimeGPT via nixtlar, ensure the
following:
No Missing Values in the Target Column: The target column must not contain any missing values (
NA).Continuous Date Sequence: The dates must be continuous, without any gaps, from the start date to the end date, matching the frequency of the data.
Currently, nixtlar does not provide any functionality to fill missing values or dates. To learn more about this, please refer to the vignette on Special Topics.
5. Minimum data requirements
The minimum size per series to obtain results from
nixtlar::nixtla_client_forecast is one, regardless of the
frequency of the data. Keep in mind, however, that this will produce
results with limited accuracy.
For certain scenarios, more than one observation may be necessary:
- When using the parameters
level,quantiles, orfinetune_steps. - When incorporating exogenous variables.
- When including historical forecasts by setting
add_history=TRUE.
The minimum data requirement varies with the frequency of the data, detailed in the official TimeGPT documentation.
When using nixtlar::nixtla_client_cross_validation, you
also need to consider the forecast horizon (h), the number
of windows (n_windows) and the step size
(step_size). The formula for the minimum data points
required per series is:
Here, refers to the values specified in the table from the official documentation.