Importing FRED Data to GAUSS

by Eric · Published December 15, 2022

Introduction

The GAUSS FRED database integration, introduced in GAUSS 23, is a time-saving feature that allows you to import FRED data directly into GAUSS. This means you have thousands of datasets at your fingertips without ever leaving GAUSS. These tools also ensure that FRED data is imported directly into a GAUSS dataframe format, which can eliminate hours of data cleaning and the headaches that come with it.

In today's blog, we will learn how to use the FRED import tools to:

• Search for a FRED data series.
• Import FRED data to GAUSS, including merging multiple series.
• Use advanced import tools to perform data transformations.

Getting Started

Requesting an API Key

Prior to importing any data from FRED using GAUSS you will need to request an API key from FRED. This can be done on the FRED API Request page. To request an API key you will need:

1. To create and/or login to a FRED account.
2. Provide a brief description of the program you intend to write. This can be simple such as, "Using GAUSS to conduct economic research."

Specifying your API key in GAUSS

You can set your API in GAUSS using any of the following methods:

1. Set the API key directly at the top of your program:

   FRED_API_KEY = "your_api_key"

2. Set the environment variable FRED_API_KEY to your API key.
3. Edit your gauss.cfg and modify the fred_api_key value:

   fred_api_key = your_api_key

Finding Your FRED Series

In order to download a series directly from FRED, we will need to know the series ID. However, this may not be something you know right offhand. Fortunately, we can use the fred_search procedure to find the proper series ID.

The fred_search procedure requires one input, a string specifying the search text. As an example, let's search for all series related to "producer price index":

fred_search("producer price index");

This prints a search report to the command window. The first five rows are:

frequency  frequency_short group_popularity              id     last_updated  observation_end observation_star       popularity     realtime_end   realtime_start seasonal_adjustm seasonal_adjustm            title            units      units_short
Monthly                 M        80.000000           PPIACO 2022-11-15 07:52       2022-10-01       1913-01-01        80.000000       2022-11-23       2022-11-23 Not Seasonally A              NSA Producer Price I   Index 1982=100   Index 1982=100
Monthly                 M        79.000000          WPU0911 2022-11-15 07:52       2022-10-01       1926-01-01        79.000000       2022-11-23       2022-11-23 Not Seasonally A              NSA Producer Price I   Index 1982=100   Index 1982=100
Monthly                 M        79.000000            PCEPI 2022-10-28 08:40       2022-09-01       1959-01-01        78.000000       2022-11-23       2022-11-23 Seasonally Adjus               SA Personal Consump   Index 2012=100   Index 2012=100
Monthly                 M        78.000000  PCU325211325211 2022-11-15 07:55       2022-10-01       1976-06-01        78.000000       2022-11-23       2022-11-23 Not Seasonally A              NSA Producer Price I Index Dec 1980=1 Index Dec 1980=1 

We can see that the FRED search report provides a thorough summary of related series. In addition to the id, which we will need to import the data from FRED, some other useful fields include:

• Frequency.
• Popularity.
• Last updated.
• Observation end.
• Observation start.
• Seasonal adjustment status.
• Units.

For our next steps, let's use the PPIACO series, which is the highest popularity series related to the search term Producer Price Index.

Importing Data From FRED

Loading A Single Series From FRED

Next, we will import the PPIACO series from the FRED database into GAUSS using the fred_load procedure.

The fred_load procedure requires one string input specifying the series ID to be loaded. To load the producer price data that we found with our FRED search, we will use the series ID PPIACO:

// Download all observations of 'PPIACO' into a GAUSS dataframe
PPI = fred_load("PPIACO");

We can examine the first five rows of the PPI dataframe using the head procedure:

// Print the first 5 rows of 'PPI'
head(PPI);

which reports

            date           PPIACO
      1913-01-01        12.100000
      1913-02-01        12.000000
      1913-03-01        12.000000
      1913-04-01        12.000000
      1913-05-01        11.900000 

We can also use the tail procedure to examine the last 5 rows of the PPI dataframe:

// Print the last 5 rows of 'PPI'
tail(PPI);

            date           PPIACO
      2022-06-01        280.25100
      2022-07-01        272.27800
      2022-08-01        269.46500
      2022-09-01        268.69300
      2022-10-01        265.19300

This shows us that the PPIACO data ranges from January, 1913 to October, 2022. Which is consistent with the observation start and end date reported in our FRED search.

Loading Multiple Series From FRED

The fred_load procedure can also be used to load multiple series from FRED simultaneously. To do this, we use a GAUSS formula string syntax, using + to add additional series IDs to our formula string.

// Load producer price
// and treasury bond data
macro_data = fred_load("PPIACO + T10Y2Y");

// Preview data
head(macro_data);

The preview of our data shows that our two series have been imported together and automatically merged by date:

            date           PPIACO           T10Y2Y
      1913-01-01        12.100000                .
      1913-02-01        12.000000                .
      1913-03-01        12.000000                .
      1913-04-01        12.000000                .
      1913-05-01        11.900000                . 

However, the preview doesn't necessarily give us reassurance that T10Y2Y was loaded properly because the values for the first five observations are all missing. Let's take a quick look at some summary statistics using dstatmt:

// Compute and print descriptive statistics
// for all variables in 'macro_data'
dstatmt(macro_data);

This prints a summary table to our Command Window:

-----------------------------------------------------------------------------
Variable    Mean   Std Dev  Variance     Minimum     Maximum   Valid  Missing
-----------------------------------------------------------------------------

date       -----     -----     -----  1913-01-01  2022-11-25   13048        0
PPIACO     74.57      66.3      4396        10.3       280.3    1318    11730
T10Y2Y    0.9146     0.903    0.8155       -2.41        2.91   11619     1429 

From this, we can tell that both series have been imported properly. However, they have different ranges, with both series having a number of missing values.

Plotting a FRED Series

It could be useful to view our FRED data before importing it into the GAUSS workspace. This can be done using the fred_load procedure with the plotXY.

To do this, we need to remember the dataframe returned from fred_load will always contain:

• A date variable named, date
• A variable for every series loaded named with the seriesID

As an example, let's consider viewing the FRED S&P 500 series with the series ID sp500:

plotXY(fred_load("sp500"), "sp500 ~ date");

Advanced Import Tools

One of most useful features of the GAUSS FRED import tools is that they can perform a number of data cleaning tasks at the time of import. In this section, we will look at how to use the FRED import tools to:

• Filter dates.
• Aggregate data.
• Perform data transformations.

The FRED Parameter List

GAUSS FRED functions use a parameter list for passing advanced settings. This list is constructed using the fred_set function.

The fred_set function creates a running list of parameters you want to pass to the FRED functions. It is specified by first listing a parameter name, then the associated parameter value.

For example:

// Create a FRED parameter list with
// 'frequency' set to 'q' (quarterly)
params_GDP = fred_set("frequency", "q");

If we wish to add additional parameters values we can update an existing parameter list:

// Set 'aggregation_method' to end-of-period
// in the previously created parameter list 'params_GDP'
params_GDP = fred_set("aggregation_method", "eop", params_GDP);

Or we can specify all parameters at the same time:

// Create a FRED parameter list with 2 settings at once.
params_GDP = fred_set("frequency", "q", "aggregation_method", "eop");

There are a few things to note about the parameter list:

1. The parameter specifications are case sensitive.
2. Order does not matter, with the exception that each parameter should be directly followed by its associated value. For example, we could have also specified

params_GDP = fred_set("aggregation_method", "eop", "frequency", "q");

Next, we'll look at how to use the parameter list for advanced FRED data import.

Filtering Dates

The observation_start and/or observation_end parameters can be used to filter the range of imported data.

For example, suppose we are interested in loading seasonally adjusted CPI data for all dates after 1971. Let's start by searching for the series ID we want to load:

// Read series information from FRED and print first 5 rows
head(fred_search("consumer price index seasonally adjusted"));

       frequency  frequency_short group_popularity               id     last_updated            notes  observation_end observation_star       popularity     realtime_end   realtime_start seasonal_adjustm seasonal_adjustm            title            units      units_short
         Monthly                M        95.000000         CPIAUCSL 2022-11-10 07:38 The Consumer Pri       2022-10-01       1947-01-01        94.000000       2022-11-28       2022-11-28 Seasonally Adjus               SA Consumer Price I Index 1982-1984= Index 1982-1984=
         Monthly                M        95.000000         CPIAUCNS 2022-11-10 07:38 Handbook of Meth       2022-10-01       1913-01-01        71.000000       2022-11-28       2022-11-28 Not Seasonally A              NSA Consumer Price I Index 1982-1984= Index 1982-1984=
      Semiannual               SA        95.000000      CUUS0000SA0 2022-07-13 07:37                .       2021-01-01       1913-01-01        38.000000       2022-11-28       2022-11-28 Not Seasonally A Consumer Price I Inflation, consu          Percent Index 1982-1984=
          Annual                A        84.000000   FPCPITOTLZGUSA 2022-05-03 14:01 Inflation as mea       2021-01-01       1960-01-01        84.000000       2022-11-28       2022-11-28 Not Seasonally A              NSA Inflation, consu          Percent                %
         Monthly                M        83.000000  CPALTT01USM657N 2022-11-14 14:25 OECD descriptor        2022-09-01       1960-01-01        80.000000       2022-11-28       2022-11-28 Not Seasonally A              NSA Consumer Price I Growth rate prev Growth rate prev 

It looks like the best series for us to use is "CPIAUCSL". However, this series starts in January 1947.

We can tell GAUSS to only import data starting from 1971 by setting the observation_start parameter to "1971-01-01" using the fred_set procedure:

// Set observation_start parameter
// to use all data on or after 1971-01-01
params_cpi = fred_set("observation_start", "1971-01-01");

Now we can load our CPI data using fred_load with two inputs:

1. The series ID.
2. The parameter list, params_cpi.

// Load data using a parameter list
cpi_m = fred_load("CPIAUCSL", params_cpi);

// Preview first 5 rows of data
head(cpi_m);

Our data preview shows that the imported data starts on January 1, 1971:

            date         CPIAUCSL
      1971-01-01        39.900000
      1971-02-01        39.900000
      1971-03-01        40.000000
      1971-04-01        40.100000
      1971-05-01        40.300000 

Aggregating Data

Next, suppose we want to aggregate our data from monthly to quarterly data. The FRED import tools provide a convenient way to do this at the time of import using the frequency parameter.

The frequency parameter allows you to specify the frequency of data you would like. The specified frequency can only be the same or lower than the frequency of the original series.

Frequency options include:

Specifier	Description
"d"	Daily
"w"	Weekly
"bw"	Biweekly
"m"	Monthly
"q"	Quarterly
"sa"	Semiannual
"a"	Annual

The default aggregation method is to use averaging. However, the aggregation_method parameter can be used to specify an aggregation method. Aggregation options include:

Specifier	Description
"avg"	Average
"sum"	Sum
"eop"	End of Period

Let's use the frequency parameter to aggregate the monthly "CPIAUCSL" series to quarterly observations. We will also use the aggregation_method to specify that end-of-period aggregation is used:

// Set parameter list
// Include previously specified
// parameter list to append new specifications
params_cpi = fred_set("frequency", "q", "aggregation_method", "eop", params_cpi);

// Load quarterly CPI
cpi_q_eop  = fred_load("CPIAUCSL", params_cpi);

head(cpi_q_eop);

            date         CPIAUCSL
      1971-01-01        40.000000
      1971-04-01        40.500000
      1971-07-01        40.800000
      1971-10-01        41.100000
      1972-01-01        41.400000

The cpi_q_eop dataframe now contains quarterly data starting in January 1971.

Transformations

Finally, suppose we want to use our CPI data to study inflation. With the FRED import tools, we can do this using the units parameter with the fred_load procedure.

The units options include:

Specifier	Description
"lin"	Levels (no transformation).
"chg"	Change.
"ch1"	Change from one year ago.
"pch"	Percent change.
"pc1"	Percent change from one year ago.
"pca"	Compounded annual rate of change.
"cch"	Continuously compounded rate of change.
"cca"	Continuously compounded annual rate of change.
"log"	Natural log.

Let's update our params_cpi parameter list and import the percent change of "CPIAUCSL" from a year ago.

// Set params
params_cpi = fred_set("units", "pc1", params_cpi);

// Load quarterly CPI
infl_q  = fred_load("CPIAUCSL", params_cpi);
plotXY(infl_q,  "CPIAUCSL ~ date");

Conclusion

In today's blog, we saw how the GAUSS FRED integration introduced in GAUSS 23 can save you time and effort when it comes to working with FRED data.

We learned how to use the FRED import tools to:

• Search for a FRED data series.
• Import FRED data to GAUSS, including merging multiple series.
• Use advanced import tools to perform data transformations.