---
title: "transformerForecasting R package"
author: "G H Harish Nayak "
date: "2025-02-08"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{user_guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
VignetteBuilder: knitr
Suggests: knitr, rmarkdown
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

options(rmarkdown.html_vignette.check_title = FALSE)
```

# <span style="color:blue">Package Requirements</span>
1. Latest version of Python
2. TensorFlow
3. Keras
4. Pandas

The `TRANSFORMER` function requires Python with TensorFlow and Keras installed. Without these, the function returns mock results for demonstration. We recommend users install the latest version of Python on their system. Then, create a Conda environment and install 
TensorFlow, Keras, and Pandas. If unfamiliar with these steps, follow the guide below.

## <span style="color:green">1. Installing TensorFlow</span>
After installing Python, run the R script below. It creates a conda environment and installs TensorFlow. If already installed, it skips the step.
```{r, eval=FALSE, include=TRUE}
install_r_tensorflow(python_path = "system_path_of_python.exe", env_name = "r-tensorflow")
```
Example system path for `python.exe`:
```{r, eval=FALSE, include=TRUE}
install_r_tensorflow(python_path = "C:/Users/User_name/AppData/Local/Programs/Python/Python312/python.exe", env_name = "r-tensorflow")
```

## <span style="color:green">2. Installing Keras</span>
After TensorFlow installation, install Keras in the virtual environment:
```{r, eval=FALSE, include=TRUE}
install_r_keras(tensorflow_python_path = "virtual_environment_path_of_python.exe", env_name = "r-tensorflow")
```
Example path:
```{r, eval=FALSE, include=TRUE}
install_r_keras(tensorflow_python_path = "C:/Users/kabil/Documents/.virtualenvs/r-tensorflow/Scripts/python.exe", env_name = "r-tensorflow")
```

## <span style="color:green">3. Installing Pandas</span>
Install Pandas using the following command:
```{r, eval=FALSE, include=TRUE}
install_r_pandas(tensorflow_python_path = "virtual_environment_path_of_python.exe", env_name = "r-tensorflow")
```
Example path:
```{r, eval=FALSE, include=TRUE}
install_r_pandas(tensorflow_python_path = "C:/Users/kabil/Documents/.virtualenvs/r-tensorflow/Scripts/python.exe", env_name = "r-tensorflow")
```

# <span style="color:blue">Running the Package</span>
Once setup is complete, run the R package using example or custom data.

## <span style="color:red">Using Example Data</span>
```{r, eval=FALSE, include=TRUE}
library(transformerForecasting)
data("S_P_500_Close_data")
df <- S_P_500_Close_data
```

## <span style="color:red">Running the TRANSFORMER Function</span>
```{r, eval=FALSE, include=TRUE}
result <- TRANSFORMER(
  df = df, 
  study_variable = "Price", 
  tensorflow_python_path = "C:/Users/kabil/Documents/.virtualenvs/r-tensorflow/Scripts/python.exe",
  env_name = "r-tensorflow",
  sequence_size = 10, 
  head_size = 128, 
  num_heads = 8, 
  ff_dim = 256, 
  num_transformer_blocks = 4, 
  mlp_units = c(128), 
  mlp_dropout = 0.3, 
  dropout = 0.2, 
  epochs = 100, 
  batch_size = 32, 
  patience = 15
)
```

# <span style="color:blue">Results</span>

### <span style="color:purple">Predictions</span>
The predicted values generated by the model.
```{r, eval=FALSE, include=TRUE}
result$PREDICTIONS
```

### <span style="color:purple">Error Metrics</span>

**Root Mean Squared Error (RMSE)** – Measures the average prediction error.
```{r, eval=FALSE, include=TRUE}
result$RMSE
```

**Mean Absolute Error (MAE)** – Shows the average absolute difference between actual and predicted values.
```{r, eval=FALSE, include=TRUE}
result$MAE
```

**Mean Absolute Percentage Error (MAPE)** – Represents prediction accuracy as a percentage.
```{r, eval=FALSE, include=TRUE}
result$MAPE
```

**Symmetric Mean Absolute Percentage Error (sMAPE)** – A variant of MAPE considering both over- and under-predictions.
```{r, eval=FALSE, include=TRUE}
result$sMAPE
```

**Relative Root Mean Squared Error (RRMSE)** – RMSE scaled by the mean of the actual values.
```{r, eval=FALSE, include=TRUE}
result$RRMSE
```

**Quantile Loss** – Used for probabilistic forecasting.
```{r, eval=FALSE, include=TRUE}
result$Quantile_Loss
```

### <span style="color:purple">Visualizations</span>

**Loss Plot** – Displays the loss curve over epochs.
```{r, eval=FALSE, include=TRUE}
result$Loss_plot
```
```{r, echo=FALSE, out.width = "500px"}
knitr::include_graphics("images/loss_plot.png", dpi = 72)
```

**Actual vs. Predicted** – Comparison plot.
```{r, eval=FALSE, include=TRUE}
result$Actual_vs_Predicted
```
```{r, echo=FALSE, out.width = "500px"}
knitr::include_graphics("images/act_vs_pred.png", dpi = 72)
```