-
Notifications
You must be signed in to change notification settings - Fork 7
/
get-started.Rmd
118 lines (88 loc) · 4.89 KB
/
get-started.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
---
title: "Get Started"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 2
vignette: >
%\VignetteIndexEntry{Get Started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
library(httptest2)
.mockPaths("../tests/mocks")
start_vignette(dir = "../tests/mocks")
original_options <- options("NIXTLA_API_KEY"="dummy_api_key", digits=7)
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7,
fig.height = 4
)
```
```{r}
library(nixtlar)
```
`nixtlar` provides an R interface to [Nixtla's TimeGPT](https://docs.nixtla.io/), 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](https://dashboard.nixtla.io/sign_in).
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
```{r eval=FALSE}
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.
```{r eval=FALSE}
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.
```{r eval=FALSE, message=FALSE}
library(usethis)
usethis::edit_r_environ()
```
This will open your `.Reviron` file. Place your API key here and named it `NIXTLA_API_KEY`.
```{r eval=FALSE}
# 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`.
```{r eval=FALSE}
# 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](https://nixtla.github.io/nixtlar/articles/setting-up-your-api-key.html) vignette. To learn more about how to use Azure, please refer to the [TimeGEN-1 Quickstart (Azure)](https://nixtla.github.io/nixtlar/articles/azure-quickstart.html).
### Validate your API key
If you want to validate your API key, call `nixtla_validate_api_key`.
```{r, eval=FALSE}
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.
```{r}
df <- nixtlar::electricity
head(df)
```
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`.
```{r}
nixtla_client_fcst <- nixtla_client_forecast(df, h = 8, level = c(80,95))
head(nixtla_client_fcst)
```
## 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).
```{r}
nixtla_client_plot(df, nixtla_client_fcst, max_insample_length = 200)
```
```{r, include=FALSE}
options(original_options)
end_vignette()
```