In this section we discuss some of the basic ways in which the package can be used.
Interface with the Database
BETSsearch
Because the database is large, it was necessary to develop a way of searching for series using the metadata, i.e., a search tool that used some of the information about the series as keywords.
The BETSsearch function performs searches in each field of the metadata table described in Section Database. It naturally allows combinations of these characteristics, making searches more flexible. Note that access to the BETS database is by means of the sqldf package, which makes the processing of searches sufficiently fast and ensures that the package performs well in any environment.
The BETSsearch prototype has the form:
BETSsearch(description, src, periodicity, unit, code, view = TRUE, lang = "en")
where the arguments are, respectively
description - A character. A search string to look for matching series descriptions.src - A character. The source of the data.periodicity - character. The frequency with which the series is observed.unit - A character. The unit in which the data were measured.code - An integer. The unique code for the series in the BETS database.view - A boolean. By default, TRUE. If FALSE, the results will be shown directly on the R console.lang - A character. Search language. By default, “en”, for English. A search can also be performed in Portuguese by changing the value to “pt”.
To refine the search, there are syntax rules for the parameter description:
To look for alternative words, separate them by blank spaces. Example: description = 'core ipca' means that the description of the series should contain “core” and “ipca”.
To search for complete expressions, put them inside ‘’. Example: description = 'index and 'core ipca'' means that the description of the series should contain “core ipca” and “index”.
To exclude words from the search, insert a ~ before each word. Example: description = 'ipca ~ core' means that the description of the series should contain “ipca” and should not contain “core”.
To exclude all the expressions from a search, as in the previous item, place them inside ‘’ and insert a ~ before each of them. Example: description = '~ index 'core ipca'' means that the description of the series should contain “index” and should not contain “core ipca”.
It is possible to search for or exclude certain words as long as these rules are obeyed.
A blank space is not required after the exclusion sign (~), but is required after each expression or word.
Some examples of how this function is used are given below. We have not shown the results in some cases as the output can be a very long table. However, we guarantee that all the calls work and invite the reader to test them.
# Some examples
BETSsearch(description = "sales ~ retail",view = F)
BETSsearch(description = "'sales volume index' ~ vehicles",view = F)
BETSsearch(description = "'distrito federal'", periodicity = 'A', src = 'IBGE',view = F)
# Search for accumulated GDP series
BETSsearch(description = "gdp accumulated", unit = "US$", view = F)
For further information on BETSsearch, including valid values for each field, consult the reference manual by typing ?BETSsearch in the R console.
BETSget
BETSget only works with the reference code for the series, which is obtained using BETSsearch. The command for this function takes the form:
BETSget(code, data.frame = FALSE)
The parameter code is obviously mandatory. The optional argument data.frame represents the type of object that will be returned. Its default value is FALSE, indicating that the object returned by the function will be a ts ( time series ). If data.frame = TRUE, the series will be stored in an object of type data.frame.
We will extract two series that we looked up previously.
# Get the 12-month cumulative GDP series in dollars
gdp_accum <- BETSget(4192)
window(gdp_accum, start = c(2014,1))
#Get the series for the GDP of the Federal District at market prices
gdp_df <- BETSget(23992, data.frame = T)
head(gdp_df)
save
To allow greater flexibility in the way BETS series are stored, files containing the series can be created in proprietary formats, i.e., formats associated with proprietary software. Basically, save extracts the time series from the database in the package in the form of a data.frame and creates a file in the specified format. There is a table in the file in which the first column contains the dates and the second, the data.
There are three variations of this function, whose prototypes are shown below:
saveSas(code, data = NULL, file.name = "series")
saveSpss(code, data = NULL, file.name = "series")
saveStata(code, data = NULL, file.name = "series")
Again, the parameter code receives the code for the series. The user can provide his own series with the argument data, which can be a data.frame or a ts. There is no need to add the extension to the file name in the parameter file.name.
Some examples of how this function is used are:
# Save the series for the net public debt in the default Excel format
saveStata(code = 2078, file.name = "series_stata.dta")
# Save the series for the net public debt in the default Excel format
saveStata(code = 2078, file.name = "series_stata.dta")
# Save any series in SPSS format
my.series <- BETSget(4447)
saveSpss(data = my.series, file.name = "series_spss")
Some Additional Functions
ere we are going to discuss some of the most special BETS functions.
chart
chart was originally designed to be a private function for use with dashboard. However, we felt it would be very helpful for users to have a way to obtain the dashboard graphs separately so that they could include them in their own work.
The chart prototype is:
chart(ts, file = NULL, open = TRUE, lang = "en", params = NULL)
The parameter ts takes one of several predefined graph options or a user defined series. There is also the option of saving the output in the working directory by defining the name of the file with the parameter file. If the file should be opened after it has been created, open should be set to TRUE. The parameter params is reserved for graphs of the user’s own series, i.e., series that are not predefined. It is a list that can contain the field codace, which receives a Boolean and indicates whether shaded areas corresponding to recessions identified by CODACE (FGV/IBRE) should be drawn, and the field start, which specifies what the start date for the series should be. As the graph concerns the economic scenario, the end date cannot be changed and is always the last item of data available.
Let us look at two examples of how chart is used. The outputs are displayed in the figures below.
# Uncertainty Index chart
chart(ts = 'iie_br', file = "iie_br", open = TRUE)
# Leading and Coincident Labor Indicators charts
chart(ts = "lab_mrkt", file = "lab_mrkt.png", open = TRUE)
For a complete list of the available graphs, consult the chart reference manual.
dashboard
In a previous section, we said that BETS includes a powerful tool for scenario analysis, the dashboards. Currently, we provide two options of dashboards: a business cycle and a macroeconomic situation dashboard. We also plan to extend the dashboards to cover other items in addition to those that are implemented.
dashboard(type = "business_cycle", charts = "all", saveas = NA, parameters = NULL)
To create a dashboard, we call dashboard, setting the type parameter either to business_cycle or “macro_situation”. It generates a .pdf and, if type is set to “busines_cycle”, one of its five pages is going to look similar to that in the next figure. In the example, the user chooses to save the file with the name survey.pdf. The graphs shown can also be chosen by the user with the charts parameter, which is “all” by default. The reference manual contains a complete list of the available graphs.
dashboard(type = "business_cycle", saveas = "survey.pdf")
The macroeconomic situation dashboard allows the user to insert a custom explanatory text, as well as a personal logo, email and website. For instance, the call below generates a four page dashboard whose first page is shown below.
parameters = list(author = "FGV/IBRE",
url = "http://portalibre.fgv.br/",
text = "text.txt",
logo = "logo_ibre.png")
dashboard(type = "macro_situation", parameters = parameters)
The main advantage of such dashboards is that they are a convenient instrument to quickly understand the subject they are about. Their values are always the most recent ones, they are organized in well defined sections and its desing is highly informative.
