nixtlar: A Software Development Kit for 'Nixtla”s 'TimeGPT'

Description

A Software Development Kit for working with 'Nixtla”s 'TimeGPT', a foundation model for time series forecasting. 'API' is an acronym for 'application programming interface'; this package allows users to interact with 'TimeGPT' via the 'API'. You can set and validate 'API' keys and generate forecasts via 'API' calls. It is compatible with 'tsibble' and base R. For more details visit https://docs.nixtla.io/.

Author(s)

Maintainer: Mariana Menchero mariana@nixtla.io (First author and maintainer)

Other contributors:

• Nixtla (Copyright held by 'Nixtla') [copyright holder]

See Also

Useful links:

• https://nixtla.github.io/nixtlar/

• https://docs.nixtla.io/

• https://github.com/Nixtla/nixtlar

• Report bugs at https://github.com/Nixtla/nixtlar/issues

Generate output dates for forecast method. This is a private function of 'nixtlar'

Description

Generate output dates for forecast method. This is a private function of 'nixtlar'

Usage

.generate_output_dates(df_info, freq, h)

Arguments

Value

A data frame with dates for the forecast.

Examples

## Not run: 
  dates_df <- .generate_output_dates(df_info, freq, h)

## End(Not run)

Get NIXTLA_API_KEY from options or from .Renviron This is a private function of 'nixtlar'

Description

Get NIXTLA_API_KEY from options or from .Renviron This is a private function of 'nixtlar'

Usage

.get_client_steup()

Value

If available, the NIXTLA_API_KEY. Otherwise it returns an error and a message asking the user to set the 'API' key.

Examples

## Not run: 
  .get_api_key()

## End(Not run)

Retrieve parameters for 'TimeGPT' model This is a private function of 'nixtlar'

Description

Retrieve parameters for 'TimeGPT' model This is a private function of 'nixtlar'

Usage

.get_model_params(model, freq)

Arguments

Value

A list with the model's input size and horizon

Examples

## Not run: 
  .get_model_params(model, freq)

## End(Not run)

Obtain level from quantiles This is a private function of 'nixtlar'

Description

Obtain level from quantiles This is a private function of 'nixtlar'

Usage

.level_from_quantiles(quantiles)

Arguments

Value

A list containing the level vector and a data frame with the quantiles and their corresponding levels.

Examples

.level_from_quantiles(c(0.1, 0.5, 0.9))

Make requests to the 'TimeGPT' API This is a private function of 'nixtlar'

Description

Make requests to the 'TimeGPT' API This is a private function of 'nixtlar'

Usage

.make_request(base_url, api_key, payload_list)

Arguments

Value

List representing the JSON response from the API endpoint.

Examples

## Not run: 
  response <- .make_request(base_url, api_key, payload_list)

## End(Not run)

Convert period or offset aliases to a character string recognized by R. This is a private function of 'nixtlar'

Description

Convert period or offset aliases to a character string recognized by R. This is a private function of 'nixtlar'

Usage

.r_frequency(freq)

Arguments

Value

A character string recognized by R for generating a regular sequence of times.

Examples

.r_frequency("MS")   # Returns "month"
.r_frequency("10h")  # Returns "10 h"
.r_frequency("h")    # Returns "h" (unchanged)

A function used by httr2::req_retry() to determine if the response represents a transient error This is a private function of 'nixtlar'

Description

A function used by httr2::req_retry() to determine if the response represents a transient error This is a private function of 'nixtlar'

Usage

.transient_errors(resp)

Arguments

Value

TRUE if the response status is 500 or 502, FALSE otherwise.

Examples

## Not run: 
.transient_errors(resp)

## End(Not run)

Validate future exogenous variables (if applicable) This is a private function of 'nixtlar'

Description

Validate future exogenous variables (if applicable) This is a private function of 'nixtlar'

Usage

.validate_exogenous(df, h, X_df)

Arguments

Value

Returns a vector with the exogenous variable names if the validation is successful. If the validation fails, it stops execution and returns an error message, indicating what went wrong.

Examples

## Not run: 
df <- nixtlar::electricity_exo_vars
X_df <- nixtlar::electricity_future_exo_vars
.validate_exogenous(df, h=24, X_df)

## End(Not run)

Electricity dataset

Description

Contains prices of different electricity markets.

Usage

electricity

Format

electricity

A data frame with 8400 rows and 3 columns:

unique_id

Unique identifiers of the electricity markets.

ds

Date in format YYYY:MM:DD hh:mm:ss.

y

Price for the given market and date.

Source

https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short.csv

Electricity dataset with exogenous variables

Description

Contains prices of different electricity markets with exogenous variables.

Usage

electricity_exo_vars

Format

electricity_exo_vars

A data frame with 8400 rows and 12 columns:

unique_id

Unique identifiers of the electricity markets.

ds

Date in format YYYY:MM:DD hh:mm:ss.

y

Price for the given market and date.

Exogenous1

An external factor influencing prices. For all markets, some form of day-ahead load forecast.

Exogenous2

An external factor influencing prices. For "BE" and "FR" markets, the day-ahead generation forecast. For "NP", the day-ahead wind generation forecast. For "PJM", the day-ahead load forecast in a specific zone. For "DE", the aggregated day-ahead wind and solar generation forecasts.

day_0

Binary variable indicating weekday.

day_1

Binary variable indicating weekday.

day_2

Binary variable indicating weekday.

day_3

Binary variable indicating weekday.

day_4

Binary variable indicating weekday.

day_5

Binary variable indicating weekday.

day_6

Binary variable indicating weekday.

Source

https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short.csv

Future values for the electricity dataset with exogenous variables

Description

Contains the future values of the exogenous variables of the electricity dataset (24 steps-ahead). To be used with electricity_exo_vars.

Usage

electricity_future_exo_vars

Format

electricity_future_exo_vars

A data frame with 120 rows and 11 columns:

unique_id

Unique identifiers of the electricity markets.

ds

Date in format YYYY:MM:DD hh:mm:ss.

Exogenous1

An external factor influencing prices. For all markets, some form of day-ahead load forecast.

Exogenous2

An external factor influencing prices. For "BE" and "FR" markets, the day-ahead generation forecast. For "NP", the day-ahead wind generation forecast. For "PJM", the day-ahead load forecast in a specific zone. For "DE", the aggregated day-ahead wind and solar generation forecasts.

day_0

Binary variable indicating weekday.

day_1

Binary variable indicating weekday.

day_2

Binary variable indicating weekday.

day_3

Binary variable indicating weekday.

day_4

Binary variable indicating weekday.

day_5

Binary variable indicating weekday.

day_6

Binary variable indicating weekday.

Source

https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-future-ex-vars.csv

Infer frequency of a data frame.

Description

Infer frequency of a data frame.

Usage

infer_frequency(df, freq)

Arguments

Value

The inferred frequency.

Examples

df <- nixtlar::electricity
freq <- NULL
infer_frequency(df, freq)

Sequential version of 'nixtla_client_cross_validation' This is a private function of 'nixtlar'

Description

Sequential version of 'nixtla_client_cross_validation' This is a private function of 'nixtlar'

Usage

nixtla_client_cross_validation(
  df,
  h = 8,
  freq = NULL,
  id_col = "unique_id",
  time_col = "ds",
  target_col = "y",
  level = NULL,
  quantiles = NULL,
  n_windows = 1,
  step_size = NULL,
  finetune_steps = 0,
  finetune_loss = "default",
  clean_ex_first = TRUE,
  model = "timegpt-1"
)

Arguments

Value

A data frame with 'TimeGPT”s cross validation result.

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("YOUR_API_KEY")
  df <- nixtlar::electricity
  fcst <- nixtlar::nixtla_client_cross_validation(df, h = 8, id_col = "unique_id", n_windows = 5)

## End(Not run)

Sequential version of 'nixtla_client_detect_anomalies' This is a private function of 'nixtlar'

Description

Sequential version of 'nixtla_client_detect_anomalies' This is a private function of 'nixtlar'

Usage

nixtla_client_detect_anomalies(
  df,
  freq = NULL,
  id_col = "unique_id",
  time_col = "ds",
  target_col = "y",
  level = c(99),
  clean_ex_first = TRUE,
  model = "timegpt-1"
)

Arguments

Value

A data frame with the anomalies detected in the historical period.

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("YOUR_API_KEY")
  df <- nixtlar::electricity
  fcst <- nixtlar::nixtla_client_anomaly_detection(df, id_col="unique_id")

## End(Not run)

Sequential version of 'nixtla_client_forecast' This is a private function of 'nixtlar'

Description

Sequential version of 'nixtla_client_forecast' This is a private function of 'nixtlar'

Usage

nixtla_client_forecast(
  df,
  h = 8,
  freq = NULL,
  id_col = "unique_id",
  time_col = "ds",
  target_col = "y",
  X_df = NULL,
  level = NULL,
  quantiles = NULL,
  finetune_steps = 0,
  finetune_loss = "default",
  clean_ex_first = TRUE,
  add_history = FALSE,
  model = "timegpt-1"
)

Arguments

Value

'TimeGPT”s forecast.

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("YOUR_API_KEY")
  df <- nixtlar::electricity
  fcst <- nixtlar::nixtla_client_forecast(df, h=8, id_col="unique_id", level=c(80,95))

## End(Not run)

Sequential version of 'nixtla_client_historic' This is a private function of 'nixtlar'

Description

Sequential version of 'nixtla_client_historic' This is a private function of 'nixtlar'

Usage

nixtla_client_historic(
  df,
  freq = NULL,
  id_col = NULL,
  time_col = "ds",
  target_col = "y",
  level = NULL,
  quantiles = NULL,
  finetune_steps = 0,
  finetune_loss = "default",
  clean_ex_first = TRUE,
  model = "timegpt-1"
)

Arguments

Value

'TimeGPT”s forecast for the in-sample period.

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("YOUR_API_KEY")
  df <- nixtlar::electricity
  fcst <- nixtlar::nixtla_client_historic(df, id_col="unique_id", level=c(80,95))

## End(Not run)

Plot the output of the following nixtla_client functions: forecast, historic, anomaly_detection, and cross_validation.

Description

Plot the output of the following nixtla_client functions: forecast, historic, anomaly_detection, and cross_validation.

Usage

nixtla_client_plot(
  df,
  fcst = NULL,
  h = NULL,
  id_col = "unique_id",
  time_col = "ds",
  target_col = "y",
  unique_ids = NULL,
  max_insample_length = NULL,
  plot_anomalies = FALSE
)

Arguments

Value

Plot with historical data and 'TimeGPT”s output (if available).

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("YOUR_API_KEY")
  df <- nixtlar::electricity
  fcst <- nixtlar::nixtla_client_forecast(df, h=8, id_col="unique_id", level=c(80,95))
  nixtlar::timegpt_plot(df, fcst, h=8, id_col="unique_id")

## End(Not run)

Set base 'ULR' and 'API' key in global environment

Description

Set base 'ULR' and 'API' key in global environment

Usage

nixtla_client_setup(base_url = NULL, api_key = NULL)

Arguments

Value

A message indicating the configuration status.

Examples

## Not run: 
  nixtlar::nixtla_client_setup(
    base_url = "Base URL",
    api_key = "Your API key"
  )

## End(Not run)

Set 'API' key in global environment

Description

This function will be deprecated in future versions. Please use nixtla_client_setup instead.

Usage

nixtla_set_api_key(api_key)

Arguments

Value

A message indicating the 'API' key has been set in the global environment.

Examples

## Not run: 
  nixtlar::nixtla_set_api_key("Your API key")

## End(Not run)

Validate 'API' key

Description

Validate 'API' key

Usage

nixtla_validate_api_key()

Value

TRUE if the API key is valid, FALSE otherwise.

Examples

## Not run: 
  nixtlar::nixtla_client_setup(api_key = "Your API key")
  nixtlar::nixtla_validate_api_key()

## End(Not run)