Basic graph with programmatic customization

Basic graphing in GAUSS with programmatic customization

Minimum GAUSS version: 14.0

For this tutorial, we will use an Excel® file containing exposure to a nuclear site for a few counties in Washington state and the cancer mortality in those counties. You can download the Excel® file here.

The contents of the data file look like this:

  A B C
1 County Exposure Mortality
2 Umatilla 2.49 147.1
3 Morrow 2.57 130.1
4 Gilliam 3.41 129.9
5 Sherman 1.25 113.5
6 Wasco 1.62 137.5
7 HoodRiver 3.83 162.3
8 Portland 11.64 207.5
9 Columbia 6.41 177.9
10 Clatsop 8.34 210.3

Step 1: Load the data

We will start by loading the exposure and mortality columns into a GAUSS matrix. First save the hanford.xls file that you downloaded from the link above to your computer and set your GAUSS working directory to the folder in which you saved the Excel® file. Then load the data with the following command:

//Load all data from columns B2:C10
//into a GAUSS matrix named 'data'
data = xlsReadM("hanford.xls", "B2:C10");
//Load all data from columns B2:C10
//into a GAUSS matrix named 'data'
data = xlsReadM("hanford.xls", "B2:C10", 1, "");

Now data should be a 9x2 GAUSS matrix where the first column is the exposure data and the second column is the mortality data. Let's create two new GAUSS matrices, one named exposure and one named mortality, to make the code more readable.

//Create a new matrix 'exposure' containing
//all observations from the first column of 'data'
exposure = data[.,1];

//Create a new matrix 'mortality' containing
//all observations from the second column of 'data'
mortality = data[.,2];

Step 2: Create a basic scatter plot

We are wondering if our data shows a relationship between nuclear exposure and cancer mortality. A scatter plot is a good way to attempt to visualize this relationship. We can create a simple scatter plot of our two variables like this:

//Create scatter plot
plotScatter(exposure, mortality);

After running the code above you should get an image that looks similar to this:

Basic GAUSS scatter plot of nuclear exposure data.

Step 3: Customize the plot

Our initial graph seems to show a relationship, which makes the data more interesting. Next we need to customize this graph a bit so that when we share this graph with others, they can understand what it represents.

Our first graph used the default settings for scatter plots. You can view and modify those graphically by selecting Tools->Preferences->Graphics from the main GAUSS menu. It is often desirable, however, to customize your graph as part of a program so that it can be easily replicated. That is our focus for this tutorial.

The plotControl structure

A plotControl structure holds all of the settings for creating a GAUSS graph. To use a plotControl structure we need to:

  1. Declare a variable to be an instance of a plotControl.
    //Declare 'myPlot' to be an instance of a plotControl structure
    struct plotControl myPlot;

    This tells GAUSS which variable you would like to be the plotControl structure.

  2. Fill this plotControl structure with the default values, using the function plotGetDefaults.
    //Fill 'myPlot' with the default values for a scatter plot
    myPlot = plotGetDefaults("scatter");

    plotGetDefaults takes one argument--a string, specifying the plot type. Valid inputs include: "bar", "box", "contour", "scatter", "surface" and "xy".

  3. Apply our desired changes.

    For now, we will just set the title for the plot as well as the X and Y axis labels. To make it more convenient to figure out which function to use, all of the functions for setting plot attributes start with plotSet. If we type plotSet in the GAUSS editor, we will get a dropdown list showing us many functions with names that communicate their function:

    Autocomplete for plotSet functions in GAUSS.

    The first argument of each of the plotSet functions is going to be a pointer to the plotControl structure that you are using. This may sound difficult, or arcane--but all you need to know is that you will need to place an ampersand & in front of the structure name. Fortunately, the function tooltips will remind you.

    GAUSS function tooltip.

    The inputs to plotSetTitle are:

    &myPlot A pointer to a plotControl structure.
    title String to display as the graph title.
    font Optional input. String, name of font to use for title.
    fontSize Optional input. Scalar, size of font in points.
    fontColor Optional input. String, name of font color.

    Notice that the inputs inside of the square brackets [] are optional inputs.

    //Set the title
    plotSetTitle(&myPlot, "Nuclear Exposure vs Cancer Mortality", "Arial", 16);
    //Set the label for the X-axis
    plotSetXLabel(&myPlot, "Exposure");
    //Set the label for the Y-axis
    plotSetYLabel(&myPlot, "Mortality");
  4. Pass this plotControl structure to our plot creation call.
    In our original call to plotScatter, we passed in only the data that we wanted to graph. This tells GAUSS to use the default plot attributes as we mentioned earlier. If we would like to supply a plotControl structure with settings to use, we can pass that in as the optional first argument to any of the GAUSS plotting functions:

    //Draw scatter plot with settings from 'myPlot'
    plotScatter(myPlot, exposure, mortality);
  5. After the code above, our updated plot should look more like this:

    GAUSS scatter plot with customized title and axis labels.

    Putting it all together

    The following code will reproduce the final figure from this tutorial. Future tutorials will describe how to create more complex graphics in GAUSS.

    //Load exposure and mortality data from
    //2nd and 3rd columns of 'hanford.txt'
    data = xlsReadM("hanford.xls", "B2:C10");
    //Assign individual variables
    exposure = data[.,1];
    mortality = data[.,2];
    //Declare 'myPlot' to be a 'plotControl' structure
    struct plotControl myPlot;
    //Fill 'myPlot' with default settings for a scatter plot
    myPlot = plotGetDefaults("scatter");
    //Set the title
    plotSetTitle(&myPlot, "Nuclear Exposure vs Cancer Mortality", "Arial", 16 );
    //Set the axis labels
    plotSetXLabel(&myPlot, "Exposure");
    plotSetYLabel(&myPlot, "Mortality");
    //Draw the customized graph
    plotScatter(myPlot, exposure, mortality);