---
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_set_api_key` function 
`nixtlar` has a function to easily set up your API key for your current R session. Simply call 

```{r eval=FALSE}
nixtla_set_api_key(api_key = "paste 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. 

### 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, you first need to 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="paste 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, set your API key using the `nixtla_set_api_key` function. 

### 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, id_col = "unique_id", max_insample_length = 200)
```

```{r, include=FALSE}
options(original_options)
end_vignette()
```