---
title: "EPE"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{EPE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Loads data from the Energy Research Company (EPE), a Brazilian public company that works closely with the Brazilian Ministry of Mines and Energy (MME) and other agencies to ensure the sustainable development of Brazil's energy infrastructure. EPE's duty on that mission is to support MME with quality research and studies in order to aid Brazil's energy infrastructure planning.

As for now, there are two different datasets available for download: the Energy Consumption Per Class and the National Energy Balance. Both of them were obtained from the [EPE website](https://www.epe.gov.br/sites-pt/publicacoes-dados-abertos/publicacoes/).

#### Energy Consumption Per Class

The Energy Consumption Per Class dataset provides monthly data about energy consumption and consumers from 2004 to 2022, for each class of energy consumption.

The different classes are Total consumption (and consumers), Industrial consumption (and consumers), Residential consumption (and consumers), Commercial consumption (and consumers), Captive consumption\* and Other consumption (and consumers).\*\*

*Note that there is no consumer data for 'Captive' class at all.

\*\*There is also no consumer data for 'Industrial', 'Commercial' and 'Other' classes when the geographical level is 'Subsystem' or 'Region'.

There are three different aggregation levels: 
The Region level encompasses the five Brazilian geographical regions (North, Northeast, Midwest, Southeast and South).
The Subsystem level encompasses the five Brazilian Electric Subsystems (North, Northeast, Southeast/Midwest, South, Isolated Systems).
The State level encompasses the 26 Brazilian States and the Federal District.

#### National Energy Balance
The National Energy Balance is a thorough and extensive research developed and published by EPE that contains useful data about energy consumption, generation, exportation and many more subjects.

As for now, the National Energy Balance dataset provides yearly data about energy generation per source of production. The sources can be divided into two groups: the renewable sources (hydro, wind, solar, nuclear, thermal, sugar_cane_bagasse, firewood, black_liquor) and the non-renewable sources (steam_coal, natural_gas, coke_oven_gas, fuel_oil, diesel).

The dataset has information at the Brazilian state level, including the Federal District, from 2011 to 2021 and also indicates whether the state is in the Legal Amazon or not.




***
**Options:**

  1. **dataset**: there are two choices:
      * `"energy_consumption_per_class"`: monthly energy consumption and consumers by State, Region or Electric Subsystem
      * `"national_energy_balance"`: yearly energy generation per source, by State

  2. **raw_data**: there are two options:
      * `TRUE`: if you want the data as it is originally.
      * `FALSE`: if you want the treated version of the data. 
      
  3. **geo_level**: only applies to the `"energy_consumption_per_class"` dataset. 
      * `"state"`
      * `"subsystem"`

  4. **language**: you can choose between Portuguese `("pt")` and English `("eng")`
  
***

**Examples:**  
  
```{r eval=FALSE}
# download treated data about energy consumption at the state level
clean_epe <- load_epe(
  dataset = "energy_consumption_per_class",
  geo_level = "state",
  raw_data = FALSE
)
```
