Problem Set - Macroeconomic Patterns with FREDR”

What’s an API?

API is short for application programming interface. An API provides an interface between your computer and the data you are interested in. Someone has done all the hard data collection work for you, and you get access to it without any hassle! No scrolling through long excel documents and struggling to convert them into tibbles. API’s are great for two reasons: first, you can retrieve data at your convenience. Second, they make your analysis replicable.

In this problem set, we’ll plot some macroeconomic time series. We’ll use US data provided by the Federal Reserve Bank through their Fred API:

The FRED® API is a web service that allows developers to write programs and build applications that retrieve economic data from the FRED® and ALFRED® websites hosted by the Economic Research Division of the Federal Reserve Bank of St. Louis.

Basic Set-up

Before you can complete this problem set, you’ll need to carry out the following steps:

  1. Install the fredr package. The package is available on CRAN, so you can install it using the following command: install.packages("fredr"). Alternatively, you can install it by clicking on the “Packages” tab in RStudio and followed by “Install” and searching for fredr.
  2. Create a FRED account here. After creating your account, login and generate an API key. Save this key in your password manager or a text file on your machine. Keep it secret, keep it safe!
  3. Paste the following code into the R console to make sure Enter the following code at the console to check that everything is working correctly:
library(fredr)
freder_set_key('PUT YOUR FRED KEY HERE!')
fredr(series_id = "GDP")

You should obtain output that looks like this:

# A tibble: 317 × 5
   date       series_id value realtime_start realtime_end
   <date>     <chr>     <dbl> <date>         <date>      
 1 1946-01-01 GDP         NA  2025-04-30     2025-04-30  
 2 1946-04-01 GDP         NA  2025-04-30     2025-04-30  
 3 1946-07-01 GDP         NA  2025-04-30     2025-04-30  
 4 1946-10-01 GDP         NA  2025-04-30     2025-04-30  
 5 1947-01-01 GDP        243. 2025-04-30     2025-04-30  
 6 1947-04-01 GDP        246. 2025-04-30     2025-04-30  
 7 1947-07-01 GDP        250. 2025-04-30     2025-04-30  
 8 1947-10-01 GDP        260. 2025-04-30     2025-04-30  
 9 1948-01-01 GDP        266. 2025-04-30     2025-04-30  
10 1948-04-01 GDP        273. 2025-04-30     2025-04-30  
# ℹ 307 more rows
# ℹ Use `print(n = ...)` to see more rows

If so, congratulations: you are now able to retrieve macroeconomic time series from FRED!

Protecting Your Key

You will need to use your API key to complete this exercise. But you should never share your API key with anyone else. Your API key is like a password: you wouldn’t want to paste that into your problem set solution!

To avoid this, we’re going to set up what is called an “environment variable”. An environment variable is a way to store sensitive information, like passwords or API keys, in a secure way. This way, you can use your API key in your code without having to hard-code it into your scripts.

You only have to do this once for each machine and each key. After you set it up, you can use the API key in your code without having to worry about it being exposed.

The easiest approach is to first install the usethis package. This package provides a function called edit_r_environ() that opens your .Renviron file in RStudio. You can then add your API key to this file, and it will be available in your R session. First run the following lines of code in the console to install the package and open the .Renviron file:

install.packages("usethis")
usethis::edit_r_environ()

This will open a text file in RStudio called .Renviron in your home directory. This file is used to store environment variables for R. If you don’t have this file, it will be created for you.

In this file, you can add your API key by typing the following line:

FRED_API_KEY="PUT YOUR KEY HERE"

Make sure to replace PUT YOUR KEY HERE with your actual API key. Save the file and close it. Now you can retrieve your key in R by running the following command:

my_key <- Sys.getenv("FRED_API_KEY")

This will retrieve your API key and store it in the variable my_key. You can then use this variable to set your API key in the fredr package, after you’ve loaded it, by running the following command:

fredr_set_key(my_key)

Now you’re ready to begin the exercises!

Questions

Exercise 1: Getting familiar with the FRED API

  1. Follow the steps from above to set up fredr and your API key, verifying that everything works as expected.

  2. Use the command fredr(series_id = "GDP") to retrieve the GDP time series and store it in a tibble called gdp. Display this tibble.

  3. In this problem set we will focus on data from 2000 onward. Type ?fredr into the console and study the function’s documentation. Modify your API call from the preceding part to retrieve quarterly GDP data from January 01, 2000, and save it in a tibble called gdp. Hint: If you want to know what other time series fredr has you can use fredr_category_children(category_id = 0) to navigate the data directory.

  4. Next, we’ll retrieve unemployment rates. To find the correct series_id, use fredr’s text search: simply run fredr_series_search_text("unemployment"). After identifying the correct id, save monthly data on US unemployment rates from January 2000 in a tibble called u.

Exercise 2: Plotting macroeconomic patterns

  1. Plot the monthly unemployment rates stored in u using ggplot2. Add a title, subtitle and axis labels to make it clear what you are plotting. You may find it helpful to consult the FRED documentation of the variable for details on the unemployment rate definition. Add a caption citing your datav source.

  2. What do you see? Describe how unemployment rates change during the business cycle.

  3. Next, plot GDP. Add a title, subtitle, axis labels and a caption. Consult the FRED documentation for their GDP variable for this. What does your plot tell you?

  4. Plotting total GDP gives you a good sense of long-run economic growth. To zoom in on business cycle changes, we’ll plot GDP growth. Modify gdp and create two new variables: qoq for quarter-over-quarter (QoQ) growth, and qoq_annualised for annualised quarter-over-quarter growth. Why do you get a warning “Removed 1 row containing missing values”? Hint: Quarter-over-quarter growth is defined as the percentage difference between the current quarter and the quarter in \(t-1\). You’ll find the lag() function helpful for constructing this measure.

  5. Plot both measures of quarterly growth in the same plot. Assign different colours to both series manually and add a legend with scale_color_manual(). Add an appropriate title, subtitle, axis labels and caption. Hint: Don’t set a y inside ggplot(aes()). Add the y aesthetic in your line geom instead.

  6. Remember how I said APIs are great for replicability? We can pull QoQ growth from the FRED API directly! This will also fix our “Removed 1 row containing missing values” error. Define a new tibble called gdp_growth containing quarterly growth rates from January 2000. Does it match your qoq variable? Hint: Set units = "pch" inside your API call.

Exercise 3: Spotting recessions

During a recession, economic production goes down and unemployment increases – that’s conventional wisdom. Surprisingly, academic economics doesn’t get much more specific than that. We don’t have a clear, unified definition for what makes a recession! Here’s how the NBER Business Cycle Dating Committee defines a recession:1

The NBER’s definition emphasizes that a recession involves a significant decline in economic activity that is spread across the economy and lasts more than a few months.

Despite the lack of a clear definition, the NBER identifies recessions. The committee assessments of when a recession starts and ends are publicly available here. I’ve saved you some legwork and coded a tibble with the start and end dates of the last three US recessions:

recessions <- tibble(
  start = as.Date(c("2001-03-01", "2007-12-01", "2020-02-01")),
  end   = as.Date(c("2001-11-30", "2009-06-30", "2020-04-30"))
)

You’ll build on your plots from the previous exercise to shade recessions in the time series, recreating this NBER plot.

  1. Plot unemployment rates and add shading for recession periods using geom_rect(). To use the recession dates in recessions, set inherit.aes = FALSE and specify a new data input inside geom_rect(). Hint: Add the shading before the time series geom. In ggplot2, layer order matters: earlier layers are drawn underneath later ones.

  2. Plot QoQ GDP growth with recession shading, using the API data saved in gdp_growth.

  3. Combine the plots next to each other using the patchwork package. Add a joint title and caption citing FREDR and the NBER as sources. Hint: Look at plot_annotation() for this last step.

Footnotes

  1. The late Edward Leamer, in his 2008 book “Macroeconomic Patterns and Stories”, has opinions about this definition: “Sorry, ye wise men of the NBER, this is not a definition of a recession. This is only a list of incidental symptoms. It’s like saying SARS is a high fever and a cough.”↩︎