---
title: "How to use qualR"
author:
- name: Mario Gavidia-Calderón, Daniel Schuch & Maria de Fatima Andrade
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{How to use qualR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Context
Both the State of São Paulo and Rio de Janeiro have one of the most extensive 
air quality stations network in South America.
[CETESB QUALAR System](https://cetesb.sp.gov.br/ar/qualar/) provide to the user the air quality data from the State
of São Paulo. QUALAR System limits the download to one parameter from one air 
station for one year in a simple query (three parameter in advance query).
The data can have missing hours (e.g. due to calibration), 
the decimal separator is ",", and the output is a CSV file.
[data.rio](https://www.data.rio/maps/PCRJ::qualidade-do-ar-dados-hor%C3%A1rios/about) hosts the air quality information from Monitor Ar Program.
It is not an user-friendly API and the data needs the same preprocessor as the 
data from QUALAR System.

`qualR` surpasses these limitations and brings to your R session ready-to use 
data frames with the information of air quality station from the State of 
São Paulo and the city of Rio de Janeiro.

# Approach

`qualR` has the following functions:

* `cetesb_retrieve_param`: Download a list of different parameter from one air quality station (AQS) from CETESB QUALAR System.
* `cetesb_retrieve_pol`: Download criteria pollutants from one AQS from CETESB QUALAR System.
* `cetesb_retrieve_met`: Download meteorological parameters from one AQS from CETESB QUALAR System.
* `cetesb_retrieve_met_pol`: Download meteorological parameters and criteria pollutants from one AQS from CETESB QUALAR System.
* `monitor_ar_retrieve_param`: Download a list of different parameters from MonitorAr - Rio program.
* `monitor_ar_retrieve_pol`: Download criteria pollutants from one AQS from MonitorAr - Rio program.
* `monitor_ar_retrieve_met`: Download meteorological parameters from one AQS from MonitorAr - Rio program.
* `monitor_ar_retrieve_met_pol`: Download meteorological parameters and criteria pollutants from one AQS from MonitorAr - Rio Program.



# Example to download data from Rio de Janeiro

In this example we want to download one year PM10 concentration from an 
air quality station located in Rio de Janeiro downtown. We need to do the following:

1. Check for the code or abbreviation of the station.
```{r setup}
library(qualR)
monitor_ar_aqs
```
2. Check for the code or abbreviation of the parameters.
```{r}
monitor_ar_param
```
3. We have that the air quality station `code` is `CA` (Estação Centro), and
PM10 `code` is `PM10`. So we use the function `monitor_ar_retrieve_param()`.
```{r}
rj_centro <- monitor_ar_retrieve_param(start_date = "01/01/2019",
                                       end_date = "31/12/2019",
                                       aqs_code = "CA",
                                       parameters = "PM10")

head(rj_centro)
```
4. We can download multiple parameters too. For example, maybe we need to know 
the relationship between PM10 and Wind Speed. To do that we just need to 
define a vector with the parameters we need.
```{r}
to_dwld <- c("PM10", "Vel_Vento")

rj_ca_params <- monitor_ar_retrieve_param(start_date = "01/01/2019",
                                    end_date = "31/12/2019",
                                    aqs_code = "CA",
                                    parameters = to_dwld)
head(rj_ca_params)
```
5. Now we can make a simple plot
```{r fig.height=5, fig.width=5}
plot(rj_ca_params$ws, rj_ca_params$pm10,
     xlab = "Wind speed (m/s)",
     ylab = "",
     xlim = c(0,4),
     ylim = c(0,120))
mtext(expression(PM[10]~" ("*mu*"g/m"^3*")"), side = 2, line = 2.5)

```

# An example using `tidyverse`

`tidyverse` is a powerful collection of R package. Here is an example using `purrr`to download data from multiple stations and `ggplot2`to visualize the relation between Ozone and air temperature. 
As we know Ozone is formed by photochemical reaction which means the participation of solar radiation.

```{r}
library(qualR)
library(purrr)

# Retrieve data from all stations in Rio
rj_params <- purrr::map_dfr(.x = qualR::monitor_ar_aqs$code, 
                            .f = monitor_ar_retrieve_param,
                            start_date = "01/01/2020",
                            end_date = "31/12/2020",
                            parameters = c("O3", "Temp")
)
```

Now we can visualize all the data simultaneity using `ggplot2` facet:

```{r fig.height=5, fig.width=5}
library(magrittr)
library(ggplot2)

# making the graph with facet
rj_params %>% 
  ggplot() +
  geom_point(aes(x = tc, y = o3), size = 0.5,  alpha = 0.5) +
  labs(x = "Air temperature (º)",
       y = expression(O[3]~" ("*mu*"g/m"^3*")"),
       caption = "Source: Data from MonitorAr - Rio, retrieved with qualR R package. "
       )+
  theme_bw()+
  facet_wrap(~aqs)
```

PS: Special thanks to [@beatrizmilz](https://github.com/beatrizmilz) for inspiring this example.

# Compatibility with `openair`
`qualR` functions returns a completed data frame (i.e. missing hours padded out
with `NA`) with a `date` column in `POSIXct`. This ensure compatibility with the
`openair`package.

Here is the code to  use openair `timeVariation()` function. Note that no 
preprocessing is needed.
```{r fig.height=5, fig.width=5, eval=FALSE}
#install.package("openair")
library(openair)
openair::timeVariation(rj_centro, pollutant = "pm10")
```

# Example to download data from São Paulo State stations
To use `cetesb_retrieve` you first need to create an account in 
[CETESB QUALAR System](https://seguranca.cetesb.sp.gov.br/Home/CadastrarUsuario).
The `cetesb_retrieve` functions are similar as `monitor_ar_retrieve_param` functions, but 
they require the `username` and `password` arguments.
[Check this section](https://github.com/quishqa/qualR#a-better-way-to-save-your-credentials) on `qualR` README to safely configure your user name and 
password on your R session.

In this example, we download Ozone concentration from an air quality station 
located at Universidade de São Paulo (USP-Ipen) for August, 2021.
1. Check the station `code` or `name` 
```{r}
head(cetesb_aqs, 15)
```
2. Check ozone `code` or abbreviation
```{r}
head(cetesb_param, 15)
```
3. The air quality station is `95` and ozone code is `63`. So to retrieve the 
data we should use the `cetesb_retrieve_param`function like this:
```{r eval=FALSE}
usp_o3 <- cetesb_retrieve_param(username = my_user,
                                password = my_password,
                                parameters = "O3", # or 63
                                aqs_code = "Cid.Universitaria-USP-Ipen",  # or 95
                                start_date = "01/08/2021",
                                end_date = "31/08/2021")      
```



# More information
- You can check [`qualR` README](https://github.com/quishqa/qualR#readme) for more examples and good practices.
- You can also check [this tutorial](https://github.com/quishqa/qualR_tuto) for more examples of `qualR` and how it works
with `openair`.
