Making Your GAUSS Plots More Informative: Working with Legends

by Eric · Published February 24, 2025

Introduction

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.

GAUSS Legend Customization Functions
Function Name	Description	Example
plotSetLegend	Defines a legend for the plot with custom labels.	plotSetLegend(&myPlot, label [, location, orientation]);
plotSetLegendBkd	Sets the opacity and color for the background of a graph legend.	plotSetLegendBkd(&myPlot, opacity [, bkd_clr]);
plotSetLegendBorder	Controls the color and thickness of the legend border.	plotSetLegendBorder(&myPlot, clr [, thickness]);
plotSetLegendFont	Customizes the font style, size, and color of legend text.	plotSetLegendFont(&myPlot, font [, font_size, font_color]);
plotSetLegendTitle	Controls the legend title.	plotSetLegendTitle(&myPlot, title)
plotSetTextInterpreter	Controls the text interpreter settings for a graph.	plotSetTextInterpreter(&myPlot, interpreter [, location]);

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