---
title: "Overview of the RBNZ Package"
author: "Jasper Watson"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, echo = FALSE}

library(RBNZ)
```

# RBNZ

This package provides a convenient way of accessing the financial and economic data published by the Reserve Bank of New Zealand (RBNZ) on their website, https://www.rbnz.govt.nz/statistics. The data is provided in .xlsx files; this package will download those files and read them into R. A summary of the available data can be found at the end of this document.

The author has no affiliation with the RBNZ. The copyright for the data can be found at https://www.rbnz.govt.nz/about-our-site/terms-of-use.

## Usage

The function for downloading the data is `getSeries`. This takes as its first argument the name of the series and will return a list containing the fields "meta" and "data" which are data frames containing the metadata and actual data, respectively. Each column of the "data" data frame corresponds to a row of the "meta" data frame (except the first which is "Date").

```{r, echo = TRUE, eval = FALSE}
library(RBNZ)

## Not evaluated in this vignette.
b1 <- getSeries("B1")

plot(b1$data$Date, b1$data$UK_pound_sterling, type = "l")
```

Some of the datasets have different available formats. For example the B1 series contains exchange rate data in both daily and monthly form. The second argument of `getSeries` allows the user to specify which option they want, e.g. `getSeries('B1', 'monthly')`.

Each series has a help file so typing, for example, `?B1`, will tell you what options, if any, are available.

To speed things up the files can be saved on disk so that they don't have to always be re-downloaded even when there are no available updates. This is controlled by the `destDir` argument to `getSeries`, which can also be specified in your .Rprofile using `options(RBNZ.destDir = "path/to/stored/files")`.

By default, where a series has multiple files for a given option, only the most recent will be downloaded if `destDir` is provided and the files already exist. This is controlled by the `reloadOnlyLatest` argument to `getSeries`.

For a full description of the arguments of `getSeries`, see the package manual or function header.

### Cloudflare

The RBNZ website is behind Cloudflare so there are some initial steps the user must take.

One option is to email the RBNZ and request that your (static) public IP address be whitelisted. The email to contact is listed on their terms of service page [here](https://www.rbnz.govt.nz/about-our-site/terms-of-use).

The second option is to download the necessary files from the RBNZ website manually through your browser and then use this package to read and organise those files. This can be done by downloading the spreadsheets needed and saving them in a given directory without changing their file names.

For example for the B1 series a user could download through their browser the following spreadsheets:

* hb1-daily-1973-1998.xlsx
* hb1-daily-1999-2017.xlsx
* hb1-daily.xlsx

They could then load the data as follows:

``` r
library(RBNZ)

dat <- getSeries('B1', destDir = 'path_to_downloaded_files', cacheOnly = TRUE)
```

The monthly option can be used after downloading hb1-monthly.xlsx and hb1-monthly-1973-1998.xlsx.

This option is not ideal as the spreadsheets need to be manually downloaded every time you want them updated but for users who don't have a permanent public IP address they can get whitelisted this is the best that can be done.

## Non-standard Data

The majority of the datasets available are all stored in a similar format, with data organised by date and a standard set of metadata. There are a few series that do not follow this template, as indicated in the next section, and for these the spreadsheets are just downloaded and read into a list of data frames, one for each sheet, with some basic attempts at cleaning up dates, column headers, and so on.

## Available Data

```{r, echo = FALSE, eval = TRUE, tidy = FALSE}
x <- RBNZ:::availableData()
for (ii in seq_len(nrow(x))){
  if (nchar(x[ii, 3]) > 50)
    x[ii, 3] <- paste0(substring(x[ii, 3], 1, 47), '...')
}
print(x, row.names = FALSE)
```