Categorical data plays a key role in data analysis, offering a structured way to capture qualitative relationships. Before running any models, simply examining the distribution of categorical data can provide valuable insights into underlying patterns.

Whether summarizing survey responses or exploring demographic trends, fundamental statistical tools, such as frequency counts and tabulations, help reveal these patterns.

GAUSS offers several tools for summarizing and visualizing categorical data, including:

• tabulate: Quickly compute cross-tabulations and summary tables.
• frequency: Generate frequency counts and relative frequencies.
• plotFreq: Create visual representations of frequency distributions.

In GAUSS 25, these functions received significant enhancements, making them more powerful and user-friendly. In this post, we'll explore these improvements and demonstrate their practical applications.

Frequency Counts

The GAUSS frequency function generates frequency tables for categorical variables. In GAUSS 25, it has been enhanced to utilize metadata from dataframes, automatically detecting and displaying variable names. Additionally, the function now includes an option to sort the frequency table, making it easier to analyze distributions.

Example: Counting Product Categories

For this example, we'll use a hypothetical dataset containing 50 observations of two categorical variables: Product_Type and Region. You can download the dataset here.

To start, we'll load the data using loadd:

/*
** Sample product sales data
*/
// Import sales dataframe
product_data = loadd(__FILE_DIR $+ "product_data.csv");

// Preview data
head(product_data);

    Product_Type           Region
     Electronics             East
      Home Goods             West
       Furniture            North
            Toys             East
      Home Goods            North

Next, we will compute the frequency counts of the Product_Type variable:

// Compute frequency counts
frequency(product_data, "Product_Type");

=============================================
   Product_Type     Count   Total %    Cum. %
=============================================

       Clothing         8        16        16
    Electronics        13        26        42
      Furniture        10        20        62
     Home Goods         7        14        76
           Toys        12        24       100
=============================================
          Total        50       100

We can also generate a sorted frequency table, using the optional sorting argument:

// Compute frequency counts
frequency(product_data, "Product_Type", 1);

=============================================
   Product_Type     Count   Total %    Cum. %
=============================================

    Electronics        13        26        26
           Toys        12        24        50
      Furniture        10        20        70
       Clothing         8        16        86
     Home Goods         7        14       100
=============================================
          Total        50       100  

Tabulating Categorical Data

While frequency counts help us understand individual categories, the tabulate function allows us to explore relationships between categorical variables. This function performs cross-tabulations, offering deeper insights into categorical distributions. In GAUSS 25, it was enhanced with new options for calculating row and column percentages, making comparisons easier.

Example: Cross-Tabulating Product Type and Region

Now let's look at the relationship between Product_Type and Region.

// Generate cross-tabulation
call tabulate(product_data, "Product_Type ~ Region");

=====================================================================================
   Product_Type                              Region                             Total
=====================================================================================
                      East          North          South           West

       Clothing          1              5              1              1             8
    Electronics          5              1              5              2            13
      Furniture          3              3              1              3            10
     Home Goods          1              3              2              1             7
           Toys          4              3              2              3            12
          Total         14             15             11             10            50

=====================================================================================

By default, the tabulate function generates absolute counts. However, in some cases, relative frequencies provide more meaningful insights. In GAUSS 25, tabulate now includes options to calculate row and column percentages, making it easier to compare distributions across categories.

This is done using the tabControl structure and the rowPercent or columnPercent members.

• Row percentages show how the distribution of product types varies across regions.
• Column percentages highlight the composition of product types within each region.

/*
** Relative tabulations
*/ 
struct tabControl tCtl;
tCtl = tabControlCreate();

// Specify row percentages
tCtl.rowPercent = 1;

// Tabulate
call tabulate(product_data, "Product_Type ~ Region", tCtl);

=====================================================================================
   Product_Type                               Region                            Total
=====================================================================================
                       East          North          South           West

       Clothing        12.5           62.5           12.5           12.5          100
    Electronics        38.5            7.7           38.5           15.4          100
      Furniture        30.0           30.0           10.0           30.0          100
     Home Goods        14.3           42.9           28.6           14.3          100
           Toys        33.3           25.0           16.7           25.0           99

=====================================================================================
Table reports row percentages.

Alternatively we can find the column percentages:

/*
** Relative column tabulations
*/ 
struct tabControl tCtl;
tCtl = tabControlCreate();

// Compute row percentages
tCtl.columnPercent = 1;

// Tabulate product types
call tabulate(product_data, "Product_Type ~ Region", tCtl);

===========================================================================
   Product_Type                                  Region

===========================================================================
                          East          North          South           West

       Clothing            7.1           33.3            9.1           10.0
    Electronics           35.7            6.7           45.5           20.0
      Furniture           21.4           20.0            9.1           30.0
     Home Goods            7.1           20.0           18.2           10.0
           Toys           28.6           20.0           18.2           30.0
          Total            100            100            100            100

===========================================================================
Table reports column percentages.

Visualizing Distributions

While tables provide numerical insights, frequency plots offer an intuitive visual representation. GAUSS 25 enhancements to the plotFreq function include:

• Automatic category labeling for better clarity.
• New support for the by keyword to split data by category.
• New percentage distributions.

Example: Visualizing Product Type Percent Distribution

To start, let's look at the percentage distribution of product type. To help with interpretation, we'll sort the graph by frequency and use a percentage axis:

// Sort frequencies
sort = 1;

// Report percentage axis
pct_axis = 1;

// Generate frequency plot
plotFreq(product_data, "Product_Type", sort, pct_axis);

Example: Visualizing Product Type Distribution by Region

Next, let's visualize the distribution of the product types across regions using the plotFreq function and the by keyword:

// Generate frequency plot
plotFreq(product_data, "Product_Type + by(Region)");

Conclusion

In this blog, we've demonstrated how updates to frequency, tabulate, and plotFreq in GAUSS 25 make categorical data analysis more efficient and insightful. These enhancements provide better readability, enhanced cross-tabulations, and more intuitive visualization options.

Further Reading

1. Introduction to Categorical Variables.
2. Easy Management of Categorical Variables
3. What is a GAUSS Dataframe and Why Should You Care?.
4. Getting Started With Survey Data In GAUSS.

In data analysis, a well-designed graph can help clarify your insights but a poorly annotated one can confuse and distract your audience. That’s why proper annotation, including legends, is essential to creating effective graphs.

Legends play a crucial role in making graphs more readable by distinguishing between different groups, categories, or data series. A well-placed legend helps ensure that your message comes across clearly.

In this blog, we'll walk through how to add and customize legends in GAUSS graphics, covering:

• Adding a basic legend using plotsetlegend.
• Customizing legend appearance with plotsetlegendfont, plotsetlegendbkd, plotsetlegendborder, and plotsetlegendtitle.
• Understanding automatic legend creation when using the by keyword in formula strings.

Automatically Adding Legends with the by Keyword

When using a formula string with the by keyword, GAUSS automatically generates a legend based on the categorical variable.

For example, let's create a scatter plot using the built-in crabs.dta dataset:

// Load data
fname = getGAUSSHome("examples/crabs.dta");
crabs = loadd(fname);

// Create scatter plot with automatic legend
plotScatter(crabs, "rear_width ~ body_depth + by(sex)");

When the by keyword is used with the categorical variable, sex GAUSS:

• Plots a separate color for each group.
• Automatically creates a legend indicating different groups.
• Includes a title on the legend.

These legends are useful when we just need a quick glance at our data. However, they don't allow for custom formatting. To use custom formatting we need to use a plotControl structure.

Setting Up a plotControl Structure

To customize a GAUSS plot, the first step is to declare and initialize a plotControl structure. This structure is used for all plot-related settings, including axis labels, colors, fonts, legends, and more.

Why Use a plotControl Structure?

The plotControl structure provides a flexible and organized way to modify a plot’s appearance. Instead of manually formatting the plot after it is created, we can programmatically set all customizations in advance. This saves us time and effort when we need to reproduce our graphs.

To use this structure we:

1. Declare a plotControl structure.
2. Fill it with default settings using plotGetDefaults.
3. Modify the structure’s properties as needed.
4. Pass the structure when calling our GAUSS plotting function.

Declaring and Initializing the plotControl Structure

Every plot customization starts with the following setup:

// Declare plot control structure
struct plotControl myPlot;

// Fill with default settings for an XY plot
myPlot = plotGetDefaults("xy");

Notice that the defaults are specific to the plot type we are making. For example, if we were creating a bar or scatter plot, we would use "bar" or "scatter" instead.

Once the plotControl structure is initialized, we can customize all graph properties—such as adding a legend.

Adding a Basic Legend

After declaring and initializing our plotControl structure, we can use the plotSetLegend function to add a default styled legend to any plot.

The function takes two required inputs:

1. A pointer to a plot control structure.
2. A string array containing legend labels.

Additionally, two optional arguments may be used:

1. A string specifying the legend location.
2. A scalar indicating vertical or horizontal orientation.

Adding a Default Legend

Let's look at adding a simple legend to an XY plot with the default location and orientation:

// Declare plot control structure
struct plotControl myPlot;

// Fill with default settings for xy plot
myPlot = plotGetDefaults("xy");

// Sample data
x = seqa(1, 1, 10);
y1 = x + rndn(10, 1);
y2 = x - 0.5 + rndn(10, 1);

// Specify legend labels
// using '$|" to concatenate 
// individual labels
label = "Group 1"$|"Group 2";

// Set up basic legend
plotSetLegend(&myPlot, label);

// Create XY plot
plotXY(myPlot, x, y1~y2);

Changing the Legend Location

By default our legend is in the top, right corner of our plot canvas. This may not always be the ideal location, as we can see in the plot above.

Fortunately, the location input allows us to specify a different location. The location input can either be the xy coordinates for the top left of the legend, or a string. Setting xy coordinates allows for precise placement, but can sometimes be more cumbersome.

When specifying the legend location using a string, you may use one or more of the following:

1. Vertical location: "top"(default), "vcenter", or "bottom".
2. Horizontal location: "left", "hcenter", or "right"(default).
3. Inside/outside location: "inside"(default) or "outside"

For example, let's change the legend location to the bottom, right corner of the plot:

// Specify legend labels
// using '$|" to concatenate 
// individual labels
label = "Group 1"$|"Group 2";

// Place in bottom right corner
location = "bottom right";

// Set legend
plotSetLegend(&myPlot, label, location);

// Create XY plot
plotXY(myPlot, x, y1~y2);

These location components can be specified in any order. For example, we would get the same results specifying the location like this:

// Place in bottom right corner
location = "right bottom";

We could create a very similar graph by specifying the top left of the legend to be at x=7.5 and y=2 like this:

// Specify xy coordinates for the top left corner of the legend.
location = { 7.5, 2 };

Changing the Legend Orientation

The plotSetLegend procedure also allows us to specify if the series are listed horizontally or vertically using the optional orientation input.

The orientation input is set to:

1. 1 for a vertical series list (default).
2. 0 for a horizontal series list.

// Specify legend labels
// using '$|" to concatenate 
// individual labels
label = "Group 1"$|"Group 2";

// Place in bottom right corner
location = "bottom right";

// Set to horizontal list
orientation = 0;

// Set legend
plotSetLegend(&myPlot, label, location, orientation);

// Create XY plot
plotXY(myPlot, x, y1~y2);

Advanced Legend Formatting

In addition to the basic legend, GAUSS provides several functions to customize legend appearance.

Example: Advanced Legend Formatting

Let's look at another plotting example and explore some of the advanced legend formatting options.

To get started, we will simulate some data:

/*
** Create the sequence 0.25, 0.5, 0.75...3
*/
x = seqa(0.25, 0.25, 12);
y = sin(x);

and setup our plotControl structure

// Declare plotControl structure
// and fill with default settings for XY plots
struct plotControl myPlot;
myPlot = plotGetDefaults("xy");

We want the legend for this plot to:

1. Be horizontally centered and placed outside the bottom of the plot.
2. Use 14 pt., "dark blue", Arial font.
3. Have a "light gray" border with a thickness of 2 pixels.
4. Render and interpret labels using latex.

Labels and Location

We set the labels and location using the plotSetLegend procedure:

/*
** Basic legend settings
*/
// Set label
label = "\sin{x}";

// Set location
location = "bottom hcenter outside";

// Set legend 
plotSetLegend(&myPlot, label, location);

Legend Font Properties

The plotSetLegendFont function allows us to adjust the font style, size, and color of the legend text.

/*
** Legend font
*/
// Set font
font_style = "Arial";

// Set font size
font_size = 14;

// Set font color
font_clr = "dark blue";

// Set all legend font properties
plotSetLegendFont(&myPlot, font_style, font_size, font_clr);

Customizing The Legend Border

The plotSetLegendBorder procedure sets the color and width of the border.

/*
** Legend border
*/

// Set border color
border_clr = "light gray";

// Border width
border_width = 2;

// Set the legend border 
plotSetLegendBorder(&myPlot, border_clr, border_width);

Changing Text Interpretation

By default, GAUSS treats legend text as plain text. However, we can enable LaTeX-style formatting using plotSetTextInterpreter:

/*
** Set text interpret to interpret
** latex for legend labels
*/
plotSetTextInterpreter(&myPlot, "latex", "legend");

Generating Our Plot

// Create XY plot
plotXY(myPlot, x, y);

Conclusion

In this blog, we covered different ways to customize legends in GAUSS plots:

• Adding a legend using plotSetLegend.
• Modifying fonts, backgrounds, and borders for better visualization.
• Utilizing LaTeX formatting and adding legend titles.
• Automatically generating legends using the by keyword.

These techniques enhance the clarity of your visualizations, making it easier to interpret results.

Further Reading

1. How to mix, match and style different graph types
2. How to Interactively Create Reusable Graphics Profiles
3. How to Create Tiled Graphs in GAUSS
4. Visualizing COVID-19 Panel Data With GAUSS 22
5. Advanced Formatting Techniques for Creating AER Quality Plots
6. Introduction to Efficient Creation of Detailed Plots

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.

Today's blog will show you how to reproduce one of the graphs from a paper in the June 2022 issue of the journal, American Economic Review. You will learn how to:

1. Add and style text boxes with LaTeX.
2. Set the anchor point of text boxes.
3. Add and style vertical lines.
4. Automatically set legend text to use your dataframe's variable names.
5. Set the font for all or a subset of the graph text elements.
6. Set the size of your graph.

The Graph and Data

Below is the graph that we are going to create. It is adapted from a recent paper in the American Economic Review. You can download the data here.

Load and Preview Data

Our first step will be to load the data and take a quick look at it.

// Load all variables from 'int_rate.csv'
int_rate = loadd("int_rate.csv");

// Print the first 5 observations of 'int_rate'
print "First 5 observations:";
head(int_rate);

// Print the last 5 observations of 'int_rate'
print "Last 5 observations:";
tail(int_rate);

// Print descriptive statistics of our variables
call dstatmt(int_rate);

This will give us the following results:

First 5 observations:

               x             high              low
   0.00010000000       0.17140598        0.0000000
   0.00020000000       0.17140598        0.0000000
   0.00030000000       0.17140598        0.0000000
   0.00040000000       0.17140598        0.0000000
   0.00050000000       0.17140598        0.0000000

Last 5 observations:

               x             high              low
      0.99950000       0.17140598       0.23012203
      0.99960000       0.17140598       0.23012203
      0.99970000       0.17140598       0.23012203
      0.99980000       0.17140598       0.23012203
      0.99990000       0.17140598       0.23012203

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

x             0.5      0.289       0.0833      1e-4      0.999    9999    0
high       0.1714   1.04e-07     1.08e-14     0.171      0.171    9999    0
low       0.09374      0.108       0.0116         0      0.230    9999    0

Initial Graphs

Our first graphs will use the default GAUSS styling. We will create one graph indexing our x and y variables and another using a formula string.

Indexing

// Set our graph size to 500x400 pixels
plotCanvasSize("px", 500 | 400);

// Use indexing to select the 'x' and 'y' variables
plotXY(int_rate[.,"x"], int_rate[.,"high" "low"]);

Formula string

// Set our graph size to 500x400 pixels
plotCanvasSize("px", 500 | 400);

// Specify the 'x' and 'y' variables using a formula string
plotXY(int_rate, "high + low ~ x");

When we use a formula string with our plot functions, it tells GAUSS that we want to use the information from the dataframe.

When using a formula string in plots:

• The tilde symbol, ~, separates the y variables on the left from the x variable(s) on the right.
• If there is a single y variable, GAUSS will use that variable name to label the y axis. If there is more than one y variable, then the variable names will be added to the legend.
• The name of the x variable will be used to label the x-axis.

While this may not always be the information we want to be displayed in our final plot, it makes it convenient to quickly create graphs that are easier to interpret.

Plot Styling

Fp Next, we will adjust the styling to match our intended final plot.

To programmatically style our graph, the first thing we need to do is to create a plotControl structure and fill it with default values.

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

Legend styling

After the pointer to the plotControl structure we want to modify, &plt, the function plotSetLegend takes one required input and two optional ones.

1. Legend text: This controls the text that will be displayed in the legend. We want GAUSS to use the variable names from our input. Therefore, below, we set this to an empty string, "". This tells GAUSS that we do not want to modify the default behavior of the legend text.

   As we mentioned earlier, the default behavior for a graph created with a formula string with more than one y variable is to use the y variable names as the legend text elements.

2. Legend location: This input can be a string with text location specifications, or a 2x1 vector with the x and y coordinates for the location of the top-left corner of the legend.

3. Legend orientation: This input specifies whether the legend position should be stacked vertically or horizontally. We set it to 1 to indicate a vertical arrangement. It may help to remember that a 1 is a vertical essentially a vertical mark.

The first input to plotSetLegendBkd, after the plotControl structure pointer, controls the legend opacity. We set it to be 0% opaque, or 100% transparent.

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

Font styling

plotSetFonts provides a convenient way to set the font family, size, and color for any subset of the text in your graph. Below we set the font for 'all' of the text in the plot. However, there are many other options, including: "axes", "legend", "legend_title", "title", "ticks" and many more.

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

X-axis label

plotSetTextInterpreter tells GAUSS whether you would like text labels to be interpreted as:

• HTML
• LaTeX
• Plain text

Like plotSetFonts, it allows you to specify many different locations, or even, "all". Below, we set the x-axis to be interpreted as LaTeX and then use LaTeX in our x-axis label.

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

Main line styling

The "set2" color palette contains eight colors:

We want to use the third color for our first series, "high", and the second color for our second series, "low".

Additionally, we set the line width to 4 pixels and set the line style to 1 and 3 respectively. One indicates a solid line and three is for a dotted line.

clrs = getColorPalette("set2");

// Set the line width, line colors, and line style
plotSetLinePen(&plt, 4, clrs[3 2], 1|3);

Axes outline

The axes outline, or spine as they are called by other libraries, controls the lines around the edges of the data area. By default, the bottom x-axis and left y-axis are enabled. The code below will also turn on the lines on the top x-axis and right y-axis.

plotSetOutlineEnabled(&plt, 1);

Graph before annotations

If we draw the graph, using our previous styling and a formula string as shown below:

plotXY(plt, int_rate, "high + low ~ x");

we get the following plot:

Add Vertical Lines

Line styling

We will continue with the plotControl structure we created earlier and modify the line settings to match the vertical lines from the graph we are trying to reproduce.

// Set lines to be: 1 pixel wide, light gray (#CCC) and dashed style (2)
plotSetLinePen(&plt, 1, "#CCC", 2);

Draw the lines

We add the vertical lines using plotAddVLine. plotAddVLine takes an optional plotControl structure as the first input and then a vector of one or more x-axis locations at which to draw the vertical spanning lines.

// The x-axis locations for the vertical lines
ks = { 0.517, 0.653, 0.781 };

plotAddVLine(plt, ks);

Add Text Annotations

Style text boxes

The annotation styling functions use a plotAnnotation structure but work very similarly to the main plot styling (plotSet) functions. Therefore, we will just use comments to describe their actions.

struct plotAnnotation ant;
ant = annotationGetDefaults();

// Set text to be interpreted as LaTeX
annotationSetTextInterpreter(&ant, "latex");

// Turn off the text box bounding line, by setting:
//     line-width=0, line-color="" (ignore), line-style=-1 (no line)
annotationSetLinePen(&ant, 0, "", -1);

// Leave the font-family as default, "",
// Set the font-size to 14 points and the color to a
// dark gray, #333
annotationSetFont(&ant, "", 14, "#3333");

// Leave the annotation background color, "".
// Set the opacity to 0% (100% transparent)
annotationSetBkd(&ant, "", 0);

Draw the text boxes

After the optional plotAnnotation structure, plotAddTextbox takes 3 input arguments:

1. The text to display.
   
2. The x-axis coordinate.
   
3. The y-axis coordinate.
   

By default, the x and y-axis coordinates specify the location of the top-left of the bounding box that contains the text.

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

Full code

Below is the full code to create our graph.

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");

// 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);

Bonus Content: Text Box Anchor Position

For this case, we wanted the text boxes to appear to just the right of the vertical lines and the vertical position of the text boxes was not critical. Therefore, the default anchor position worked well.

However, if we had needed the text boxes to be towards the bottom of the graph, the first of them would have overlapped with one of our lines. We can see this by changing the plotAddTextbox lines to the following:

// Draw the text boxes at a lower position, y=0.04
plotAddTextbox(ant, "\\omega_1", ks[1], 0.04);
plotAddTextbox(ant, "\\omega_2", ks[2], 0.04);
plotAddTextbox(ant, "\\omega_3", ks[3], 0.04);

This makes the bottom of our graph look like this:

In this case, it would be nice to move the text boxes to the left of the vertical line. We can do this by using the final optional input of plotAddTextbox. It is a string that allows you to specify the position of the text box with respect to its anchor position.

The string options include:

• Vertical position: "top", "vcenter", "bottom".
  
• Horizontal position: "left", "hcenter", "right".
  

or "center" which is equivalent to "vcenter hcenter".

For this example, we will just move the text boxes to the left of the vertical lines which are at the same position as the text box's anchor locations:

// Draw the text boxes at a lower position, y=0.04
plotAddTextbox(ant, "\\omega_1", ks[1], 0.04, "left");
plotAddTextbox(ant, "\\omega_2", ks[2], 0.04, "left");
plotAddTextbox(ant, "\\omega_3", ks[3], 0.04, "left");

This gives us the following image:

Conclusion

Great job! You have learned how to:

1. Add and style text boxes with LaTeX.
2. Set the anchor point of text boxes.
3. Add and style vertical lines.
4. Automatically set legend text to use your dataframe's variable names.
5. Set the font for all or a subset of the graph text elements.
6. Set the size of your graph.
7. Control the position of text boxes with respect to their attachment point.

Further Reading

1. Visualizing COVID-19 Data with GAUSS 22
2. How to Mix, Match, and Style Different Graph Types
3. How to Create Tiled Graphs in GAUSS
4. Five Hacks for Creating Custom GAUSS Graphics

References

Farboodi, Maryam, and Péter Kondor. 2022. "Heterogeneous Global Booms and Busts." American Economic Review, 112 (7): 2178-2212. DOI: 10.1257/aer.20181830

When they're done right, graphs are a useful tool for telling compelling data stories and supporting data models. However, too often graphs lack the right components to truly enhance understanding.

In this blog, we look at how a few quick customizations help make graphs more impactful. In particular, we will consider:

• Using grid lines without cluttering a graph.
• Changing tick labels for readability.
• Using clear axis labels.
• Marking events and outcomes with lines, bars, and annotations.

Data

As an example, we will use New York Times COVID tracking data (available on GitHub). This data is part of the New York Times U.S. tracking project.

From this data, we will be using the rolling 7-day average of COVID cases per 100k provided by date for five states: Arizona, California, Florida, Texas, and Washington.

Creating a Basic Graph

Let's start by creating a basic panel data plot using:

• The plotXY procedure with dates.
• A formula string and the by keyword.

First we will load our data:

// Load original data
fname = "us_state_covid_cases.csv";
covid_cases = loadd(fname, 
                    "date($date) + cat(state) + cases + cases_avg_per_100k");

// Filter desired states
covid_cases = selif(covid_cases, 
                    rowcontains(covid_cases[., "state"], 
                                "Florida"$|"California"$|
                                "Arizona"$|"Washington"$|
                                "Texas"));

Note that in this step we've:

1. Specified the variables we want to load and their variable types.
2. Filtered our data to include only our states of interest.

Now, we can make a preliminary plot of the rolling 7 day average number of COVID-19 cases per 100,000 people:

// Plot COVID cases per 100K by state
plotXY(covid_cases, "cases_avg_per_100k ~ date + by(state)");

Customizing Our Graph

Our quick graph was a good starting point. However, a few customizations will help present a clearer picture:

• Adding y-axis grid lines will help us read COVID cases values more easily.
• Reformatting our x-axis tick labels to include months rather than quarters will make the dates more recognizable.
• Change axis labels.

Declaring a plotControl Structure

The first step for customizing graphs is to declare a plotControl structure and to fill it with the appropriate defaults:

// Declare plot control structure
struct plotControl myPlot;

// Fill with defaults for "xy" graph
myPlot = plotGetDefaults("xy");

Customizing Plot Attributes

After declaring the plotControl structure, we can use plotSet procedures to change the desired attributes of our graph.

Adding Y-Axis Grid Lines

First, to help make levels of COVID cases more clear, let's add y-axis grid lines to our plot using plotSetYGridPen.

The plotSetYGridPen procedure can be used to set the width, color, and style of the y-axis grid lines:

• Turn on y-axis major and/or minor grids.
• Set the width, color, and style of the grid lines.

// Turn on y-axis grid for the major ticks. Set the
// grid lines to be solid, 1 pixel and light grey
plotSetYGridPen(&myPlot, "major", 1, "Light Grey", 1);

Because GAUSS allows us to add and format y-axis and x-axis grid lines separately, we are able to improve readability with y-axis lines without adding the clutter of a full grid.

Customizing X-Axis Ticks

Next, let's turn our attention to the x-axis ticks. We will use three GAUSS procedures to help us customize our ticks:

First, let's change the format of the labels on the x-axis to indicate months rather than quarters:

// Display 4 digit year and month on 'X' tick labels
plotSetXTicLabel(&myPlot, "YYYY-MO");

Second, let's set the x-axis ticks to:

• Start in March of 2020 to correspond with the start of the pandemic.
• Occur every 3 months.

// Place first 'X' tick mark on March 1st, 2020
// with ticks occurring every 3 months
plotSetXTicInterval(&myPlot, 3, "months", asDate("2020-03"));

Third, let's increase the size of the axis tick labels:

// Change tic label font size
plotSetTicLabelFont(&myPlot, "Arial", 12); 

Updating Axis Labels

Finally, we change the axis labels:

// Specify the text for the Y-axis label as well as
// the font and font size for both labels
plotSetYLabel(&myPlot, "Cases per 100k", "Arial", 14);

// Specify text for the x-axis label
plotSetXLabel(&myPlot, "Date");

Now we can create our formatted graph:

// Plot COVID cases per 100K by state. Pass in the 'plotControl'
// structure, 'myPlot', to use the settings we applied above.
plotXY(myPlot, covid_cases, "cases_avg_per_100k ~ date + by(state)");

Highlighting Events

It's common with time series plots that we want to note specific dates or periods on the graph. GAUSS includes four functions, introduced in GAUSS 22, that make highlighting events easy.

As an example, let's add vertical lines to help compare July 4th, 2020 to July 4th, 2021.

Specifying Legend Behavior When Adding Lines

First, when adding new data to an existing plot, we need to specify how we want this data treated on the legend using the plotSetLegend procedure.

We can add a label for the line to the legend:

// Label next added line "Independence Day"
// and add to the legend
plotSetLegend(&myPlot, "Independence Day");

or we can tell GAUSS to not make any changes to the current legend:

// The empty string specifies that the legend 
// should remain unchanged when the next line is added.
plotSetLegend(&myPlot, "");

Specifying Line Style

Next, we will specify the style of our lines using the plotSetLinePen procedure. This procedure lets us set the width, color, and style of the lines added to the graph.

// Set the line width to be 2 pxs
// the line color to be #555555
// and the line to be dashed
plotSetLinePen(&myPlot, 2, "#555555", 2);

Adding Lines to Mark Events

Finally, let's add the lines marking Independence Day in 2020 and 2021.

We first specify the dates we want to add lines using asDate:

// Create string array of independence days
ind_days = asDate("2020-07-04"$|"2021-07-04");

Then we add our holidays to the existing graph using plotAddVLine:

// Add holidays to graph
plotAddVLine(myPlot, ind_days);

The complete code for adding the lines looks like this:

// Do not add vertical lines to the legend
plotSetLegend(&myPlot, "");

// Set the line width to be 2 pixels
// the line color to be a dark grey color, #555555,
// and the line to be dashed
plotSetLinePen(&myPlot, 2, "#555555", 2);

// Create string array of independence days
ind_days = asDate("2020-07-04"$|"2021-07-04");

// Add holidays to graph
plotAddVline(myPlot, ind_days);

Adding Bars to Mark Events

Now, let's add a vertical bar to mark the winter holidays time period of 2020. We will add a bar that marks the time span from Thanksgiving 2020 to New Year's Day 2021.

We first need to create a new plotControl structure to format our bars. Since we are adding a bar to the graph, we will fill our new plotControl structure with the defaults for a bar graph:

// Create plotControl structure
struct plotControl plt;

// Fill with default bar settings
plt = plotGetDefaults("bar");

Next, we can format our bar using the plotSetFill procedure. The plotSetFill procedure allows us to control the fill style, opacity, and color of graphed bars:

// Set bar to have solid fill with 20% opacity
// and grey color
plotSetFill(&plt, 1, 0.20, "grey");

We also have to specify the legend behavior when the bar is added. This time let's add a label to the legend for the "Winter Holidays":

// Add "Winter Holidays" to the legend
plotSetLegend(&plt, "Winter<br>Holidays");

Now we are ready to add the bar to our graph using the plotAddVBar procedure:

// Add a vertical bar to graph starting 
// on November 26th, 2020 and 
// ending January 1st, 2021
plotAddVBar(plt, asDate("2020-11-26"), asDate("2021-01"));

Adding Notes to Graphs

As final customization, let's add a note to our graph to label one of our holidays. We can do this using the plotAddTextBox procedure.

The plotAddTextBoxtakes three required inputs:

• The text to be added to the graph.
• The x location where the text should start.
• The y location where the text should start.

// Label the 2020 Independence Day line
plotAddTextBox("← Independence Day", asDate("2020-07-04"), 80);

Conclusion

In this blog, we see how a few customizations and enhancements can make plots easier to read and more impactful.

In particular, we covered:

• Using grid lines without cluttering a graph.
• Changing tick labels for readability.
• Using clear axis labels.
• Marking events and outcomes with lines, bars, and annotations.

Further Reading

• How to Create Tiled Graphs in GAUSS
• How to Interactively Create Reusable Graphics Profiles
• Five Hacks For Creating Custom GAUSS Graphics
• How to Mix, Match, and Style Different Graph Types

References

"The New York Times. (2021). Coronavirus (Covid-19) Data in the United States. Retrieved 12-05-2021, from https://github.com/nytimes/covid-19-data."

Placing graphs next to each other can be a great way to present information. Today we will learn how to create tiled graphs in GAUSS using plotLayout.

We will work through two simple examples where you will learn:

• How to created tiled layouts which are uniform and layouts with graphs of different sizes.
• Which graph types can be used with plotLayout.
• How to clear your tiled graph layouts.

How to use plotLayout

In GAUSS, plotLayout allows you to arrange multiple graphs in a tiled layout. It takes the following inputs:

g_rows

The number of rows in the graph grid.

g_cols

The number of columns in the graph grid.

idx

The cell in which to place the next graph, walking along the rows.

---

Therefore, the call:

plotLayout(2, 3, idx);

will:

1. Split the graph canvas into a 2x3 grid.
2. Place the next graph in the cell corresponding to the value of idx as shown below.

Which Graph Types Can be Used with plotLayout?

Below is a partial list of the GAUSS graph functions which can be used with plotLayout. Each cell is independent and may contain a different graph type.

Example 1: Uniform Grid Layout

Now that we have seen the basics of plotLayout, let's put together a simple example placing 4 graphs in a 2x2 grid.

new;

// Create the vector 0.1, 0.2, 0.3...3.0
x = seqa(0.1, 0.1, 30);

/*
** First subplot
*/

// Divide the graph canvas into a 2x2 grid
// and place the next graph in the 1st cell
plotLayout(2, 2, 1);

// Create 'y1' and draw graph
y1 = exp(x);
plotXY(x, y1);

/*
** Second subplot
*/
plotLayout(2, 2, 2);

y2 = sin(x);
plotXY(x, y2);

/*
** Third subplot
*/
plotLayout(2, 2, 3);

y3 = cos(x);
plotXY(x, y3);

/*
** Fourth subplot
*/
plotLayout(2, 2, 4);

y4 = ln(x);
plotXY(x, y4);

After running the above code, you should see a graph that looks like this:

Clearing the Plot Layout

What do you think would happen if we created another plot right after running the code from the previous section? Let's try it with the code below.

// Create new 'y' by adding uniform random
// numbers to the 'x' created above
y = x + rndu(30,1);

// Draw graph
plotScatter(x, y);

This time your graph should look like this:

As we can see, GAUSS remembers the grid we created with our last call to plotLayout as well as the chosen cell index. This state will persist until one of the following statements has been executed:

// Subsequent graphs will fill the entire graph canvas.
plotClearLayout();

// 1. Clear all data from the GAUSS workspace.
// 2. Clear the current plot layout state, so that new graphs will fill the entire graph canvas.
new;

Example 2: Mixed Size Grid Layout

Sometimes your graphs will look better with tiles of different sizes. Fortunately, as we saw earlier, plotLayout only computes and stores coordinates.

Therefore, each call to plotLayout is independent of any previous calls. As long as your graph tiles do not overlap, each call to plotLayout may use a different grid size. This allows you to mix graphs of different sizes in the same graph canvas.

Let's modify our previous example, so that the third graph takes up the entire second row.

new;

// Create the vector 0.1, 0.2, 0.3...3.0
x = seqa(0.1, 0.1, 30);

/*
** First subplot
*/

// Divide the graph canvas into a 2x2 grid
// and place the next graph in the 1st cell
plotLayout(2, 2, 1);

// Create 'y1' and draw graph
y1 = exp(x);
plotXY(x, y1);

/*
** Second subplot
*/
plotLayout(2, 2, 2);

y2 = sin(x);
plotXY(x, y2);

/*
** Third subplot
**
**     Change to interpret the graph canvas
**     as a 2x1 grid and place the next graph
**     in the second cell.
*/
plotLayout(2, 1, 2);

y3 = cos(x);
plotXY(x, y3);

In this code example, we changed the inputs to plotLayout instructing it to:

• Split the graph canvas into a grid with 2 rows and 1 column.
• Place the next graph in the second cell.

This results in the graph below with the third plot taking up the entire second row of the graph canvas.

Conclusion

Congratulations, you now have another tool in your graph creating toolbox! You have learned how to:

1. Create tiled graphics in GAUSS.
2. Create uniform and mixed size layouts.
3. Clear the plot layout grid.

Next Steps

• How to Mix, Match and Style Different Graph Types.
• Five Hacks For Creating Custom GAUSS Graphics.
• How to Interactively Create Reusable Graphics Profiles.

You probably know that you can use GAUSS code to create repeatable styling for your graphs. However, you might not know that GAUSS also allows you to build reusable graphics profiles with a few clicks of your mouse.

We will show you how to clone existing graphics profiles and how to control:

• Font settings for the title, axes labels, and tick labels.
• Line colors and styles.
• Legend location and styling.

While this tutorial will not cover all available options, you should learn enough to be comfortable making most other changes without additional help.

Our Project

For this tutorial, our goal will be to create a graph profile to replicate the style of the graph below. Data for the graph can be downloaded from here.

Video Tutorial

This video tutorial will show you how to:

1. Clone an Existing Graph Profile.
2. Modify Title and Axis Font Settings.
3. Modify Line Style and Legend Descriptions.
4. Set the Legend Properties.
5. Set the Y-axis Label.

or read the text instructions below.

Step 1: Clone an Existing Graph Profile

1. Select Tools > Preferences from the main GAUSS menu.
   
2. Select Graphics on the left side of the Preferences window.
   
3. Select the Profiles button at the top of the Graphics Preferences.
   
4. Select the profile you would like to clone from the dropdown list.
   
5. Select the Clone button.
   
6. Enter the name for your new profile and click OK.
   

Step 2: Modify Font Settings

Set the Title Font

Using the graphics profile created in the previous step:

1. Select Title from the list of graph settings on the left.
   
2. Click Change button on the right.
   

This will open your operating system's font dialog, where you can select your desired font, weight, and size:

Set the Axes Label and Tick Label Fonts

1. Select Axes Style from the list of graph settings on the left.
   
2. From the Caption section, select the Change button to modify the axes label font.
   
3. Click the Numbers Change button and select your preferred font settings for the tick labels.
   

Step 3: Modify Line Style and Legend Descriptions

We'll start by modifying the third line which marks the date of the first U.S. location transmission.

1. Select Series 3.
2. Enter the legend text for this line in the Legend Title text input box.
3. Double-click the color box next to Line Color and select a gray color.
4. Select Dash Line from the dropdown box next to Style.

Then repeat step 2 above to add the legend text for Series 1 and Series 2.

Step 4: Set the Legend Properties

1. Select Legend.
2. Click the font Change button and set the desired font and font size.
3. Select the legend location, using the Vertical Position, Horizontal Position, Inside/Outside and Orientation options.
4. Double-click the color box next to Line Color and set it to white so the legend outline is unseen.

Step 5: Set Y-axis Label

1. Select Axes Text.
2. Enter the desired axis label in the appropriate text box.

Use the Custom Graphics Profile

You can access the settings from a graph profile using the plotGetDefaults function as you would for the default settings. Below is a simple example.

// Load variables
Y = loadd("cook-county-covid.csv", "cases + deaths");

x = seqa(1, 1, rows(Y));

// Declare myPlot to be a plotControl structure
// and fill with the settings from our covid profile
struct plotControl myPlot;
myPlot = plotGetDefaults("covid");

// Draw plot using covid profile settings
plotXY(myPlot, x, Y);

which will produce the plot below:

Further Customize

While the graphs for a given project may share many features, it is likely that some attributes such as the title or legend text will need to be different. You could clone your custom profile and make these changes. However, it might be simpler to make these changes in your code.

Fortunately, you can use the plotSet functions to further customize the settings for a particular graph. You can modify any settings that you would like to change.

The code below shows how to change the title, keeping all other settings unchanged.

// Load variables
Y = loadd("cook-county-covid.csv", "cases + deaths");

x = seqa(1, 1, rows(Y));

// Declare myPlot to be a plotControl structure
// and fill with the settings from our covid profile
struct plotControl myPlot;
myPlot = plotGetDefaults("covid");

// Set title text
plotSetTitle(&myPlot, "COVID-19 Cook County");

// Draw plot using covid profile settings
plotXY(myPlot, x, Y);

These settings will not modify the custom graphics profile that you created. Next time you call myPlot = plotGetDefaults("covid"), myPlot will be filled with the custom profile settings that you selected in the Preferences dialog window.

Full Code for Time Series Plot

Full code to create the time series plot shown at the top of this post, using the "covid" custom graphics profile we created, can be downloaded here.

Conclusion

Great job! You've learned how to interactively create custom graphics profiles that can be easily reused and further modified.

Next Steps

• How to Mix, Match and Style Different Graph Types.
• Five Hacks For Creating Custom GAUSS Graphics.
• Graph high-frequency Forex data.

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 includes a plethora of tools for creating publication-quality graphics. Unfortunately, many people fail to use these tools to their full potential. Today we unlock five advanced GAUSS hacks for building beautiful graphics:

1. Using HSL, HSLuv, and Colorbrewer color palettes.
2. Controlling graph exports.
3. Changing the plot canvas size.
4. Annotating graphs with shapes, text boxes, and lines.
5. Using LaTeX for GAUSS legends, labels and text boxes.

Using custom color palettes

GAUSS color schemes include 30 built-in color palettes designed for optimal visual impacts. These include pre-made palettes for sequential, quantitative and diverging data and colorblind friendly palettes.

If you can't find the pre-made palette you like, you can create your own evenly spaced colors in HSL hue space, evenly spaced circular hues in the HSLuv system, or blend custom color palettes.

Color palettes can be controlled using a number of GAUSS procedures:

As an example, let's look at getting the first three colors from the ColorBrewer Dark2 color palette:

// Get the first 3 colors from the ColorBrewer 'Dark2' palette
clrs = getColorPalette("Dark2", 3);

The resulting colors are:

Once the color palette is set, we can use these colors in GAUSS graphs for the line, background, or bar colors.

For example, to use our color palette to plot different colors for each series in a bar graph we would use plotSetFill to change the color assignment in our plotControl structure:

// Declare plotControl structure
struct plotControl myPlot;

// Initialize plotControl structure
myPlot = plotGetDefaults("bar");

// Set all bars to have a solid fill with the colors
// assigned to 'clrs' in the previous code box
textures = 1;
plotSetFill(&myPlot, textures, 1, clrs);

// Create data
x = seqa(1, 1, 5);
y1 = { 1.5, 2, 3, 0.5, 1 };
y2 = { 3, 6.7, 8, 2, 0.49 };
y3 = { 2, 3.4, 2.4, 1, 3 };

// Draw bar graph
plotBar(myPlot, x, y1~y2~y3);

Bar graph with Colorbrewer 'Dark2' color palette.

Controlling graph exports

Our second hack, the GAUSS plotSave procedure, is a handy tool which allows us to control the file type, size, and dots per inch (DPI) of exported graphs in a single command.

plotSave(filename, size); 
plotSave(filename, size, units);
plotSave(filename, size, units dpi);

The procedure is easy to use and has two required inputs and two optional inputs:

filename

String, name of the file to create with a file type extension. Available file extensions include: .jpg, .plot, .png, .pdf, .svg, .tiff.

size

2x1 vector, dimensions of the saved graph in specified units. The default unit is centimeters.

units

Optional input, String, type of units dimension is specified in. Valid options include:
    "cm" Centimeters (Default)
    "mm" Millimeters
    "in" Inches
    "px" Pixels

dpi

Optional input, scalar, requested dots per inch when saving file. Defaults to current system DPI. dpi determines the number of pixels rendered when saving a file in terms of physical dimensions (cm, mm, in).

---

For example, if a publisher requests a 640 x 480 pixel .png plot, we specify:

// Save the graph as a 640 wide by 480 tall PNG file
plotSave("mygraph.png", 640 | 480, "px");

However, if we need an 11 x 8.5 inch PDF at 300 DPI for a flyer, we specify:

// Save the graph as a 11 x 8.5 inch PDF at 300 DPI
plotSave("mygraph.pdf", 11 | 8.5, "in", 300);

There are some helpful things to note about the plotSave procedure:

• The size input is a required input for all file types except .plot files.
• The unit input is ignored if the file is a .plot file.
• The dpi input determines the number of pixels rendered when saving a file in terms of physical dimensions (cm, mm, in). Specifying the dpi parameter has no effect if the specified units are pixels (px).

Changing the plot canvas size

There may be times when we want to see how a graph looks at a different size before we export it. This can be easily done with our next tool, plotCanvasSize.

The GAUSS procedure plotCanvasSize adjusts plot canvas sizes programmatically based on specifications in centimeters, millimeters, inches or pixels.

To produce our graph on a 750 px by 350 px canvas, as shown above, we place the call to plotCanvasSize prior to calling our graphic procedure:

/*
** Make this call before your plot to set the graph canvas
** to 750 px by 530 px as shown in the image above
*/
plotCanvasSize("px", 750|530);

When we are ready to go back to the default canvas size when simply tell GAUSS to "fill" the plot canvas:

// Go back to factory canvas size
plotCanvasSize("fill");

Annotating graphs with shapes, text boxes, and lines

Annotations make graphs more professional, more readable and easier to interpret. There are three easy-to-use functions for adding annotations to any existing GAUSS plot:

To create annotations there are a few key things to remember:

• The location of an annotation is specified using starting, and when applicable ending, x and y coordinates.
• We can use default settings for annotations or we can customize the appearance using the optional plotAnnotation structure.
• If we plan on using our annotations often and want to use the same styling, instead of going through multiple steps to set up the style each time, we can create a simple procedure to do the set up:

/*
** Add the procedure below to your user library
** and you will only need one line for all the settings
*/
plotAddTextbox(grayTextSettings(), "My customized text box", 0.15, 0.2);

proc (1) = grayTextSettings();
    struct plotAnnotation mytextbox;

    mytextbox = annotationGetDefaults();
    annotationSetBkd(&mytextbox, "#DDDDDD", 0.3);
    annotationSetFont(&mytextbox, "times", 18, "#555555");
    annotationSetLineThickness(&mytextbox, 2);
    annotationSetLineColor(&mytextbox, "#555555");
    retp(mytextbox);
endp;

Using LaTeX for GAUSS legends, label and text boxes

LaTeX is a powerful tool for generating scientific and technical documents because of its flexibility and ability to transcribe mathematical functions. GAUSS allows users to use the MathJax library for the interpretation of a wide variety of LaTeX commands.

To use LaTeX, we must first set the GAUSS text interpreter to ‘latex’ using the plotSetTextInterpreter procedure. This procedure requires three inputs:

&myPlot

A plotControl structure pointer.

interpreter

String, "html", "plain", "latex".

location

String, "all", "legend", "title" or "axes". Default is "all".

For example, let's use LaTeX for our legend, axes, and title:

new;

// Declare plotControl structure
struct plotControl myPlot;

// Initialize plotControl structure
myPlot = plotGetDefaults("xy");

// Set up text interpreter
plotSetTextInterpreter(&myPlot, "latex", "all");

We can now use LaTeX syntax for labeling our graph:

// Set up legend in LateX format
string legend_string = {
"y_1 = \\cos{(x)}",
"y_2 = \\sin{(\\frac{x}{2})} = \\pm \\sqrt{\\frac{1-\\cos{(x)}}{2}}",
"y_3 = \\cos{(\\frac{x}{2})} = \\pm \\sqrt{\\frac{1+\\cos{(x)}}{2}}" };

plotSetLegend(&myPlot, legend_string, "bottom right inside",1);

There are a few things to remember when using LaTeX in GAUSS:

1. Since backslashes are used for escape sequences in strings, you must use double backslashes.
2. Strings interpreted as LaTeX are automatically in ‘inline equation mode’. Therefore to add regular text, you must enclose the text inside of \text{ }. For example:

   /*
   ** Since LaTeX does not respect spaces inside of equations
   ** add a space after 'equation is' inside of the text section
   */
   "\\text{The equation is } \\alpha + \\beta X"

3. Text inside of a '\text{}' section will use the font set by the user as it would if the text interpreter were set to plain or HTML.

   /*
   ** 'Posterior distribution' will be in Times 24 point font
   ** The greek lambda will be proportional in size to Times 24, but will be in TeX font
   */
   plotSetTitle(&myPlot, "\\text{Posterior distribution of  } \\lambda_1", "Times", 24);

Conclusion

GAUSS graphics tools have been created with the end goal of generating publication quality graphs. In this blog we highlight five advanced hacks for raising the bar on your custom GAUSS graphics:

1. Using HSL, HSLuv, and Colorbrewer color palettes.
2. Controlling graph exports.
3. Changing the plot canvas size.
4. Annotating graphs with shapes, text boxes, and lines.
5. Using LaTeX for GAUSS legends, labels and text boxes.

For more tips and graph examples, please see our GAUSS plot library.

Last week we learned how to use the date keyword to load dates into GAUSS. Today, we will plot some high-frequency Forex data.

The data

Today's dataset (usdcad_tick.csv) contains tick data for a little over 30,000 observations of the bid price for the USD/CAD currency pair from January 2, 2018.

This file has two variables:

• timestamp: The time of the bid as a POSIX date/time (seconds since Jan 1, 1970).
• bid: The bid price.

The first few observations of the file look like this:

timestamp,bid
1514872801.247, 1.25372
1514872801.497, 1.25376
1514872801.747, 1.25373
1514872802.247, 1.25377
1514872802.497, 1.25377

The fractional portion of the timestamp data represents nanoseconds.

plotTSHF

plotTSHF is a function which will draw graphs of irregularly spaced and high-frequency time series data. It has three required inputs:

date_vec

Tx1 vector containing POSIX date/times for each observation.

label_unit

The unit to use for X-axis tick labels. Valid options include:

• milliseconds
• seconds
• minutes
• hours
• days
• months
• quarters
• years

y

Tx1 vector or TxP matrix containing the data to plot.

Basic plot

We can plot our dataset with the following code:

// Load all observations of both variables
fname = "usdcad_tick.csv";
data = loadd(fname);

// Split variables into separate vectors
timevec = data[.,1];
bid = data[.,2];

// Plot data
plotTSHF(timevec, "hours", bid);

and we will see a graph that looks like this:

label_unit

Most of the code we used to create this graph should be fairly straightforward, with the possible exception of the label_unit input.

plotTSHF(timevec, "hours", bid);

In the above line of code, the label_unit is "hours". This tells GAUSS that we would like X-tick labels to be set at even hours.

If we used "days" we would not see any X-tick labels. This is because our data is from 06:00-18:00 on the same day. Since the time series data does not cross from one day to another, the graph does not contain the start of a day at which to place the tick label.

Customize tick labels

Now we will use plotSetXTicInterval to set the X-ticks to appear every 60 minutes, starting at 06:30.

To accomplish this, we will have to take the following steps:

1. Set the label_unit passed to plotTSHF to "minutes".
   • This step tells plotTSHF to place the X-tick labels at even minutes.
2. Set the tick_interval input to plotSetXTicInterval to be 60.
   • Since the tick_interval is in terms of the plotTSHF label_unit, setting tick_interval to 60 will set the X-ticks to be placed every 60 minutes.
3. Set the first_labeled input to plotSetXTicInterval to be a POSIX date which equals Jan 2, 2018 06:30.
   • Since plotTSHF uses only POSIX date/times, we must specify the first X-tick to label as a POSIX date/time.

// Load all observations of both variables
fname = "usdcad_tick.csv";
data = loadd(fname);

// Split variables into separate vectors
timevec = data[.,1];
bid = data[.,2];

// Declare 'myPlot' to be a plotControl struct
// and fill with default values
struct plotControl myPlot;
myPlot = plotGetDefaults("xy");

// Convert the DT Scalar date to POSIX
// YYYY MO DD HH MI SS
// 2018 01 02 06 30 00
first_lbl = dttoposix(2018010206300);

// Draw X-tick labels every 60 minutes,
// starting at Jan 2, 2018 at 06:30
plotSetXTicInterval(&myPlot, 60, first_lbl);

// Plot data (notice we pass in the plotControl struct)
plotTSHF(myPlot, timevec, "minutes", bid);

The above code will create a graph like shown below.

Conclusions

Congratulations! You have learned how to:

1. Plot high-frequency time series data with plotTSHF, using POSIX date/times.
2. Customize the frequency and starting point of X-tick labels for time series graphs using plotTSHF.

Code and data from this blog can be found here.