Get Started

library(nixtlar)
#> Error in get(paste0(generic, ".", class), envir = get_method_env()) : 
#>   object 'type_sum.accel' not found

nixtlar provides an R interface to Nixtla’s TimeGPT, a generative pre-trained forecasting model for time series data. TimeGPT is the first foundation model capable of producing accurate forecasts for new time series not seen during training, using only its historical values as inputs. TimeGPT can also be used for other time series related tasks, such as anomaly detection and cross-validation. Here we explain how to get started with TimeGPT in R and give a quick overview of the main features of nixtlar.

1. Setting up your API key

First, you need to set up your API key. An API key is a string of characters that allows you to authenticate your requests when using TimeGPT via nixtlar. This API key needs to be provided by Nixtla, so if you don’t have one, please request one here.

When using nixtlar, there are two ways of setting up your API key:

a. Using the `nixtla_client_setup` function

nixtlar has a function to easily set up your API key for your current R session. Simply call

nixtla_client_setup(api_key = "Your API key here")

Keep in mind that if you close your R session or you re-start it, then you’ll need to set up your API key again.

When using Azure, you also need to add the base_ur parameter to the nixtla_client_setup function.

nixtla_client_setup(
  base_url = "Base ULR",
  api_key = "Your API key here"
)

b. Using an environment variable

For a more persistent method that can be used across different projects, set up your API key as environment variable. To do this, first load the usethis package.

library(usethis)
usethis::edit_r_environ()

This will open your .Reviron file. Place your API key here and named it NIXTLA_API_KEY.

# Inside the .Renviron file 
NIXTLA_API_KEY="Your API key here"

You’ll need to restart R for changes to take effect. Keep in mind that modifying the .Renviron file affects all of your R sessions, so if you’re not comfortable with this, use the nixtla_client_setup function instead.

If you are using Azure, you also need to specify the NIXTLA_BASE_URL.

# Inside the .Renviron file 
NIXTLA_BASE_URL="Base URL"
NIXTLA_API_KEY="Your API key here"

For details on how to set up your API key, check out the Setting Up Your API Key vignette. To learn more about how to use Azure, please refer to the TimeGEN-1 Quickstart (Azure).

Validate your API key

If you want to validate your API key, call nixtla_validate_api_key.

nixtla_validate_api_key()

You don’t need to validate your API key every time you set it up, only when you want to check if it’s valid. The nixtla_validate_api_key will return TRUE if you API key is valid, and FALSE otherwise.

2. Generate TimeGPT forecast

Once your API key has been set up, you’re ready to use TimeGPT. Here we’ll show you how this is done using a dataset that contains prices of different electricity markets.

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

To generate a forecast for this dataset, use nixtla_client_forecast. Default names for the time and the target columns are ds and y. If your time and target columns have different names, specify them with time_col and target_col. Since it has multiple ids (one for every electricity market), you’ll need to specify the name of the column that contains the ids, which in this case is unique_id. To do this, simply use id_col="unique_id". You can also choose confidence levels (0-100) for prediction intervals with level.

nixtla_client_fcst <- nixtla_client_forecast(df, h = 8, level = c(80,95))
#> Frequency chosen: h
head(nixtla_client_fcst)
#>   unique_id                  ds  TimeGPT TimeGPT-lo-95 TimeGPT-lo-80
#> 1        BE 2016-12-31 00:00:00 45.19067      30.49690      35.50871
#> 2        BE 2016-12-31 01:00:00 43.24491      28.96405      35.37627
#> 3        BE 2016-12-31 02:00:00 41.95889      27.06674      35.34068
#> 4        BE 2016-12-31 03:00:00 39.79668      27.96726      32.32737
#> 5        BE 2016-12-31 04:00:00 39.20456      24.66173      30.99833
#> 6        BE 2016-12-31 05:00:00 40.10912      23.05270      32.43550
#>   TimeGPT-hi-80 TimeGPT-hi-95
#> 1      54.87264      59.88444
#> 2      51.11356      57.52577
#> 3      48.57710      56.85105
#> 4      47.26598      51.62609
#> 5      47.41079      53.74739
#> 6      47.78273      57.16553

3. Plot TimeGPT forecast

nixtlar includes a function to plot the historical data and any output from nixtla_client_forecast, nixtla_client_historic, nixtla_client_anomaly_detection and nixtla_client_cross_validation. If you have long series, you can use max_insample_length to only plot the last N historical values (the forecast will always be plotted in full).