Skip to content

Latest commit

 

History

History
206 lines (164 loc) · 6.64 KB

README.md

File metadata and controls

206 lines (164 loc) · 6.64 KB
Raw

https://github.com/bank-of-england/boeCharts.git

Data Classification

Bank of England Data Classification: OFFICIAL BLUE

Overview

boeCharts is an R package to help you create charts that are in-line with the Bank’s chart design guidelines, recommended (and designed) for use in conjunction with ggplot2.

It also contains design patterns for approximating charts found within flagship publications, including:

N.B. this is still a maturing project. Feedback/issues/contributions appreciated. If you are reporting a bug/error and/or requesting a new feature, please try and use the boeCharts backlog. For questions and other discussion, please use the Data Community.

Installation

boeCharts is not likely to be submitted to CRAN. Get the latest development version from GitHub:

remotes::install_github('bank-of-england/boeCharts', ref = "public")

Usage

Complementing a ggplot2 worflow

boeCharts provides native support for use with ggplot2 (a popular R graphics library). You can use scale_[colour|fill]_[continuous|discrete]_boe functions for adopting Bank colour palettes within charts generated by ggplot2, and theme_xxx functions for applying full chart styles supported by boeCharts.

A minimal example

First, load packages:

library(boeCharts)
library(ggplot2)
library(palmerpenguins) # for example purposes only
library(scales) # for date examples

Here is an out-of-the-box ggplot2 chart.

ggplot(penguins, aes(flipper_length_mm, body_mass_g, color = species)) +
  geom_jitter()

Custom themes can be applied to ggplot objects as additional “layers”. As mentioned above, all boeCharts theme functions are prefixed by theme_ e.g. theme_overground() applies the Bank Overground chart theme:

ggplot(penguins, aes(flipper_length_mm, body_mass_g, color = species)) +
  geom_jitter() +
  # add Bank Overground theme
  theme_overground()

Custom ggplot scales help with applying Bank colour palettes. In this case, the points can be coloured with a “vibrant” Bank colour combination variant, via scale_colour_discrete_boe(), again as an additional ggplot layer:

ggplot(penguins, aes(flipper_length_mm, body_mass_g, color = species)) +
  geom_jitter() +
  theme_overground() +
  # add a "vibrant" Bank colour combination
  scale_colour_discrete_boe(palette = "vibrant_c")

Now, switching in the Bank’s chart design guidelines theme and colours. Additionally, scale_y_continuous() is used to move the y-axis across to the right.

ggplot(penguins, aes(flipper_length_mm, body_mass_g, color = species)) +
  geom_jitter() +
  # add visual identity theme
  theme_boe_identity() +
  # add a "vibrant" Bank colour combination
  scale_colour_discrete_boe(palette = "boe_identity") +
  # move the y-axis to the right
  scale_y_continuous(
    position = "right", sec.axis = dup_axis(labels = NULL)
    ) +
  theme(axis.title.y.left = element_blank())

An in-depth example

Another ggplot2 + boeCharts creation, this time investigating some more customization options, including:

  • automatic axis breaks/limits (using boe_breaks|limits_date|numeric())
  • direct line labels (using position_voronoi())
  • strong horizontal line at zero
# create chart
chart <- ggplot(data = FANG, aes(x = date, y = close, colour = symbol)) +
  # add lines + hide legend
  geom_line(lwd = 0.75, lineend = "round", show.legend = FALSE) +
  # add series labels + hide legend
  geom_text(
    aes(label = symbol), position = position_voronoi(), 
    family = "Calibri", show.legend = FALSE
    ) +
  # add some chart labels
  labs(
    title = "Chart 1.2: Historical FANG stock prices",
    subtitle = "Stock price at the close of trading (USD), 2013-2016",
    caption = caption_boe(source = "Investopedia"),
    x = NULL, y = NULL
    ) +
  # use 'highlights' palette
  scale_colour_discrete_boe(palette = "boe_identity") +
  # add Bank Overground theme
  theme_boe_identity() +
  # apply custom axis settings
  scale_y_continuous(
    expand = c(0, 0), breaks = boe_breaks_numeric(), 
    limits = boe_limits_numeric(), position = "right"
    ) +
  scale_x_date(
    expand = c(0, 0), labels = scales::label_date_short(),
    breaks = boe_breaks_date(), limits = boe_limits_date()
    ) +
  add_hline0() # strong line at zero

chart

Markdown theme variants

A Markdown variant of each {boeCharts} theme has been made with a md_ suffix, like theme_mpr_md(). These themes add support for rendering text as markdown, thanks to the ggtext package. Here’s an example:

chart +
  theme_boe_identity_md() +
  labs(
    title = "**Chart A.2** Historical FANG stock prices",
    subtitle = "Stock price at the close of trading (USD), 2013-2016",
    caption = caption_boe(source = "Investopedia")
    )

Using custom fonts

boeCharts helps you safely import and use fonts other than the basic fonts R already uses (with help from the extrafont package). These fonts can be imported using an associated import_ utility function. For example, to import Calibri (used by default in some boeCharts themes), you should run the import_calibri() function. If you want to use fonts in PDF (or Postscript) output files, set the boeCharts.loadfonts option to TRUE.

N.B. the font import step only needs to be run once on your machine. Fonts will be loaded automatically when you load boeCharts in future R sessions.