Introduction to valetr

José de Mello

2019-08-08

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.

Functions

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.

Examples

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 2019-08-08 and queries using the arguments recent* are referencing the date in which this vignette was created.

getSeriesData() in action

Core 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:

Now that the series has been properly assembled, we use ggplot2 to draw both series:

Retrieve monetary aggregates

‘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:

#>                                        label
#> 2416 Adjustments to M2+ (gross) (Unadjusted)
#> 2417                M2+ (gross) (Unadjusted)
#> 2418       M2+ (gross) (Seasonally adjusted)
#> 2423               M2++ (gross) (Unadjusted)
#> 2424      M2++ (gross) (Seasonally adjusted)
#> 2425                M1+ (gross) (Unadjusted)
#> 2426       M1+ (gross) (Seasonally adjusted)
#> 2427               M1++ (gross) (Unadjusted)
#> 2428      M1++ (gross) (Seasonally adjusted)
#>                                                    link      name
#> 2416    https://www.bankofcanada.ca/valet/series/V37251    V37251
#> 2417 https://www.bankofcanada.ca/valet/series/V41552788 V41552788
#> 2418 https://www.bankofcanada.ca/valet/series/V41552798 V41552798
#> 2423 https://www.bankofcanada.ca/valet/series/V41552790 V41552790
#> 2424 https://www.bankofcanada.ca/valet/series/V41552801 V41552801
#> 2425    https://www.bankofcanada.ca/valet/series/V37258    V37258
#> 2426    https://www.bankofcanada.ca/valet/series/V37151    V37151
#> 2427    https://www.bankofcanada.ca/valet/series/V37259    V37259
#> 2428    https://www.bankofcanada.ca/valet/series/V37152    V37152

The resulting object series can then be used to retrieve the series’ data using series[["name"]].

Retrieve series details with 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)
#> 
Retrieving series labels and names. This process may take a few minutes...16.67% completed...
Retrieving series labels and names. This process may take a few minutes...33.33% completed...
Retrieving series labels and names. This process may take a few minutes...50.00% completed...
Retrieving series labels and names. This process may take a few minutes...66.67% completed...
Retrieving series labels and names. This process may take a few minutes...83.33% completed...
Retrieving series labels and names. This process may take a few minutes...100.00% completed...

This new series then allows the user to browse the many types of exchange rates:

head(fxsInfo)
#>            group_name                     group_label
#> 1 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#> 2 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#> 3 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#> 4 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#> 5 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#> 6 FX_RATES_RECIPROCAL Daily reciprocal exchange rates
#>                                                                                                                                             group_desc
#> 1 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#> 2 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#> 3 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#> 4 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#> 5 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#> 6 Daily average reciprocal exchange rates - published once each business day by 16:30 ET. All Bank of Canada exchange rates are indicative rates only.
#>   series_label                                       series_link
#> 1      CAD/AUD https://www.bankofcanada.ca/valet/series/FXCADAUD
#> 2      CAD/BRL https://www.bankofcanada.ca/valet/series/FXCADBRL
#> 3      CAD/CNY https://www.bankofcanada.ca/valet/series/FXCADCNY
#> 4      CAD/EUR https://www.bankofcanada.ca/valet/series/FXCADEUR
#> 5      CAD/HKD https://www.bankofcanada.ca/valet/series/FXCADHKD
#> 6      CAD/INR https://www.bankofcanada.ca/valet/series/FXCADINR
#>   series_name
#> 1    FXCADAUD
#> 2    FXCADBRL
#> 3    FXCADCNY
#> 4    FXCADEUR
#> 5    FXCADHKD
#> 6    FXCADINR

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.