The Basics (GPL)

The GPL example below creates a simple bar chart. A summary of the GPL follows the bar chart.

Note: To run the examples that appear in the GPL documentation, they must be incorporated into the syntax specific to your application. For more information, see Using the Examples in Your Application (GPL).

Figure 1. GPL for a simple bar chart
SOURCE: s = userSource(id("Employeedata"))
GGRAPH
  /GRAPHDATASET NAME="graphdataset" VARIABLES=jobcat salary
  /GRAPHSPEC SOURCE=INLINE.
BEGIN GPL
  SOURCE: s=userSource(id("graphdataset"))
  DATA: jobcat=col(source(s), name("jobcat"), unit.category()) 
  DATA: salary=col(source(s), name("salary")) 
  SCALE: linear(dim(2), include(0)) 
  GUIDE: axis(dim(2), label("Mean Salary")) 
  GUIDE: axis(dim(1), label("Job Category")) 
  ELEMENT: interval(position(summary.mean(jobcat*salary)))
END GPL.
Figure 2. Simple bar chart
Simple bar chart

Each line in the example is a statement. One or more statements make up a block of GPL. Each statement specifies an aspect of the graph, such as the source data, relevant data transformations, coordinate systems, guides (for example, axis labels), graphic elements (for example, points and lines), and statistics.

Statements begin with a label that identifies the statement type. The label and the colon (:) that follows the label are the only items that delineate the statement.

Consider the statements in the example:

  • SOURCE. This statement specifies the file or dataset that contains the data for the graph. In the example, it identifies userSource, which is a data source defined by the application that is calling the GPL. The data source could also have been a comma-separated values (CSV) file.
  • DATA. This statement assigns a variable to a column or field in the data source. In the example, the DATA statements assign jobcat and salary to two columns in the data source. The statement identifies the appropriate columns in the data source by using the name function. The strings passed to the name function correspond to variable names in the userSource. These could also be the column header strings that appear in the first line of a CSV file. Note that jobcat is defined as a categorical variable. If a measurement level is not specified, it is assumed to be continuous.
    Note: Starting with IBM® SPSS® Statistics 28.0.1, GPL DATA statements are optional.
  • SCALE. This statement specifies the type of scale used for the graph dimensions and the range for the scale, among other options. In the example, it specifies a linear scale on the second dimension (the y axis in this case) and indicates that the scale must include 0. Linear scales do not necessarily include 0, but many bar charts do. Therefore, it's explicitly defined to ensure the bars start at 0. You need to include a SCALE statement only when you want to modify the scale. In this example, no SCALE statement is specified for the first dimension. We are using the default scale, which is categorical because the underlying data are categorical.
  • GUIDE. This statement handles all of the aspects of the graph that aren't directly tied to the data but help to interpret the data, such as axis labels and reference lines. In the example, the GUIDE statements specify labels for the x and y axes. A specific axis is identified by a dim function. The first two dimensions of any graph are the x and y axes. The GUIDE statement is not required. Like the SCALE statement, it is needed only when you want to modify a particular guide. In this case, we are adding labels to the guides. The axis guides would still be created if the GUIDE statements were omitted, but the axes would not have labels.
  • ELEMENT. This statement identifies the graphic element type, variables, and statistics. The example specifies interval. An interval element is commonly known as a bar element. It creates the bars in the example. position() specifies the location of the bars. One bar appears at each category in the jobcat. Because statistics are calculated on the second dimension in a 2-D graph, the height of the bars is the mean of salary for each job category. The contents of position() use GPL algebra. See the topic Brief Overview of GPL Algebra for more information.

Details about all of the statements and functions appear in GPL Statement and Function Reference.