getSeriesData: Retrieves series' observations

In valetr: Interface to Bank of Canada's 'Valet' API

Description

valetr workhorse function. getSeriesData() retrieves observations from one or more series. This list may have one or more components. Each component is a series. This function accepts query arguments as specified on the API's manual.

Usage

getSeriesData(series, ...)

Arguments

series	character string of length >= 1. It accepts both series' link and their name only (see Details).
...	additional API's query arguments. See Details

Details

series

The argument series accepts a character vector in which each element is either a series link or a series name. getSeriesData() does not throw an error if some components do not have a valid name or link in the API. Instead, getSeriesData() issues a warning message with the series and API error message details. Additionally, the final output removes elements without a valid link. If all components in series do not have a valid address then the function throws an error.

...

The following arguments are accepted in ...: start_date, end_date, recent, recent_weeks, recent_months, recent_years. These are the API's options for time subsetting (see API documentation). Only start_date and end_date can be jointly used in .... Using any other combination of two or more arguments causes getSeriesData() to accept only one of them according to a pre-established hierarchy. This argument hierarchy causes the function to ignore the additional arguments. The hiearchy flows as follows:

• start_date and end_date

• recent

• recent_weeks

• recent_months

• recent_years

The function converts numeric inputs to recent.

The series observations may have a frequency that is not compatible to the query (i.e. recent_weeks query in a monthly series). Valet API converts the query time interval into the corresponding frequency of the series. If the time interval component is less than the most recent observation in the series, getSeriesData() returns a data.frame with a single row containing the series information. This behaviour allows getSeriesData() to return some series for which there is a valid interval. Also note that any invalid arguments passed to ... is ignored during execution. For more details on the arguments' input format, see examples, the package's vignette and Valet's documentation.

Value

An object of class list of one or more data.frames with n x 5 dimensions each. The colums are respectively: series_name, series_label, series_desc, d (observation date) and v (series values).

Examples

### step 1: find the series link or name
# get series info
seriesInfo <- getSeriesInfo(patternGroupLabel="(?i)consumer price",
                            patternSeriesLabel="(?i)seasonally")

# use link from resulting object to get series obs
series <- getSeriesData(seriesInfo[["series_link"]])

#### query example ####
# ex1: start and end date
series <- getSeriesData(seriesInfo[["series_link"]],
                        start_date="2010-01-01", end_date="2012-01-01")

# ex2: the most recent 10 obs
series <- getSeriesData(seriesInfo[["series_link"]], recent=10L)

# ex3: most recent weeks
series <- getSeriesData(seriesInfo[["series_link"]], recent_weeks=20L)

# ex4: most recent months
series <- getSeriesData(seriesInfo[["series_link"]], recent_months=29L)

# ex4: most recent years
series <- getSeriesData(seriesInfo[["series_link"]], recent_years=20L)

valetr documentation built on Aug. 9, 2019, 5:06 p.m.