README.qmd

---
format: gfm
default-image-extension: ''
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    warning: false
    message: false
    dev: "ragg_png"
    tidy: "styler"
    fig.path: "man/figures/README-"
    dpi: 300
    out.width: "100%"
---

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

# tidyBdE <a href="https://ropenspain.github.io/tidyBdE/"><img src="man/figures/logo.png" alt="tidyBdE website" align="right" height="139"/></a>

<!-- badges: start -->

[![rOS-badge](https://ropenspain.github.io/rostemplate/reference/figures/ropenspain-badge.svg)](https://ropenspain.es/)
[![CRAN-status](https://www.r-pkg.org/badges/version/tidyBdE)](https://CRAN.R-project.org/package=tidyBdE)
[![CRAN-results](https://badges.cranchecks.info/worst/tidyBdE.svg)](https://cran.r-project.org/web/checks/check_results_tidyBdE.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/grand-total/tidyBdE?color=blue)](https://cran.r-project.org/package=tidyBdE)
[![On-CRAN](https://www.r-pkg.org/badges/ago/tidyBdE)](https://cran.r-project.org/web/checks/check_results_tidyBdE.html)
[![r-universe](https://ropenspain.r-universe.dev/badges/tidyBdE)](https://ropenspain.r-universe.dev/tidyBdE)
[![R-CMD-check](https://github.com/rOpenSpain/tidyBdE/actions/workflows/check-full.yaml/badge.svg)](https://github.com/rOpenSpain/tidyBdE/actions/workflows/check-full.yaml)
[![codecov](https://codecov.io/gh/ropenspain/tidyBdE/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropenspain/tidyBdE)
[![CodeFactor](https://www.codefactor.io/repository/github/ropenspain/tidybde/badge)](https://www.codefactor.io/repository/github/ropenspain/tidybde)
[![DOI](https://img.shields.io/badge/DOI-10.32614/CRAN.package.tidyBdE-blue)](https://doi.org/10.32614/CRAN.package.tidyBdE)
[![Project Status: Active -- The project has reached a stable, usable state and
is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

<!-- badges: end -->

**tidyBdE** is an API package that retrieves data from [Banco de
España](https://www.bde.es/webbe/en/estadisticas/recursos/descargas-completas.html).
The data is returned as a [tibble](https://tibble.tidyverse.org/), and the
package automatically detects the format of each time series (dates, characters,
and numbers).

## Installation

Install **tidyBdE** from [**CRAN**](https://CRAN.R-project.org/package=tidyBdE):

```{r}
#| eval: false
install.packages("tidyBdE")
```

You can install the developing version of **tidyBdE** with:

```{r}
#| eval: false
pak::pak("ropenspain/tidyBdE")
```

Alternatively, you can install **tidyBdE** using the
[r-universe](https://ropenspain.r-universe.dev/tidyBdE):

```{r}
#| eval: false
# Install tidyBdE in R:
install.packages(
  "tidyBdE",
  repos = c(
    "https://ropenspain.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```

## Examples

Banco de España (**BdE**) provides several time series, either produced by the
institution itself or compiled from other sources, such as
[Eurostat](https://ec.europa.eu/eurostat) or [INE](https://www.ine.es/).

The basic entry point for searching series is the time series catalog
information. You can search any series by name:

```{r}
#| label: search
#| results: false
library(tidyBdE)

# Load tidyverse for better handling
library(ggplot2)
library(dplyr)
library(tidyr)

# Search GBP on "TC" (exchange rate) catalog
xr_gbp <- bde_catalog_search("GBP", catalog = "TC")

xr_gbp |>
  select(Numero_secuencial, Descripcion_de_la_serie) |>
  # To table on document
  knitr::kable()
```

```{r}
#| echo: false
#| results: asis
xr_gbp |>
  select(Numero_secuencial, Descripcion_de_la_serie) |>
  # To table on document
  knitr::kable()
cat("<p class=\"caption\">Table 1: Search results</p>")
```

**Note that BdE metadata is currently only provided in Spanish.** The
institution is working on an English version. For now, search terms must be
provided in Spanish to retrieve results.

After we have found our series, we can load the series for the GBP/EUR exchange
rate using the sequential number reference (`Numero_Secuencial`) as follows:

```{r}
#| label: find
seq_number <- xr_gbp |>
  # First record
  slice(1) |>
  # Get id
  select(Numero_secuencial) |>
  # Convert to num
  as.double()

# Extract series
time_series <- bde_series_load(seq_number, series_label = "EUR_GBP_XR") |>
  filter(Date >= "2010-01-01" & Date <= "2020-12-31") |>
  drop_na()

time_series
```

### Plots

The package also provides a custom **ggplot2** theme based on BdE publications:

```{r}
#| label: chart
#| fig-asp: 0.7
#| fig-cap: EUR/GBP Exchange Rate (2010-2020)
ggplot(time_series, aes(x = Date, y = EUR_GBP_XR)) +
  geom_line(colour = bde_tidy_palettes(n = 1)) +
  geom_smooth(method = "gam", colour = bde_tidy_palettes(n = 2)[2]) +
  labs(
    title = "EUR/GBP Exchange Rate (2010-2020)",
    subtitle = "%",
    caption = "Source: BdE"
  ) +
  geom_vline(
    xintercept = as.Date("2016-06-23"),
    linetype = "dotted"
  ) +
  geom_label(aes(
    x = as.Date("2016-06-23"),
    y = .95,
    label = "Brexit"
  )) +
  coord_cartesian(ylim = c(0.7, 1)) +
  theme_tidybde()
```

The package also provides several "shortcut" functions for a selection of
relevant macroeconomic series, so there is no need to search for them in
advance:

```{r}
#| label: macroseries
#| fig-asp: 0.7
#| fig-cap: Spanish Economic Indicators (2010-2019)
# Data in "long" format

plotseries <- bde_ind_gdp_var("GDP YoY", out_format = "long") |>
  bind_rows(
    bde_ind_unemployment_rate("Unemployment Rate", out_format = "long")
  ) |>
  drop_na() |>
  filter(Date >= "2010-01-01" & Date <= "2019-12-31")

ggplot(plotseries, aes(x = Date, y = serie_value)) +
  geom_line(aes(color = serie_name), linewidth = 1) +
  labs(
    title = "Spanish Economic Indicators (2010-2019)",
    subtitle = "%",
    caption = "Source: BdE"
  ) +
  theme_tidybde() +
  scale_color_bde_d(palette = "bde_vivid_pal") # Custom palette on the package
```

### Palettes

Two custom palettes, based on those used by BdE in some publications, are
available.

These palettes can be applied to `ggplot2` plots using custom utilities included
in the package (see `help("scale_color_bde_d", package = "tidyBdE")`).

### A note on caching

You can use **tidyBdE** to create your own local repository in a given local
directory by passing the following option:

``` r
options(bde_cache_dir = "./path/to/location")
```

When this option is set, **tidyBdE** looks for cached files in the
`bde_cache_dir` directory and loads them, speeding up the process.

It is possible to update the data (i.e. after every monthly or quarterly data
release) with the following commands:

```{r}
#| eval: false
bde_catalog_update()

# In most functions using the option update_cache = TRUE

bde_series_load("SOME ID", update_cache = TRUE)
```

## Disclaimer

This package is in no way sponsored, endorsed, or administered by Banco de
España.

## Citation

```{r}
#| echo: false
#| results: asis
print(citation("tidyBdE"), style = "html")
```

A BibTeX entry for LaTeX users is

```{r}
#| echo: false
#| comment: ''
toBibtex(citation("tidyBdE"))
```