---
title: "BIS"
author: "Stefan Angrick"
date: "`r Sys.Date()`"
vignette: >
  %\VignetteIndexEntry{BIS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: rmarkdown::html_vignette
---

The `BIS` package provides an `R` interface to data hosted by the [Bank for International Settlements](https://www.bis.org), specifically the [single-file data sets](https://www.bis.org/statistics/full_data_sets.htm) available on the BIS homepage.

## Installing the package

You can install the package from CRAN or GitHub.

```{r install, eval=FALSE, message=FALSE, warning=FALSE}
library(devtools)
install_github("stefanangrick/BIS")  # GitHub
install.packages("BIS")              # CRAN
```

## Example usage

To start using the package, load it into your R session.

```{r loading, eval=FALSE, message=FALSE, warning=FALSE}
library("BIS")
```

Next, retrieve a list of available data sets using the `get_datasets()` function.

```{r datasets, eval=FALSE, message=FALSE, warning=FALSE}
ds <- get_datasets()
head(ds, 20)
```

The `get_datasets()` function returns a [tibble](https://tibble.tidyverse.org/) data frame listing available data sets. Use the `url` column as input for the `get_bis()` function to download, parse, and import the corresponding data set.

For example, to import monthly-frequency data on [central banks' policy rates](https://www.bis.org/statistics/cbpol.htm), use the following code:

```{r rates, eval=FALSE, message=FALSE, warning=FALSE}
rates <- get_bis(ds$url[ds$id == "WS_CBPOL_csv_flat"])
head(rates)
```

To plot the data with [ggplot2](https://ggplot2.tidyverse.org), run the following:

```{r plot, eval=FALSE, message=FALSE, warning=FALSE}
library("dplyr")
library("ggplot2")
library("zoo")

rates_plot <- subset(rates, ref_area %in% c("US", "XM", "JP", "GB", "CH", "CA"))
rates_plot <- subset(rates, ref_area %in% c("US: United States",
                                            "XM: Euro area",
                                            "JP: Japan",
                                            "GB: United Kingdom",
                                            "CH: Switzerland",
                                            "CA: Canada"))
rates_plot <- mutate(rates_plot, time_period =
                       as.Date(as.yearmon(time_period, format = "%Y-%m")))

ggplot(rates_plot, aes(time_period, obs_value, color = ref_area)) +
  geom_line(show.legend = FALSE) +
  facet_wrap(~ref_area) +
  labs(title = "Central bank policy rates",
       subtitle = "% per annum", x = NULL, y = NULL)
```

Note that BIS data sets use various time formats. The [zoo](https://cran.r-project.org/package=zoo) package (e.g., `as.yearmon()`) can handle most of these formats.

## Reading locally stored files

In some cases, the BIS homepage may only be accessible through a web browser, preventing the programmatic retrieval of data sets directly within R. When this occurs, users can manually download the files and use the `read_bis()` function to parse them.

To read a locally stored CSV file, use the following code:

```{r localcsv, eval=FALSE, message=FALSE, warning=FALSE}
df <- read_bis("WS_CBPOL_csv_flat.csv")
```

To read a locally stored ZIP file, use this code:

```{r localzip, eval=FALSE, message=FALSE, warning=FALSE}
df <- read_bis(.unzip_file("WS_CBPOL_csv_flat.zip"))
```

## Retrieving individual data series

To retrieve individual data series instead of full data sets, consider using the BIS [SDMX RESTful API](https://stats.bis.org/api-doc/v1/#/). The [rsdmx R package](https://cran.r-project.org/package=rsdmx) supports processing SDMX data in R. The latest [development version](https://github.com/opensdmx/rsdmx) of `rsdmx` includes a BIS connector to streamline the process.

## Note

This package is neither officially related to nor endorsed by the [Bank for International Settlements](https://www.bis.org/). It is based on a fork of [CC0](https://cran.r-project.org/src/contrib/Archive/BIS/)-licensed [code by expersso](https://github.com/expersso/BIS). Please avoid overloading the BIS servers with unnecessary requests.