README.Rmd

---
output: github_document
html_preview: false
always_allow_html: true
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# meedr <img src='man/figures/logo.png' align="right" height="139" />

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/meedr)](https://CRAN.R-project.org/package=meedr)
[![R-CMD-check](https://github.com/schoulten/meedr/workflows/R-CMD-check/badge.svg)](https://github.com/schoulten/meedr/actions)
[![CRAN downloads](http://cranlogs.r-pkg.org/badges/grand-total/meedr?color=green)](https://cran.r-project.org/package=meedr)
<!-- badges: end -->

The goal of **meedr** is to provide quick and easy access to market expectations data to the main macroeconomic indicators in the Focus report, made available by the **Central Bank of Brazil** through the Expectations System data [API](https://dadosabertos.bcb.gov.br/). This data comes from several financial institutions, such as: banks, brokers, funds, consultancies, etc.

**Warning**: This package was definitively archived by CRAN on July 22, 2021 and is only available in this repository. Despite this, maintenance and bug fixes will continue to be done.

The **meedr** package offers an R interface to the API and other advantages:

- Use of a caching system with package `memoise` to speed up repeated requests of data;
- User can utilize all cores of the machine (parallel computing) when fetching a large batch of time series.

Check the [meedr pkgdown page](https://fortietwo.com/meedr/) for more general information ;)

## Installation

You can install the development version from [GitHub](https://github.com/schoulten/meedr) with:

```r
# install.packages("remotes")
remotes::install_github("schoulten/meedr")
```

## Features

- [get_monthly()](#get_monthly): Get data on monthly market expectations
- [get_quarterly()](#get_quarterly): Get data on quarterly market expectations
- [get_annual()](#get_annual): Get data on annual market expectations
- [get_inflation_12m()](#get_inflation_12m): Get data on market expectations for inflation over the next 12 months
- [get_monthly_top5()](#get_monthly_top5): Get data on monthly market expectations for the Top 5 indicators
- [get_annual_top5()](#get_annual_top5): Get data on annual market expectations for the Top 5 indicators
- [get_selic()](#get_selic): Get Selic market expectations data

## Example

These are some basic examples of using the package:

### get_monthly(){#get_monthly}

```{r, message=FALSE, warning=FALSE}
library(meedr)

# Monthly market expectations for IPCA indicator
ipca <- meedr::get_monthly(
  indicator      = "IPCA",
  first_date     = Sys.Date()-30,
  reference_date = format(Sys.Date(), "%m/%Y"),
  be_quiet       = TRUE
  )

head(ipca, 5)
```

### get_quarterly(){#get_quarterly}

```r
# Quarterly market expectations for GDP indicator
meedr::get_quarterly(
  indicator      = "PIB Total",
  first_date     = "2021-01-01",
  reference_date = paste0(lubridate::quarter(Sys.Date()), "/", lubridate::year(Sys.Date())),
  be_quiet       = TRUE
  )
```

### get_annual(){#get_annual}

```r
# Annual market expectations for SELIC and exchange rate (BRL) indicator
meedr::get_annual(
  indicator      = c("Selic", "Câmbio"),
  reference_date = format(Sys.Date(), "%Y"),
  be_quiet       = TRUE
  )
```

### get_inflation_12m(){#get_inflation_12m}

```r
# Inflation over the next 12 months
# First, and a suggestion, run this for using parallel computing:
future::plan(future::multisession, workers = floor(future::availableCores()/2))
meedr::get_inflation_12m(
  indicator   = c("IGP-DI", "IGP-M", "INPC", "IPA-DI", "IPA-M", "IPCA", "IPCA-15", "IPC-Fipe"),
  smoothed    = "yes",
  be_quiet    = FALSE, # display messages
  do_parallel = TRUE # turn on parallel computing
  )
```

### get_monthly_top5(){#get_monthly_top5}

```r
# Monthly market expectations for IGP-M indicator (Top 5 Focus)
meedr::get_monthly_top5(
  indicator  = "IGP-M",
  first_date = NULL, # get all data to current date
  calc_type  = "long",
  be_quiet   = TRUE
  )
```

### get_annual_top5(){#get_annual_top5}

```r
# Annual market expectations for SELIC indicator (Top 5 Focus)
meedr::get_annual_top5(
  indicator   = "Selic",
  detail      = "Fim do ano", # argument deprecated by API BCB-Olinda
  be_quiet    = TRUE,
  use_memoise = FALSE # disable caching system
  )
```

### get_selic(){#get_selic}

```{r}
df1 <- get_selic(indicator = "Selic", first_date = Sys.Date() - 30)
df1

df2 <- get_selic(indicator = "Selic", first_date = NULL, meeting = "R1/2024")
df2
```


## Related works

Check out some similar works:

- [rbcb](https://github.com/wilsonfreitas/rbcb): R interface to Brazilian Central Bank web services by @wilsonfreitas