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

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

```{r setup}
library(citmre)
```

The cITMre library—Colombian Index Tool (Market Rate Exchange)—responds to the researcher's economics and financial sciences needs to use the colombian Representative Market Rate Exchange. This package presents a practical solution for downloading the RMRE database. 

The tool allows us to obtain:

* Download the data series in daily, monthly, quarterly, and half-yearly frequencies.
* Can split the time series through start and end function
* Can transform the data set in log returns or level
* Can make a Dynamic graph through Plotly, or if is your preference can make a normal plot.

# Motivation

Obtaining information from the Colombian RMRE is relatively straightforward; the search in the official state database Portal de Datos Abiertos <www.datos.gov.co> allows the data to be downloaded in .xls or .csv. In economics or financial sciences, obtaining and loading this information into R can be frustrating, forcing many users to create a routine function linked to the database limited to the user's expertise. Thus, this tool aims to facilitate both the loading of data and the use of essential RMRE time series analysis tools.

Note: The information discounts weekends and holidays; the function approximates the nearest trade date.

# Applied Example

If you want to use `citmre`, perform the package installation process using `install.package("citmre")` or through CRAN and load the `library(citmre)` library.
Once the package is installed, use the `rmre_data()` function to obtain the total RMRE series (the Colombian state has RMRE data since 1991-12-02); the data loaded is an XTS series. This information can be plotted through `plot()`.

```{r plot_1, fig.dim = c(7, 5), fig.align = 'center'}
library(citmre)
head(rmre_data())
plot(rmre_data())
```

In economic or financial research, it is not necessary to take the whole time series; use `start_date` and `end_date` under the format "YYYYY-MM_DD" to obtain a specific start and end date. For example, we want to get the RMRE from March 18, 2005, to June 26, 2019, in an object called `data` simplifying function result.

```{r plot_2, fig.dim = c(7, 5), fig.align = 'center'}
data <- rmre_data(start_date = "2005-03-18", end_date = "2019-06-26")
head(data)
tail(data)
plot(data)
```

In some research, the historical volatility is expected to be analysed for advanced econometric or financial studies. It is possible to use the function `log_return=TRUE` to change the series to log return based on the formula: $lr(RMRE) = Ln(\frac {RMRE_t}{RMRE_{t-1}})$, in Default the series is presented in level data.

```{r plot_3, fig.dim = c(7, 5), fig.align = 'center'}
data_log <- rmre_data(start_date = "2005-03-18", end_date = "2019-06-26", log_return = TRUE)
head(data_log)
tail(data_log)
plot(data_log)
```

On some occasions, economic or financial variables do not necessarily use the same time-frequency of the daily series as in the RMRE. Colombia's GDP (Gross Domestic Product) is quarterly; therefore, the RMRE daily series must be transformed into a quarterly one. The `frequency` function displays the RMRE series in monthly (12), quarterly (4) and half-yearly (2) series. By default, the daily series will be (365). Frequencies can also be transformed to log_return

The `type` function can approximate the series on mean or last date data. When `type = "mean" is used, the series gets the average value of the series in frequency. If `type = "last_date" is used, the last data of the series is used in frequency. By default, the `type` is set to `last_date`.

```{r plot_456,fig.dim = c(7, 5), fig.align = 'center'}
# Monthly RMRE
data_m <- rmre_data(start_date = "1998-03-18", end_date = "2019-06-26", frequency = 12)
head(data_m)
tail(data_m)
plot(data_m)

# Quarterly
data_q <- rmre_data(start_date = "1998-03-18", end_date = "2019-06-26", frequency = 4, log_return = T)
head(data_q)
tail(data_q)
plot(data_q)

# Half-year
data_s <- rmre_data(start_date = "1998-03-18", end_date = "2019-06-26", frequency = 2, type = "mean")
head(data_s)
tail(data_s)
plot(data_s)
```

Finally, some researchers feel that displaying a dynamic graph increases the analysis and learning methods, which is why the `plot_data` option can display a Plotly line graph, allowing the user to analyse the data through the Viewer (See https://plotly.com/r/line-charts/>). This option works well with the other options of the `rmre_data` function.

```{r plotly, eval=FALSE}
# Monthly RMRE
rmre_data(start_date = "1998-03-18", end_date = "2019-06-26", frequency = 12, plot_data = T)
```

# Final considerations

This tool can be used for time series analysis with an xts class condition; therefore, the user can transform the series to ts if any tool conflicts with an xts series.

# References
Source: Portal de Datos Abiertos <www.datos.gov.co> 

