---
title: "Historical Forecast"
output: 
  rmarkdown::html_vignette:
    toc: true 
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Historical Forecast}
  %\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)
```

## 1. TimeGPT Historical Forecast
When generating a forecast, sometimes you might be interested in forecasting the historical observations. These predictions, known as **fitted values**, can help you better understand and evaluate a model's performance over time. 

`TimeGPT` has a method for generating fitted values, and users can call it from `nixtlar`. This vignette will explain how to do this. It assumes you have already set up your API key. If you haven't done this, please read the [Get Started](https://nixtla.github.io/nixtlar/articles/get-started.html) vignette first.  

## 2. Load data 
For this vignette, we'll use the electricity consumption dataset that is included in `nixtlar`, which contains the hourly prices of five different electricity markets. 

```{r}
df <- nixtlar::electricity
head(df)
```

## 3. Forecast historical data 
To generate a forecast for the historical data, use `nixtlar::nixtla_client_historic`, which should include the following parameters: 

- **df**: The time series data, provided as a data frame, tibble, or tsibble. It must include at least two columns: one for the timestamps and one for the observations. The default names for these columns are `ds` and `y`. If your column names are different, specify them with `time_col` and `target_col`, respectively. If you are working with multiple series, you must also include a column with unique identifiers. The default name for this column is `unique_id`; if different, specify it with `id_col`.
- **level**: The prediction intervals for the forecast. 

```{r}
nixtla_client_fitted_values <- nixtla_client_historic(df, level = c(80,95))
head(nixtla_client_fitted_values)
```

Notice that there are no fitted values for some of the initial observations. This is because `TimeGPT` requires a minimum number of values to generate a forecast for the historical data. 

All the fitted values are generated using a rolling window, meaning that the fitted value for observation $T$ is generated using the first $T-1$ observations. 

### 3.1 Fitted values from `nixtlar::nixtla_client_forecast`
`nixtlar::nixtla_client_historic` is the dedicated function that calls `TimeGPT`'s method for generating fitted values. However, you can also use `nixtlar::nixtla_client_forecast` with `add_history=TRUE`. This will generate both a forecast for the historical data and for the next $h$ future observations. 

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