Retrieving Debt-GDP ratios from FRED

Processing Two Time Series

This note provides an example of retrieving two time series from the FRED database maintained at the St. Louis Fed. This is a database of over 500,000 time series from multiple sources including US government and international sources. There are several R packages which can be used to access FRED. The package alfred is simplest for retrieving a series without documentation because it uses an internal application API key. However, it cannot retrieve the associated series information. In this example, we will use fredr which includes access to the basic series documentation. It requires that the user open a one-time account to obtain an API key.  The actual script and the log file are in a corresponding PDF in the downloads section of the Jacobson Consulting web site.

Packages USED

The key package used in this vignette is the fredr package which accesses the FRED api. Key packages include

  • dplyr – for processing the tibble prior to conversion to xts
  • ggplot2 – part of tidyverse for plotting the results
  • fredr – the retrieval package to be used.

Retrieving the DATA

The first step in the analysis is to go the FRED site at https://fred.stlouisfed.org to open and account and obtain an API key. This is done only once and can be used for multiple R scripts. In this case, the key is saved in a CSV file in the folder being used for this example. It must be retrieved from this CSV file for each run to initialize the calls to the API.

# this routine uses fredr to access the basic documentation

setwd("D:\\OneDrive\\fred_test")
library(tidyverse)
library(fredr)
library(ggplot2)
#set up the key
user_api_key<-read.csv("fred_api_key.csv",stringsAsFactors=FALSE)
fredr_set_key(user_api_key$fredapi)

The next stage is to define the names for the series to be retrieved. The fredr package has search options which would facilitate the lookup of series ids. For simplicity, this was done in this example using the St. Louis web site. The next set of code retrieves the information about the series first. Each call to the routine fredr_series returns a tibble for one series. These are merged using bind_rows to get one tibble which is printed and written out as a csv for documentation purposes. The routine fredr_series_observations returns the actual data as a tibble.

#define the series
us_ratio<-"DEBTTLUSA188A"
cdn_ratio<-"DEBTTLCAA188A"
#first, we retrieve the information about the two series for documentation purposes
us_debt_ratio_info<-fredr_series(us_ratio)
cdn_debt_ratio_info<-fredr_series(cdn_ratio)
series_info<-bind_rows(us_debt_ratio_info,cdn_debt_ratio_info)
print(as.data.frame(series_info))
write.csv(series_info,file="debt_series_info.csv")
#now get the data
us_debt_ratio<-fredr_series_observations(us_ratio)
cdn_debt_ratio<-fredr_series_observations(cdn_ratio)

The next stage is to bind the two tibbles into one for the purpose of plotting. The dplyr filter command is used to exclude earlier observations. Then ggplot from the ggplot2 library is used to prepare the chart.

#combine the two series into one tibble
plot_data<-bind_rows(us_debt_ratio,cdn_debt_ratio) %>%
filter(date >="2000-01-01")
#now start chart
debt_plot<-ggplot(plot_data, aes(x=date,y=value,group=series_id,colour=series_id))+
geom_line(size=1)+
theme(legend.position="bottom",legend.title=element_blank())+
scale_colour_hue(labels=c("Canada","United States"))+
labs(title=paste0(cdn_debt_ratio_info$title,"\n",us_debt_ratio_info$title),
y="Share of GDP",x=NULL,caption=paste("FRED update:",cdn_ratio,"/",
substr(cdn_debt_ratio_info$last_updated,1,10),"--",us_ratio,"/",
substr(us_debt_ratio_info$last_updated,1,10)))
ggsave(debt_plot,file="CAN_US_Debt_plot.png")

It should be noted that the variables named in the ggplot aes are specific to the fredr package. The titles retrieved in the info variables from FRED are used to prepare the chart title. A newline is generated in the title by including the string “\n”. The date of last update from the series information is used as part of the caption. The latter also includes the actual FRED mnemonics for documentation purposes.

The resulting chart is shown below.

CAN US Debt plot