Five Hacks For Creating Custom GAUSS Graphics

by Eric · Published March 16, 2019 · Updated April 7, 2020

Introduction

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.

Eric( Director of Applications and Training at Aptech Systems, Inc. )

Eric has been working to build, distribute, and strengthen the GAUSS universe since 2012. He is an economist skilled in data analysis and software development. He has earned a B.A. and MSc in economics and engineering and has over 18 years of combined industry and academic experience in data analysis and research.