If you've worked with real-world data, you know that data cleaning and management can eat up your time. Efficiently tackling tedious data cleaning, organization, and management tasks can have a huge impact on productivity.

We created the GAUSS Data Management Guide with that exact goal in mind. It's aimed to help you save time and make the most of your data.

Today's blog looks at what the GAUSS Data Management Guide offers and how to best use the guide.

What is the GAUSS Data Management Guide?

The GAUSS Data Management Guide is a comprehensive reference tool for accomplishing data-related tasks in GAUSS. It provides a detailed roadmap for working with data in GAUSS, from basic data import and manipulation to advanced data cleaning and visualization.

The guide is intentionally designed for all levels of GAUSS users with:

• Extensive coverage.
• Step-by-step instructions.
• Annotated examples.

What does the GAUSS Data Management Guide cover?

The GAUSS Data Management Guide includes sections for:

• Interactive Data Import
• Programmatic Data Import
• Programmatic Export
• Data Cleaning
• Data Exploration
• Data Sampling
• Data Smoothing
• Data Transformations

How should I use the GAUSS Data Management Guide?

• Use page outlines, located on the right-hand side of each page, to identify and navigate to specific tasks.

• Copy the examples in the guide and paste into GAUSS program files to use as templates.

• Use the links to complete function reference pages to find additional support.

Conclusion

The GAUSS Data Management Guide provides practical examples, detailed instructions, and comprehensive coverage that can help work productively and efficiently with your data.

Further Reading

1. GAUSS Basics: Interactive commands
2. GAUSS Basics 2: Running a program
3. GAUSS Basics 3: Introduction to matrices
4. GAUSS Basics 4: Matrix operations
5. GAUSS Basics 5: Element-by-element conformability
6. GAUSS Basics 6: Logical and relational operators
7. GAUSS Basics 7: Conditional statements
8. Basics of GAUSS Procedures
9. Understanding Errors | G0025 : Undefined symbol
10. Understanding Errors: G0064 Operand Missing
11. Understanding Errors: G0058 Index out-of-Range

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:

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

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:

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.

A few weeks ago, we showed you how to create a detailed plot from a recent article in the American Economic Review. That article contained several plots that contain quite a bit of similar and stylized formatting. Today we will show you how to efficiently create two of these graphs.

Our main goals are to get you thinking about code reuse and how it can help you:

• Get more results from your limited research time.
• Avoid the frustration that comes from growing mountains of spaghetti code.

Our Graphs

This is what we will create today. As you can see they share many style attributes. This gives us a great opportunity to reuse code.

You can download the data here.

Our Initial Code

This is not a massive amount of code and many of you might be tempted to just copy and paste this code and make the minor modifications needed to get your desired result. I completely understand. Your biggest problem is probably a lack of time, so productivity is paramount.

While it might feel like this is a shortcut, it will saddle you with technical debt. Technical debt is just a fancy term that describes the stress, frustration, and time-wasting that inevitably occurs when you take shortcuts like this.

Not only will this save you pain, but it might save you some embarrassment as well. These sorts of mundane issues are real drivers of the replication crises in research today.

Your research is important and I know you want to do it right, so let's get started!

new;
cls;

/*
** Load and preview data
*/
int_rate = loadd("int_rate.csv");

tail(int_rate);

ks = { 0.517, 0.653, 0.781  };

/*
** Graph data
*/

// Graph size
plotCanvasSize("px", 500 | 400);

// Default settings
struct plotControl plt;
plt = plotGetDefaults("xy");

// Font
plotSetFonts(&plt, "all", "roboto", 14);

// Legend
plotSetLegend(&plt, "", "vcenter left inside", 1);
plotSetLegendBkd(&plt, 0);

// Main line settings
clrs = getColorPalette("set2");
plotSetLinePen(&plt, 4, clrs[3 2], 1|3);

// Axes outline (spine)
plotSetOutlineEnabled(&plt, 1);

// X-axis
plotSetTextInterpreter(&plt, "latex", "xaxis");
plotSetXAxisLabel(&plt, "\\text{country opacity }, \\omega");

// Y-axis
plotSetYLabel(&plt, "interest rate");

// Draw main plot
plotXY(plt, int_rate, "high + low ~ x");

// Style and add vertical lines
plotSetLinePen(&plt, 1, "#CCC", 2);
plotAddVLine(plt, ks);

// Style text boxes
struct plotAnnotation ant;
ant = annotationGetDefaults();
annotationSetTextInterpreter(&ant, "latex");
annotationSetLinePen(&ant, 0, "", -1);
annotationSetFont(&ant, "", 14, "#3333");
annotationSetBkd(&ant, "", 0);

// Add text boxes
plotAddTextbox(ant, "\\omega_1", ks[1], 0.15);
plotAddTextbox(ant, "\\omega_2", ks[2], 0.15);
plotAddTextbox(ant, "\\omega_3", ks[3], 0.15);

Initial Code Simplification

We will start by creating a procedure to hold some of the plot styling functions that we want to repeat and apply them to the first plot only. Then we will add the data for the second plot.

It looks like all of the styling applied before the call to plotXY will be the same in both plots, but the y-axis label text is different. So, let's create a procedure that will apply the main settings:

new;
cls;

/*
** Load and preview data
*/
int_rate = loadd("int_rate.csv");

tail(int_rate);

ks = { 0.517, 0.653, 0.781  };

/*
** Graph data
*/

// Graph size
plotCanvasSize("px", 500 | 400);

// Declare plotControl structure
struct plotControl plt;

// Fill with defaults for this project
plt = pltDefaults();

// Set y-axis label for first plot
plotSetYLabel(&plt, "interest rate");

// Draw first plot
plotXY(plt, int_rate, "high + low ~ x");

proc (1) = pltDefaults();
    local clrs;

    struct plotControl plt;
    plt = plotGetDefaults("xy");

    // Font
    plotSetFonts(&plt, "all", "roboto", 14);

    // Legend
    plotSetLegend(&plt, "", "vcenter left inside", 1);
    plotSetLegendBkd(&plt, 0);

    // Main line settings
    clrs = getColorPalette("set2");
    plotSetLinePen(&plt, 4, clrs[3 2], 1|3);

    // Axes outline (spine)
    plotSetOutlineEnabled(&plt, 1);

    // X-axis
    plotSetTextInterpreter(&plt, "latex", "xaxis");
    plotSetXAxisLabel(&plt, "\\text{country opacity }, \\omega");

    retp(plt);
endp;

While this code is slightly longer when drawing just one plot, it will save us when we add the next plot. Before we do that, we need to address the vertical lines and annotations.

Simplifying the Annotations

Looking over the plots at the top of this article shows us that the vertical lines and the omega text boxes all depend on the ks vector. Since they seem to be intertwined, it is probably safe to put them in one procedure.

The simplest thing to do would be to add all the annotation code to a single procedure like this:

proc (0) = pltAddOmegas(ks);

    struct plotControl plt;
    plt = plotGetDefaults("xy");

    // Style and add vertical lines
    plotSetLinePen(&plt, 1, "#CCC", 2);
    plotAddVLine(plt, ks);

    // Style text boxes
    struct plotAnnotation ant;
    ant = annotationGetDefaults();
    annotationSetTextInterpreter(&ant, "latex");
    annotationSetLinePen(&ant, 0, "", -1);
    annotationSetFont(&ant, "", 14, "#3333");
    annotationSetBkd(&ant, "", 0);

    // Add text boxes
    plotAddTextbox(ant, "\\omega_1", ks[1], 0.15);
    plotAddTextbox(ant, "\\omega_2", ks[2], 0.15);
    plotAddTextbox(ant, "\\omega_3", ks[3], 0.15);
endp;

and then call that procedure right after plotXY. In this case, it is not a bad place to start. However, since we are in learning mode, let's pretend that we were going to create more graphs in this file that would add text boxes with the same styling, but would use different greek letters and would be located in a different place in the graph.

In that case, we would probably want to separate the text box styling from the text box drawing, like this:

proc (1) = textBoxDefaults();
    struct plotAnnotation ant;
    ant = annotationGetDefaults();

    annotationSetTextInterpreter(&ant, "latex");
    annotationSetLinePen(&ant, 0, "", -1);
    annotationSetFont(&ant, "", 14, "#3333");
    annotationSetBkd(&ant, "", 0);

    retp(ant);
endp;

proc (0) = pltAddOmegas(ks);

    struct plotControl plt;
    plt = plotGetDefaults("xy");

    // Style and add vertical lines
    plotSetLinePen(&plt, 1, "#CCC", 2);
    plotAddVLine(plt, ks);

    struct plotAnnotation ant;
    ant = textBoxDefaults();

    // Add text boxes
    plotAddTextbox(ant, "\\omega_1", ks[1], 0.15);
    plotAddTextbox(ant, "\\omega_2", ks[2], 0.15);
    plotAddTextbox(ant, "\\omega_3", ks[3], 0.15);
endp;

Conclusion and final code

Below is the final code to create the graphs from the top of this blog. This isn't designed to show you the best way to write this code, but rather to get you started with the idea of code reuse.

Software engineers sometimes use the acronym DRY — Don't Repeat Yourself. While that is a great practice, even just repeating yourself less often will bring you great rewards.

new;
cls;

/*
** Load and preview data
*/
int_rate = loadd("int_rate.csv");
tail(int_rate);

rationing = loadd("rationing.csv");
tail(rationing);

ks = { 0.517, 0.653, 0.781  };

/*
** Graph data
*/

// Graph size
plotCanvasSize("px", 1000 | 400);

// Declare plotControl structure and
// fill with defaults for this project
struct plotControl plt;
plt = pltDefaults();

/*
** Interest rate plot
*/

// Create grid for multiple plots
plotLayout(1,2,1);

// Set y-axis label for first plot
plotSetYLabel(&plt, "interest rate");

// Draw first plot
plotXY(plt, int_rate, "high + low ~ x");
pltAddOmegas(ks);

/*
** Rationing plot
*/

// Create grid for multiple plots
plotLayout(1,2,2);

// Set y-axis label for first plot
plotSetYLabel(&plt, "rationing");

// Draw first plot
plotXY(plt, rationing, "high + low ~ x");
pltAddOmegas(ks);

proc (1) = pltDefaults();
    local clrs;

    struct plotControl plt;
    plt = plotGetDefaults("xy");

    // Font
    plotSetFonts(&plt, "all", "roboto", 14);

    // Legend
    plotSetLegend(&plt, "", "vcenter left inside", 1);
    plotSetLegendBkd(&plt, 0);

    // Main line settings
    clrs = getColorPalette("set2");
    plotSetLinePen(&plt, 4, clrs[3 2], 1|3);

    // Axes outline (spine)
    plotSetOutlineEnabled(&plt, 1);

    // X-axis
    plotSetTextInterpreter(&plt, "latex", "xaxis");
    plotSetXAxisLabel(&plt, "\\text{country opacity }, \\omega");

    retp(plt);
endp;

proc (1) = textBoxDefaults();
    struct plotAnnotation ant;
    ant = annotationGetDefaults();

    annotationSetTextInterpreter(&ant, "latex");
    annotationSetLinePen(&ant, 0, "", -1);
    annotationSetFont(&ant, "", 14, "#3333");
    annotationSetBkd(&ant, "", 0);

    retp(ant);
endp;

proc (0) = pltAddOmegas(ks);

    struct plotControl plt;
    plt = plotGetDefaults("xy");

    // Style and add vertical lines
    plotSetLinePen(&plt, 1, "#CCC", 2);
    plotAddVLine(plt, ks);

    struct plotAnnotation ant;
    ant = textBoxDefaults();

    // Add text boxes
    plotAddTextbox(ant, "\\omega_1", ks[1], 0.15);
    plotAddTextbox(ant, "\\omega_2", ks[2], 0.15);
    plotAddTextbox(ant, "\\omega_3", ks[3], 0.15);
endp;

Further Reading

1. Advanced Formatting Techniques for Creating AER Quality Plots.
2. Visualizing COVID-19 Panel Data With GAUSS 22.
3. How to Mix, Match and Style Different Graph Types.

Our new Introduction to GAUSS offers a guide for users coming from Stata who are looking to get started quickly in GAUSS. It offers side-by-side comparisons of essential analysis tasks in GAUSS and Stata.

The guide is easily searchable making it a quick and intuitive reference tool for new and experienced GAUSS users, alike.

Contents

In this introduction, you'll learn everything you need to get started in GAUSS including:

Data storage

• GAUSS dataframes.

Data input/output

• Constructing a dataframe from values.
• Reading external dataset.
• Interactively loading data.
• Viewing data.

Data Operations

• Indexing matrices and dataframes.
• Operations on variables.
• Matrix operations.
• Filtering.
• Selection of data.
• Sorting.

Date Function

• Creating usable dates from raw data.
• Creating dates from existing strings.
• Changing the display format.

String Processing

• Finding the length of a string.
• Finding the position of a substring.
• Extracting a substring by position.
• Extracting words.
• Changing case.

Missing values

• Counting missing values.
• Removing missing values.
• Replacing missing values.

Merging

• Merge existing dataframes.

Conclusion

If you're new to GAUSS and are familiar with Stata, you'll find our Introduction to GAUSS the perfect tool for getting up and running.

Our goal for this post is to learn the fundamentals of creating and using procedures in GAUSS. When you are finished, you should be able to create GAUSS procedures and use those written by others.

What is a GAUSS Procedure?

GAUSS procedures are user-defined functions. They allow you to combine a sequence of commands to perform a desired task.

Why Create GAUSS Procedures?

There are many advantages to creating GAUSS procedures. Even if you don’t consider yourself a programmer, creating GAUSS procedures will make your work easier and more productive.

Save time. Every time you use a previously written GAUSS procedure you,

• Avoid rewriting the same code.
• Avoid debugging new or old mistakes.
• Keep your main code simpler and more readable.

How to Create a GAUSS Procedure Definition

Let’s start with a simple example. We’ll create a simple procedure named power which takes two inputs and returns one output.

proc (1) = power(X, p); // 1. Procedure declaration
    local X_out;        // 2. Local variable list

    X_out = X ^ p;      // 3. Procedure body

    retp(X_out);        // 4. Procedure return
endp;                   // 5. Procedure end

Each line in the above procedure is one of the main parts of a GAUSS procedure. Now let's discuss the details of each of these elements.

1. The Procedure Declaration

a.         c.
↓          ↓
proc (1) = power(X, p);
      ↑          ↑
      b.         d.

The procedure declaration is the first line of all GAUSS procedures. It contains four main sections:

Don't forget the ending semi-colon.

2. The Local Variable List

    local X_out;  

The local variable list is a comma-separated list of variables that will be used inside the procedure. These local variables only exist when the procedure is running.

3. The Procedure Body

    X_out = X ^ p;

The procedure body is where the procedure's computations are performed. In this case, we have just one simple line. However, there is no limit to the size of your procedure.

You can use procedures created by you or others as well as any built-in GAUSS function or operator inside the body of your procedure.

4. The Procedure Return

    retp(X_out);

You can return any of the local variables from the procedure, or none at all. When returning more than one variable, use commas to separate the variable names.

5. The Procedure End

endp;

The endp keyword signals the end of the procedure.

How to Use a GAUSS Procedure

There are two steps required to use a GAUSS procedure:

1. Define the procedure.
2. Call the procedure.

How to Define a GAUSS Procedure

When GAUSS first starts up, it is only aware of its own built-in functions and procedures. Defining a procedure is the process of making GAUSS aware of your procedure. If you try to use a procedure before it is defined, like this:

// Clear all data and procedures from the GAUSS workspace
new;

// Call procedure that has not been defined
power(3, 2);

you will get the error G0025 : Undefined symbol: 'power'.

Here are four ways to define your GAUSS procedure:

1. Add the procedure to your main code file.
2. Run the GAUSS procedure.
3. Place the procedure in a .g file.
4. Add your procedure to a GAUSS library.

1. Add the procedure to your main code file. The simplest method to define a procedure is to simply add it to your code and run the main file. This allows for a natural process of learning-by-doing.

As we can see from the above image, the procedure can be included anywhere in your program file. It is often convenient to place procedures after the main code.

GAUSS can allow this because it does not just run your code line-by-line. It is smarter than that. When GAUSS runs your program, its first step is to compile your code. This allows GAUSS to find many mistakes immediately and also speed-up your code in addition to locating your procedures.

2. Run the GAUSS procedure. Since GAUSS does not run your code line-by-line, as we saw in the previous section, GAUSS needs to have the entire procedure definition at once. Therefore, you cannot run a procedure one line at a time. If you try to run the first line alone:

proc (1) = power(X, p);

you will get the error G0278 : PROC without ENDP 'power'.

After you run the entire procedure:

the procedure is defined so that you can use it in GAUSS. Now running:

x = power(3, 2);
print x;

will be successful, returning:

9

3. Place your procedure in a .g file. It is not always convenient to keep all procedures in your main code file.

A simple alternative is to:

    i. Create a file with the same name as your procedure plus a .g file extension. Such as power.g.
    ii. Place your procedure in this file.
    iii. Save this file in a location where GAUSS can find it.

4. Add your procedure to a GAUSS library. Adding your related procedures to a GAUSS library is considered a best practice. GAUSS libraries make it easier to use and share code without worrying about paths.

Full GAUSS library management is beyond the scope of this article. However, the above image shows the Create Library and Add Files controls.

How to Call a GAUSS Procedure

Now that we've learned how to create and define GAUSS procedures, it's time to use them. Here are a few example procedures to fill in anything you might be unsure about.

We'll start with a procedure with two returns.

// Create 4x1 vector
y = { 1, 3, 2, 1 };

// Call procedure
{ a, b } = range(y);

// Print results
print "The smallest value is: " a;
print "The largest value is : " b;

// Procedure that returns two items
proc (2) = range(X);
    local min, max;

    min = minc(X);
    max = maxc(X);

    retp(min, max);
endp;

Running the above code will return:

The smallest value is:        1
The largest value is :        3

Next, we'll consider a case with two inputs.

// Create 5x1 vector
z = { 1, 2, 3, 4, 9 };

m1 = average(z, "median");
print m1;

m2 = average(z, "mean");
print m2;

proc (1) = average(y, type_);
    local avg;

    if type_ $== "mean";
        avg = meanc(y);
    elseif type_ $== "median";
        avg = median(y);
    else;
        print "Second input, type_, not recognized";
        end;
    endif;

    retp(avg);
endp;

which will return:

3.0
3.8

Conclusion

Great job! You've made it through the fundamentals of GAUSS procedures. You've learned:

1. The parts that make up a GAUSS procedure.
2. How to define GAUSS procedures.
3. How to call GAUSS procedures.

Often times we need to mix multiple graph types in order to create a plot which most effectively tells the story of our data. In this post, we will create a plot of the Phillips Curve in the United States over two separate time periods.

We will show how to add scatter points and lines as well as data series' of different length to a single plot. However, our main focus will be showing you how to control the styling of all aspects of the plot in these cases.

How to add data to an existing graph

The main GAUSS graphing functions shown in the second column of the table below, treat each column of the input data as a separate series. This makes it very simple to plot data in which the plot type and series length are the same.

We can add a new series to a graph created with one of the main functions in column two, by using one of the add functions in column three.

The add functions take the same inputs as the main functions. For example, the code below will create a scatter plot and then add a line at the mean of the Y variable.

// Load variables from dataset
data = loadd("phillips-us-1955.csv", "CPI + Unemployment");

// Plot initial scatter points
plotScatter(data[.,1], data[.,2]);

// Compute mean of unemployment
mu_u = meanc(data[.,2]);

// Compute range of CPI
range_cpi = minc(data[.,1]) | maxc(data[.,2]);

// Add a line across the range of the CPI
// data at the height of the average of the
// Unemployment data
plotAddXY(range_cpi, mu_u | mu_u);

The code will create a graph which looks like this:

How to style a graph with plotAdd functions

When styling graphs made with plotAdd functions, an important distinction is made between axis level attributes and series level attributes.

Axis level attributes

Axis level attributes are the elements which are generally independent of the data. For example, the title, axes labels and tick labels are axis level attributes. These attributes become fixed during the creation of the initial plot and cannot be modified with a plotAdd call.

The axis level attributes include:

• Title
• Axes labels
• Tick label font and format
• Axes line attributes
• X and Y-axis range (if explicitly set with plotSetXRange / plotSetYRange)
• Canvas size
• Legend location, font and background style

For example, if we modify our earlier code like this:

// Load variables from dataset
data = loadd("phillips-us-1955.csv", "CPI + Unemployment");

struct plotControl myPlot;
myPlot = plotGetDefaults("scatter");

// Set axis element, title
plotSetTitle(&myPlot, "Phillips Curve in the US", "Helvetica Neue", 14);

// Plot initial scatter points
// Note that we pass in 'myPlot' this time
plotScatter(myPlot, data[.,1], data[.,2]);

// Compute mean of unemployment
mu_u = meanc(data[.,2]);

// Compute range of CPI
range_cpi = minc(data[.,1]) | maxc(data[.,2]);

// Attempt to reset axis level property
myPlot = plotGetDefaults("xy");
plotSetTitle(&myPlot, "Title which will be ignored");

// Attempt to set axis level property
plotSetXLabel(&myPlot, "CPI");

// Add a line across the range of the CPI
// data at the height of the average of the
// Unemployment data
// Note that we pass in 'myPlot' this time
plotAddXY(myPlot, range_cpi, mu_u | mu_u);

we will get a graph that looks like this:

The code reset the title before the plotAddXY call from "Phillips Curve in the US" to "Title which will be ignored". The code also reset the X-axis label from nothing to "CPI". As you see both of those changes were ignored because axis level attributes must be set on the initial plot creation.

Series level attributes

Series level attributes are those settings which are specific to the data series. For example, line color, line thickness and scatter symbol are all series level attributes.

The series level attributes include:

• Line color, thickness, style
• Scatter symbol type, color
• Legend text

You have the choice whether to set the series level attributes at the time of the initial plot call or to modify them during the plotAdd. Passing a plotControl structure to the plotAdd call tells GAUSS to update the series level attributes. If you do not pass a plotControl structure to the plotAdd call, GAUSS will continue using the attributes set in the initial plot creation.

More specifically, when a plotControl structure is not passed into the plotAdd call, GAUSS will continue cycling through the previously set series attributes where the last plot call left off. It is like the last plot call left a bookmark in the list of series attributes.

For example, you may have noticed that the mean line in the first graph we made is blue, while the line in the second graph is orange. Looking at the default colors in the table below, we can see why.

When we created the first graph, the initial plotScatter call set the graph's line and scatter symbol colors to the list of five colors shown above. The initial scatter plot used the first orange color, so the plotAddXY without a plotControl structure started with the blue color next in the list.

In the second graph, since the plotAddXY call was given a plotControl structure, this told GAUSS to create the new line using the series settings from the new plotControl structure starting from the beginning. Since we had not changed the sequence of colors, the added mean line used the same orange color as the scatter plot.

How to create the full Phillips Curve graph

It is generally considered a best practice to apply all axes and series level settings with the initial plot call. That is what we will do here. Our steps will be:

1. Load the data.
2. Set the axis level attributes.
3. Set the series level attributes.
4. Draw the initial scatter plot.
5. Add the second set of scatter points.
6. Add the two regression lines.

Step 1: Load and define data

We will start by loading the data for both sets of scatter points. To keep our focus on the graphs, we have simply defined the start and endpoints for the regression lines instead of computing them.

// Load inflation and unemployment data
// (CPI percent change) for 1955–71 and 1974–84
phil_1955 = loadd("phillips-us-1955.csv", "CPI + Unemployment");
phil_1974 = loadd("phillips-us-1974.csv", "CPI + Unemployment");

// For simplicity, define start and
// end points for regression lines
reg_x_1955 = { -0.8538, 6.4246 };
reg_y_1955 = { 5.6356, 3.8925 };

reg_x_1974 = { 2.3590, 14.5923 };
reg_y_1974 = { 9.0762, 5.9248 };

Step 2: Set the axis level attributes

Next, we will apply the most straightforward axis level settings. The only point to note about these is that they cannot be changed by a plotAdd call.

// Declare 'myPlot' to be a plotControl structure
// and fill with default settings
struct plotControl myPlot;
myPlot = plotGetDefaults("scatter");

plotSetTitle(&myPlot, "Phillips Curve in the US", "Arial", 14);

// Note that the font settings applied in
// plotSetXLabel will control the Y-label font
// as well. Setting the Y-label without font
// settings will leave previous font settings unchanged
plotSetXLabel(&myPlot, "Inflation", "Arial", 14);
plotSetYLabel(&myPlot, "Unemployment");

plotSetYRange(&myPlot, 0, 12.5);

Setting the legend will make us think a little more. We will set the legend background to be completely transparent, that is clearly an axis level setting.

However, the function plotSetLegend allows us to set the legend location which is also an axis level attribute in addition to the text for each item in the legend which is a series level attribute.

Fortunately, since we have decided to set all axis and series level attributes before the first scatter plot, we don't need to worry about this distinction. We simply need to make sure that we set our desired text for every data series we plan to add to the plot.

// Make the legend background completely
// transparent, i.e. 0% opacity
plotSetLegendBkd(&myPlot, 0);

// The text for each data series we plan to add
// to our graph, in order. Note that the last
// item is an empty string, "", because we only
// want a legend item for one of the regression lines.
leg_text = "1955-1971" $| "1974-1984" $| "Regression line" $| "";
plotSetLegend(&myPlot, leg_text, "top left inside");

Step 3: Set the series level attributes

After setting the legend text, we have one more series level attribute to set. That is the line or scatter symbol color. To keep things simple and focused, we will just use the string hex codes and a text name for the colors.

However, GAUSS has many built-in color palettes which are attractive and easy to use. Our blog post 5 Hacks for Creating Custom GAUSS Graphics includes a section which links to the available color palettes and the functions needed to access them.

// Set the colors for the scatter plot, an orange and green
// color, followed by one "black" for each regression line
clrs = "#66C2A5" $| "#FC8D62" $| "black" $| "black";
plotSetLineColor(&myPlot, clrs);

Step 4: Draw the initial scatter plot

We'll now draw the initial scatter plot, containing the inflation and unemployment data from 1955 to 1971. We will pass in the plotControl structure which contains all the settings we have applied for every data series we plan to add to the graph.

// Draw initial scatter plot
plotScatter(myPlot, phil_1955[.,1], phil_1955[.,2]);

This results in a graph which looks like this:

Step 5: Add the second scatter plot

// Add next scatter series, using previously
// set series level attributes since a
// plotControl structure was not passed in
plotAddScatter(phil_1974[.,1], phil_1974[.,2]);

This code will result in a plot which looks like this:

Most of this graph should look like you expect. The added scatter plot is using the second legend text item and the second color. The title, axes labels, and Y-axis range have stayed just as we set them.

The X-axis range, however, has changed. Since we made a big deal earlier that axis level attributes do not change after a plotAdd, you may wonder why the X-axis range did not stay the same.

The reason for this is that the default state for the X and Y-axis ranges is to expand to fit the data being drawn. Since we had not set the X-axis range, it remained at "expand to fit data".

However, if we had set the X-axis range to the range of the first scatter plot, -1 to +7, then the X-axis range would have remained unchanged. This would mean that all data to the right of X=7 would be out of view.

Step 6: Add the regression lines

Since the plotAdd functions, like the standard plot functions, will plot each column of data as a separate series, either of these code snippets will produce the same result:

// Option 1: Add the regression lines in separate calls
plotAddXY(reg_x_1955, reg_y_1955);
plotAddXY(reg_x_1974, reg_y_1974);

// Option 2: Add both regression lines in one call
plotAddXY(reg_x_1955 ~ reg_x_1974, reg_y_1955 ~ reg_y_1974);

Remember to only use only one of the above options. This should result in the plot shown at the top of this tutorial.

Conclusion

Congratulations! You have learned:

1. Which plot attributes are axis level elements vs series level elements.
2. That axis level elements need to be set on the first plot call.
3. That series level elements can be set on the first plot call, or during a plotAdd, if a plotControl structure is passed in.

These concepts you've learned will make it much easier for you to create and style GAUSS graphs with data of different lengths and different plot types.

GAUSS packages provide access to powerful tools for performing data analysis. This guide covers all you need to know to get the most from GAUSS packages including:

• What is a GAUSS package
• Where to find GAUSS packages
• What is included in GAUSS packages
• How to use GAUSS packages

What is a GAUSS package?

A GAUSS package is a pre-built compilation of procedures and examples. GAUSS packages:

1. Can save time and effort by providing tools that you would have to program otherwise.
2. Are easy to install and use.
3. Are built both by Aptech and experienced GAUSS users.

Packages usually provide tools focused in a specific area of analysis. For example, Aptech produces a time series package (TSMT) and a Bayesian estimation package (BET).

Where can I find GAUSS packages?

GAUSS packages are available from Aptech maintained sites and user maintained sources.

From Aptech you can:

1. Purchase application packages from the Aptech product page.
2. Browse, download, and install open-source packages using the GAUSS Package Manager..

How do I install a GAUSS package?

Nearly all GAUSS packages can be easily installed using the GAUSS Package Manager. Introduced in GAUSS version 20, the Package Manager simplifies managing GAUSS packages by allowing you to download, install, and remove them directly without ever leaving GAUSS.

Step-by-Step installation using the GAUSS Package Manager

1. Select Tools > Package Manager to open the Installed Packages window shown below:
   As the name implies, it will list all the packages you have previously installed. If you have not installed any packages, the window will be blank as we see above.
2. Click the plus icon (+) on the top right of the Installed Packages window to open the Repository Packages window.
3. Click the name of an available package from the list in the Repository Packages window.
4. Click the Install Package button on the bottom-left.
5. Click Close when the package has finished installing.

The Applications Installer Wizard

In the case that a package cannot be installed using the GAUSS Package Manager, the GAUSS Applications Installer Wizard should be used.

Video instructions

Step-by-Step installation using the GAUSS Applications Installer Wizard

1. Download the package zipped folder.
2. Select Tools > Install Application from the main GAUSS menu.
3. Follow the installer prompts, making sure to navigate to the proper zipped folder associated with the package.

What is included in a GAUSS package?

GAUSS packages are made up of a number of files which can include:

• Source code files
• Example files
• Support documents
• Library definition files
• Miscellaneous support files

The source code, example, and document files will be the most relevant for using a package.

Source code

What is source code? A package's source code is a collection of files that contain the definitions of the GAUSS procedures and structures included in the package.

Where can I find a package's source code after installation? Once a package is installed using the GAUSS Package Manager, the source code will be located in the pkgs > packagename > src folder under your GAUSS home directory.

For example, if your GAUSS home directory is C:\gauss after installation of the tspdlib library the source code will be found in the C:\gauss\pkgs\tspdlib\src directory.

You can easily navigate to a source code file from an installed library using the GAUSS Library Tool. Simply:

1. Find the library name on the list of installed libraries.
2. Expand the list of source code files included in the library by clicking on the arrow next to the library name.
3. Double-click on the file you want to view and the file will open in the GAUSS Program Editor.

Examples

What are example files? Example files are GAUSS program filesthat demonstrate how to use the procedures included in a GAUSS package.

Where can I find a package's examples after installation? Once a package is installed using the GAUSS Package Manager, the examples will be located in the pkgs > packagename > examples folder located under your GAUSS home directory.

Continuing our previous example, if your GAUSS home directory is C:\gauss after installation of the tspdlib library the examples will be found in the C:\gauss\pkgs\tspdlib\examples folder.

You can easily create a shortcut for navigating to example files by adding the directory for a package to your GAUSS Project Folders Window.

Documents

What are document files? Document files can be one of a number of different types of files that provide general descriptions and instructions for using a GAUSS package. These are not always included with a package.

Where can I find a package's documents after installation? A large number of packages have online documentation available, including examples and command references. You can find these documents on the GAUSS Applications Page. If a package has additional documents beyond those available online, they will generally be contained in the pkgs > packagename > docs directory, under your GAUSS home folder.

How do I use a GAUSS package?

GAUSS packages provide procedures that are built to be called from the command line or in program files. In order to use these procedures:

1. The package must be properly installed and the library must be properly built.
2. The library must be loaded.

There are a number of ways to load a GAUSS library:

• Navigate to the Library Tool and click the gear symbol next to the library name. Select load library from the menu:
• Enter the command library libraryname in the input/output window. For example, if you want to load the TSPDLIB library you would enter library tspdlib.
• Put the line library libraryname; at the beginning of your program file. For example, if you want to load the TSPDLIB library you add the line library tspdlib; to the top of the file.

What should I do with source code?

Generally, nothing should be done with source code once it is installed. Since altering source code can break the procedures included in a library, it should only be done by experienced GAUSS users. However, advanced users are welcome to modify the code to meet their needs.

If source code is well annotated with comments, you may find it helpful to look at the source code to learn more about how to use a specific procedure or what a procedure is doing.

As an example, let's consider the adf.src file from the TSPDLIB library. It contains a header which describes how to call the adf procedure followed by the definition of the adf procedure:

What should I do with example files?

Example files are provided to help you learn how to use functions properly and efficiently.

To get the most from the examples in a package:

1. Review example files to learn how to call and use procedures contained in a package.
2. Run examples files to learn more about what happens when you call procedures and how the output is returned.
3. Copy and paste the code from the example files to use as templates for your projects.

Video: Run a GAUSS package example

Conclusion

Today's comprehensive GAUSS package guide covers what you need to know to get the most out of GAUSS packages.

After today you should know:

• What a GAUSS package is.
• Where to find GAUSS packages.
• What is included in a GAUSS package.
• How to use GAUSS packages.

Further Reading

1. Running publicly available GAUSS code: Part 1
2. Running publicly available GAUSS code: Part 2
3. GAUSS Basics 2: Running a program
4. GAUSS Package Manager Basics
5. Understanding Errors | G0025 : Undefined symbol

Introduction

This third video in our GAUSS Basics series will show you how to:

1. Create matrices.
2. Find their size.
3. Access specific elements with indexing.
4. Grow them with matrix concatenation.

Timeline

0:00 Matrix declarations.
1:40 Matrix Indexing.
2:48 Matrix Concatenation.

The GAUSS Basics Video Series

1. GAUSS Basics: Interactive commands
2. GAUSS Basics 2: Running a program
3. GAUSS Basics 4: Matrix operations
4. GAUSS Basics 5: Element-by-element conformability
5. GAUSS Basics 6: Logical and relational operators
6. GAUSS Basics 7: Conditional Statements

Introduction

This second video in our new GAUSS Basics series will show you how to:

1. Create and run a GAUSS program.
2. Use recommended file extensions.
3. Create and print strings.
4. Add code comments.

Timeline

0:00 Introduction.
0:27 Creating a program file.
2:14 Running a program file.

The GAUSS Basics Video Series

1. GAUSS Basics 2: Running a program
2. GAUSS Basics 3: Introduction to matrices
3. GAUSS Basics 4: Matrix operations
4. GAUSS Basics 5: Element-by-element conformability
5. GAUSS Basics 6: Logical and relational operators
6. GAUSS Basics 7: Conditional Statements

Introduction

This is the first video in our new GAUSS Basics series. This series is designed to teach you everything you need to know to be productive with GAUSS.

This video is designed to be your first step in GAUSS! Learn how to:

1. Create variables.
2. Use arithmetic operators.
3. Enter interactive commands.
4. View the variables in your workspace.
5. Print output.

Timeline

0:00 Introduction.
0:08 Arithmetic operators.
2:40 Variable names.

The GAUSS Basics Video Series

1. GAUSS Basics 2: Running a program
2. GAUSS Basics 3: Introduction to matrices
3. GAUSS Basics 4: Matrix operations
4. GAUSS Basics 5: Element-by-element conformability
5. GAUSS Basics 6: Logical and relational operators
6. GAUSS Basics 7: Conditional Statements