knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) library(valetr)
valetr
provides an interface to the Bank of Canada’s
'Valet' API —read the API's terms and
condtions. Some of the data
available include key monetary policy variables —i.e. Total CPI and M
aggregates.
The 'Valet' API also provides a route to Foreign Exchange Rates in RSS. This route returns the most recent foreign exchange rate —one observation only. This functionality is not included in valter
for now.
See 'Valet' documentation for an overview of the data structure.
valetr
has three functions. Two functions help the user to explore series' and groups' labels whereas getSeriesData()
performs the data extraction from the API:
regexSeriesLabel Matches a `pattern` to the label of one or more series. Returns a `data.frame` with label, link and name getSeriesInfo Allows to pattern-match both group and series labels. This function returns a `data.frame` with a more complete description of a series. It includes their group information (name, label, desc.) as well as the series descriptive components getSeriesData Extracts one or more series by specifying their name or link --vector can contain a mix of both. It also allows the insertion of the API's query parameters.
To reproduce the examples below, you need to have data.table
and ggplot2
;&empbesides valetr
of course. Also note that this vignette was created on r Sys.Date()
and queries using the arguments recent*
are referencing the date in which this vignette was created.
getSeriesData()
in actionCore CPI is an indicator of changes in food and energy prices only. Total CPI tracks the change of a fixed basket of goods and services purchased by Canadian consumers. Core CPI is expected to display higher volatility than Total CPI. However, Bank of Canada's Core CPI excludes some volatile items from the Core CPI's basket. Are these exclusions enough to make Core CPI less volatile than BoC's Total CPI? The Bank of Canada's inflation targetting regime looks at Total CPI when setting a target &emp;and establishing lower and upper bands. The Bank watches Total CPI fluctuates over time and it may decide to raise or cut the overnight rate if Total CPI is approaching its upper or lower band respectively.
Let's get both inflation measures for the last 20 years with getSeriesData()
. The goal is to look at the CPIs' percentage change over a 12 month period. Note the query parameter recent_years=21L
because there is a one-year loss to calculate the 12 month percentage variation. The reason to look at the 12 month percentage change in the inflation indicators is that the BoC's actions take longer to have an effect on the economy:
cpis <- getSeriesData(series=c("V41690973","V41693242"), recent_years=21L) # get data # load data.table library(data.table) # calcule the CPI % cpis <- lapply(cpis, function(x){ # change last col name to cpi names(x)[length(x)] <- "value" x[["value"]] <- as.numeric(x[["value"]]) # cpi val as numeric x[["d"]] <- format(as.Date(x[["d"]]), "%Y-%m") # format date data.table::setDT(x) # calculate % change over the past 12 mo x[, chng := value/data.table::shift(value, n = 12) - 1] # remove NAs (due to lag) x <- x[!is.na(chng), ] return(x) }) # bind datasets cpis <- do.call(rbind, cpis) head(cpis)
Now that the series has been properly assembled, we use ggplot2
to draw both series:
# compare series library(ggplot2) ggplot(cpis, aes(y=chng, x=d, group=series_label, colour=series_label) ) + geom_line() + labs(x=NULL, y = "% change over the past 12 months", title="Core CPI series appears less\nvolatile than Total CPI", caption=paste0("Valet API series: ", paste0(unique(cpis[["series_name"]]),collapse =","))) + scale_y_continuous(labels=function(x) paste0(round(x*100, 2), "%")) + theme_minimal() + theme(axis.text.x = element_blank(), panel.grid = element_blank(), legend.title = element_blank(), legend.position = c(.8,.85))
'Valet' houses monetary aggregate data as well &emp;M series. We use the function regexSeriesLabel()
to search for the series:
# capture m aggregates series <- regexSeriesLabel(pattern="(?i)m\\d\\+{1,} \\(gross\\)")
regexSeriesLabel()
returns a data.frame
with the series' label, link and name:
# capture m aggregates
series
The resulting object series
can then be used to retrieve the series' data using series[["name"]]
.
getSeriesInfo()
The main difference between regexSeriesLabel()
and getSeriesInfo()
is that the latter can also search patterns in the series' group label via the patternGroupLabel
argument. If patternGroupLabel
is empty, getSeriesInfo()
will pull all series information in the API which may take a few minutes. The other argument is patternSeriesLabel
which is pattern-matching on the series labels &emp;same as regexSeriesLabel()
. The idea of having a search on groups is that it allows the exploration of series' names given that the API houses thousands of series. For instance, one may not know beforehand the labels for the exchange rate series. Searching by group allows the user to interactively browse for series in an R session:
fxsInfo <- getSeriesInfo(patternGroupLabel = "exchange rate", ignore.case=TRUE)
This new series then allows the user to browse the many types of exchange rates:
head(fxsInfo)
As seen above, the data.frame
returned in getSeriesInfo()
has six columns with the group name, label and description, and the series label, link and name. It is therefore a more complete picture compared to the one in regexSeriesLabel()
.
Read more about the API here.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.