README.Rmd

---
output: github_document 
---

<!-- 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%",
  fig.height = 5,
  fig.width = 7,
  fig.retina = 2
)
```

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

<!-- badges: start -->

[![R build status](https://github.com/MattCowgill/readrba/workflows/R-CMD-check/badge.svg)](https://github.com/MattCowgill/readrba/actions) [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![Codecov test coverage](https://codecov.io/gh/MattCowgill/readrba/branch/master/graph/badge.svg)](https://app.codecov.io/gh/MattCowgill/readrba?branch=master)
[![CRAN status](https://www.r-pkg.org/badges/version/readrba)](https://CRAN.R-project.org/package=readrba)
<!-- badges: end -->

Get data from the [Reserve Bank of Australia](https://rba.gov.au/statistics/tables/) in a [tidy](https://tidyr.tidyverse.org/articles/tidy-data.html) [tibble](https://tibble.tidyverse.org)! 

## Installation
Install from CRAN using:
```{r eval=FALSE}
install.packages("readrba")
```

Or install the development version from GitHub:
```{r eval=FALSE}
remotes::install_github("mattcowgill/readrba")
```

## Examples
```{r library, message = FALSE}
library(ggplot2)
library(dplyr)
library(readrba)
```

### Quick examples
With just a few lines of code, you can get a data series from the RBA and visualise it!

Here's the unemployment rate:
```{r}
unemp_rate <- read_rba(series_id = "GLFSURSA") 

unemp_rate %>%
  ggplot(aes(x = date, y = value)) +
  geom_line() +
  theme_minimal() +
  labs(title = "Unemployment rate (actual)")
```

And you can also easily get the RBA's public forecasts - from 1990 to present -
and visualise those. Here's every public forecast of the unemployment rate the
RBA has made over the past three decades:

```{r}
unemp_forecasts <- rba_forecasts() %>%
  filter(series == "unemp_rate")

unemp_forecasts %>%
  ggplot(aes(x = date, 
             y = value, 
             group = forecast_date, 
             col = forecast_date)) +
  geom_line() +
  theme_minimal() +
  labs(title = "Unemployment rate (RBA forecasts)")
```


### Reading RBA data
There primary function in {readrba} is `read_rba()`.

Here's how you fetch the current version of a single RBA statistical table: table G1, consumer price inflation using `read_rba()`:

```{r}
cpi_table <- read_rba(table_no = "g1")
```

The object returned by `read_rba()` is a tidy tibble (ie. in 'long' format):

```{r}
head(cpi_table)
```

You can also request multiple tables. They'll be returned together as one tidy tibble:

```{r}
rba_data <- read_rba(table_no = c("a1", "g1"))

head(rba_data)

unique(rba_data$table_title)
```

You can also retrieve data based on the unique RBA time series identifier(s). For example, to getch the consumer price index series only:
```{r}
cpi_series <- read_rba(series_id = "GCPIAG")
head(cpi_series)
unique(cpi_series$series_id)
```

The convenience function `read_rba_seriesid()` is a wrapper around `read_rba()`. This means `read_rba_seriesid("GCPIAG")` is equivalent to `read_rba(series_id = "GCPIAG")`.

By default, `read_rba()` fetches the current version of whatever table you request. You can specify the historical version of a table, if it's available, using the `cur_hist` argument:

```{r hist}

hist_a11 <- read_rba(table_no = "a1.1", cur_hist = "historical")

head(hist_a11)
```

### Browsing RBA data
Two functions are provided to help you find the table number or series ID you need. These are `browse_rba_tables()` and `browse_rba_series()`. Each returns a tibble with information about the available RBA data. 

```{r browse}
browse_rba_tables()
```
```{r browse_series}
browse_rba_series()
```

You can specify a search string to filter the tables or series, as in:
```{r browse-search}
browse_rba_tables("inflation")
```

### RBA forecasts
The function `rba_forecasts()` provides easy access to all the RBA's public
forecasts of key economic variables since 1990. The function scrapes the 
RBA website to obtain the latest Statement on Monetary Policy forecasts.

```{r forecasts}
rba_forecasts()
```

If you just want the latest forecasts, you can request them:
```{r latest-forecasts}
rba_forecasts(all_or_latest = "latest")
```

## Data availability

The `read_rba()` function is able to import most tables on the [Statistical Tables](https://rba.gov.au/statistics/tables/) page of the RBA website. These are the tables that are downloaded when you use `read_rba(cur_hist = "current")`, the default. 

`read_rba()` can also download many of the tables on the [Historical Data](https://rba.gov.au/statistics/historical-data.html) page of the RBA website. To get these, specify `cur_hist = "historical"` in `read_rba()`. 

### Historical exchange rate tables
The historical exchange rate tables do not have table numbers on the RBA website. They can still be downloaded, using the following table numbers:

```{r echo=FALSE}
ex_rates <- dplyr::filter(readrba:::table_list, grepl("ex", no)) 

ex_rates <- dplyr::select(ex_rates, `Table title` = title, `table_no` = no)

knitr::kable(ex_rates)
```

### Non-standard tables
`read_rba()` is currently only able to import RBA statistical tables that are formatted in a (more or less) standard way. Some are formatted in a non-standard way, either because they're distributions rather than time series, or because they're particularly old. 

Tables that are **not** able to be downloaded are:

```{r echo=FALSE}
nonreadable <- dplyr::filter(readrba:::table_list, readable == FALSE)
nonreadable <- dplyr::select(nonreadable, `Table title` = title, table_no = no, current_or_historical)
knitr::kable(nonreadable )
```

## Resolving network issues by manually setting the download method

Certain corporate networks restrict your ability to download files in an R session. On some of these networks, the `"wininet"` method must be used when downloading files. Users can specify the method that will be used to download files by setting the `"R_READRBA_DL_METHOD"` environment variable. 

For example, the following code sets the environment variable for your current session: 

```{r, eval = FALSE}
Sys.setenv("R_READRBA_DL_METHOD" = "wininet")
```

You can add `"R_READRBA_DL_METHOD"` to your .Rprofile to have this persist across sessions.

If you have other issues using `{readrba}` in your corporate environment, I would appreciate you opening an issue on GitHub.

## Issues and contributions

I welcome any feature requests or bug reports. The best way is to file a [GitHub issue](https://github.com/MattCowgill/readrba/issues). 

I would welcome contributions to the package. Please start by filing an issue, outlining the bug you intend to fix or functionality you intend to add or modify.

## Disclaimer

This package is not affiliated with or endorsed by the Reserve Bank of Australia. All data is provided subject to any conditions and restrictions set out on the RBA website.