Next Previous Contents

5. The graph module

GLE allows the user to produce a graph from data in a separate file or by defining a formula within a program script. The advantage of using GLE to produce graphs lies in its flexibility and the degree of control it allows over the final apperance. However, GLE does not include a dedicated spreadsheet. There is, of course, nothing to prevent us from preparing the data in a traditional spreadsheet and then producing the finished graph in GLE.

5.1 Graph basics

The graph module is a separate enitity within a GLE program. The commands begin graph and end graph define the limit of the module. Outside of these commands we are free to use any standard GLE command, between them there is a special command set appropriate for graph drawing. The following example draws a simple graph using data from a separate file.


!mygraph.gle - Some of the simple graph drawing commands
size 10 13                              !Sets the size of the paper
begin graph
        size 10 10                      !Sets the size of the graph
        data mydata.dat                 !Reads data from mydata.dat
        title "My first Graph" hei 1 color red dist 2
        yaxis min 0                     !Sets the y axis to zero
        d1 line marker circle msize 0.2
end graph                               

The data file (mydata.dat), in the same directory as the source code, is:
1 2
2 6
3 2
4 5
5 9

The first command, size, sets the size of the paper we are working with. On this paper we can place any number of graphs or other drawings, though in this case we have only a single graph. The second size command, within the graph loop, sets the size of the graph within the page. To separate the graph from the rest of the page GLE automatically scales the graph to 70% of the given size and also adds a box. Entering the command nobox within the graph loop will remove the box. To change either or both of the default scaling we use the commands vscale and hscale. For example, inserting the commands:

size 10 10
nobox
vscale 1.2
hscale 1
would remove the box and scale the vertical axis to 12cm and the horizontal axis to 10cm. To set the graph size to 100% and remove the box we can use the shortcut command fullsize within the module.

Data is stored in GLE as a set of (x,y) coordinates, each with a name given by dn where n is an integer. The default for the first data set is d1, d2 for the second, and so on. The data command tells GLE which file to use for the data set, and in the above example we use the default settings. If we wish we may specify any data set.

data mydata.dat d34
More usefuly if we have a data file with multiple columns, we can define a data set using any pair of columns.
data experiment.dat d1=c1,c2 d2=c1,c3
Which would read columns 1 and 2 of experiment.dat into d1, and columns 1 and 3 into d2.

The title command places, as might be expected, a title onto the graph. The title must be contained within quotation marks and may be followed by commands defining the height, colour, or font of the title. The dist command sets the distance of the title (in cm) from the top of the x-axis, the default setting is zero with positive and negative values also allowed.

Another default setting that is often altered is GLE's habit of taking the origin of the graph to be the lowest (x,y) data pair. To set the origin and the maximum we use the command,

xaxis min 0 max 5 dpoints 1
yaxis min 0 max 10 dpoints 1
Where min and max determine the maximum and minimum values of the x and y axis. dpoints sets the number of decimal places displayed in the data.

To plot the data we use the data label (d1, d2, d3, ...) followed by a set of commands that determine how the data is plotted. The line command tells GLE to join the points with a series of straight lines. We can apply the usual formatting options for lines by adding qualifiers after the main data command.

d2 line lstyle 2 lwidth 0.01 color red

The d1 marker command indicates that each point should be represented by a set of circular markers of size 0.2cm. The markers are identical to those used outside of the graph module: a list can be found in the appendix. By default neither lines or markers are drawn by GLE, and an error in this command can often be the reason behind blank graphs.

The dataset commands have the same syntax as the set function introduced in the previous section. The subcommands can appear on the same line, or on separate lines each with its own data label. The following script is identical to the single line command,

d1 line
d1 marker circle 
d1 msize 0.2
Often we shall use the longer version when highlighting new commands or to make programs easier to understand. If we wish to format a group of data types at the same time then we can also use the dn command, which applies to all the defined data sets at the same time.
dn marker circle
d3 marker square
This will draw all of the data sets with circles except for the set d3 which will be drawn with squares. Notice that the dn command will overwrite any previous formatting commands, so if we had written:
d3 marker square
dn marker circle
All the data sets would be circles regardless of the d3 marker square command.

If a data point is missing (there is no value supplied in the data file) then, by default, GLE will not connect the points on either side of the blank. To connect all points, even if they are not consecutive, we can add the nomiss command, either in the same statement as the line command, or with its own separate data label.

5.2 Examples of formatting

To cover all the possible options for formatting both the axis and line styles we shall look at a series of more complex graphs. The first example is somewhat artificial, in that both graphs use the same (made up) data set, but it does serve to illustrate the degree of control it is possible to take over the final appearnce of a graph. This flexibility is clearly an advantage, but can be time consuming and sometimes unneccesary. In most cases GLE will do a reasonable job of producing a graph using the default settings.


!format.gle - Demonstrates the various format options for the axis of a graph
size 18 27 
amove 1.3 14.5

begin graph
        size 16 12
        nobox                                   !Formats the axis
        xaxis min 0 max 20 dticks 4 dsubticks 1
        xplaces 4 8 12 16 20
        xnames "Sep 13" "Sep 23" "Oct 3" "Oct 13" "Oct 23"
        xticks length 0.2
        yticks length 0.2
        yaxis min 0 max 75 dticks 10 dsubticks 5 nofirst
        ytitle "Bud burst (%)"
        xtitle ""
        data test.dat
        

                !Draws the various data points
        d1 lstyle 1 marker wcircle msize 0.3 key "Shelter row"
        d2 lstyle 1 marker wsquare msize 0.3 key "Shelter row + H"
        d3 lstyle 2 marker wcircle msize 0.3 key "Middle row"
        d4 lstyle 2 marker wsquare msize 0.3 key "Middle row + H"
        
        key pos tl hei 0.4              !Draws a key
        

end graph

rmove 12 9                      !Labels graph (a)
set font rm hei 0.5
text (a)

amove 1.3 4
                                !Draws the lower graph
begin graph
        size 16 12
        nobox                                   !Formats the axis
        xaxis min 0 max 20 dticks 4 dsubticks 1
        xplaces 4 8 12 16 20
        xnames "Nov 10" "Nov 15" "Nov 20" "Nov 25" "Nov 30"
        xticks length 0.2
        yticks length 0.2
        yaxis min 0 max 110 dticks 10 dsubticks 5
        ytitle "Flowers per cane at full bloom" 
        xtitle ""
        data test.dat
        d1 lstyle 1 marker circle msize 0.3     !Draws the various data points
        d2 lstyle 1 marker square msize 0.3
        d3 lstyle 2 marker circle msize 0.3
        d4 lstyle 2 marker square msize 0.3
end graph

rmove 12 9                              !Labels graph (b)
text (b)

set hei 0.4                             !Adds an explanation of the data
amove 1.3 3
begin text width 16
Figure 5: Influence of Hicane on the duration and timing of (a) bud burst and (b) 
flowering of kiwifruit. (Note: this data has been made up)
end text

Adding a simple key

There is a dedicated command module, similar to the graph module we are working with, that allow for the construction of keys. If, however, we only want to add a simple key then we can add a command from within the graph module. The key command has less formatting options available to it, but is simpler than the full key module. We indicate that we wish a dataset to be included in the key by placing the key qualifier in the data line followed by the title we wish the dataset to have,

d2 marker dot key "Observed values"
d3 line key "Predicted values" 
We can change the position and format of the key by adding a subsequent key command,
key pos tl hei 0.4
This will draw the key in the top-left hand corner with text of height 0.4cm. We can remove the box that GLE adds by default with the qualifier nobox, for example,
key pos br nobox

Formatting the axis

A graph in GLE consists of a number of separate parts, four axes, their corresponding labels, and various titles. Each part has various formatting options that can be specified individually, or as a group. In this text we have tried to use all the possible formatting options for a given command. It is normally unnecessary to be so specific, as GLE will make reasonably sensible choices for most of the formatting.

The most important compontents, from the point of formatting, are the axes. These are referred to by the labels xaxis, yaxis, x2axis, y2axis, where the last pair refer to the upper and right hand axis. We can specify the formatting of these axis with the command,

xaxis color red lwidth 0.2 font texcmss hei 0.5
The syntax for the qualifiers is the same as for line styles and text outside the graph module. The other three axis can be specified in the same way,
y2axis color blue 
By default all four axis will be drawn with labels only on the left and bottom. Changing the format of the xaxis will also change the formatting of the x2axis.
x2axis color blue
xaxis color red
Will still draw both the xaxis and the x2axis in red, though the y-axis will be unaffected. To produce a blue x2axis we would need to place the x2axis command after the xaxis one.

The axis commands control the overall format of the graph; they apply to the labeling, the title, and the appearance of the axis graduations which we call ‘ticks’ and ‘sub-ticks’. Specifying a format option with the xaxis command sets it as the default for all following commands. So if we write,

xaxis color green
xtitle "Voltage"
The title ‘Voltage’ will appear in green as opposed to black.

We may turn off the x2axis and the y2axis with the commands,

x2axis off
y2axis off
In this way the xaxis and yaxis may also, if we wish, be removed. For the sake of completeness we mention that the command xaxis on will turn the x-axis back on again, though this can also be accomplished by not turning it off in the first place.

We may change the format options of the axis lines themselves using the command,

xside color blue lwidth 0.2 
There are similar commands for the other three axis. Using this command the ticks, subticks, and the axes themselves will be changed, but the labels and title will remain intact. Again we may turn off the x-axis' lines, or any other lines, with the command,
xside off
And back on again with xside on.

The ticks and subticks, refering to the large and small graduations on the axes, can also be formatted. There are several commands that relate both to their positioning and to their appearence.

xticks lstyle 2 lwidth 0.01 length 0.2 color red
This will apply to the ticks and subticks on the top and bottom axes. We can specify the y axis as well.
y2subticks lstyle 2 lwidth 0.1 length 0.1 color black
This will apply only to the subticks on the right hand y-axis. Again the order of commands is important, as we may end up obliterating previous formatting by inadvertantly placing a xaxis command at the end of a graph module.

Ticks and subticks are draw on the inside of the graph, if we wish to move them to the outside then we simply specify a negative length.

x2subticks length -0.2
This will draw the top x-axis subticks on the outside of the axis.

The command xlabels formats both the data labels and the title of the x-axis, and the top x-axis. The converse is not true, x2labels formats only the top x-axis and leaves the bottom x-axis untouched.

xlabels color blue hei 0.3 font tt
x2labels hei 0.1
x2labels on
Where the x2labels on command tells GLE to add the x2axis labels which will, by default, not appear even if we attempt to format them. Again the x2labels format commmand must appear after the xlabels command if it is to have any effect. The xlabels on command may appear anywhere within the graph module, and we may include it in the format line: x2labels hei 0.1 on.

The ticks and subticks are allocated evenly accross the axes, but we can gain more control over the allocation using an xaxis command. We write,

xaxis dticks 3 dsubticks 1.5
Which will produce ticks every 3cm, with subticks every 1.5cm. Alternatively we can write,
xaxis nticks 5 nsubticks 20
Now the spacing of the ticks is changed such that there are 5 ticks and 20 subticks along the axis. We can combine the two commands by specifying a set number of ticks and a set distance between the subticks, but if we specify both a nticks command and a dticks command the set distance command will take precedence. Again the xaxis command will also set the format for the top x-axis.

When a graph is drawn the labels on the axes are assigned with each tick having an associated label, which should produce a graph with an easily readable scale. If for some reason it does not, or we wish to relabel the graph to draw attention to a particular region, then we may manually add the axes labels with the command xplaces. If, for example, we have a data set that is asymptotic to x=1 then, assuming we have sufficient resolution, we may write

xplaces 0 0.25 0.5 0.75 0.9 0.95 0.99
This will label the x-axis with the numbers 0, 0.25, 0.5, ..., 0.99, each number having a tick associated with it. These ticks will remain in position even if we set a tick spacing.
xplaces 0 0.25 0.5 0.75 0.9 0.95 0.99
xaxis nticks 6
The xaxis nticks command will not change the position of the labels on the bottom x-axis, we must remove the xplaces command to do that, the top x-axis will have 6 ticks along it.

If we are not satisfied with the default labels supplied by GLE then we can substitute them for ones of our own choosing.

xplaces 1 2 4 6 7
xnames "Monday" "Tuesday" "Thursday"
xnames "Saturday" "Sunday"
The xnames commands allows us to supply any text variable to replace the labels used in the text. It also, as in the example above, allows us to specify labeling with a non-uniform spacing. The xplaces command is not required, without it GLE will apply the labels to the default placings. If there is insufficient space on a single line for all the labels then separate xnames commands can be used for each individual label.

Fine tuning

There are a few remaining commmands that are useful for solving particular problems with the final graph.

The commands xaxis nofirst and xaxis nolast will remove the first or last labels on the x-axis, with similar commands for the y-axis. If the labels are overlapping then the use of this command can be easier than reformatting the entire axis.

xaxis shift 0.2 will shift the labels on the xaxis by 0.2cm from the left to the right. This can be used when the labels refer to data between the labels rather than above them. Again an analogous command exists for the y-axis.

If we wish to add a grid to our graph then we may use a dedicated command xaxis grid to produce one. The command makes the x and y ticks as long and as tall as the graph itself. For example,

xticks lstyle 2
yticks lstyle 2
xaxis grid
yaxis grid
will produce a dotted grid underneath the data.

By default the text on the second y-axis will be written vertically upwards. If we wish to include the graph within another application then to stop text appearing upside down we may need to reverse this default setting. To do this we use the command y2title "Axis title" rotate, which will display the text written vertically downwards instead. The command is specific to the second y-axis.

Logarithmic scales

We can produce graphs with logarithmic scales on the x-axis, or the y-axis, or both. Logaritmic scales no longer have a constant spacing between the labels, so we should use the xaxis nticks command for changing the spacing between the ticks. There are also some slight differences in the use of smoothing routines with logarithmic scales.


!log.gle - Demonstration of the use of logarithmic scales
size 14 12
amove 0 0

begin graph
nobox
size 14 12
data freq.dat                   !Reads data from freq.dat

yaxis log min 0.01 max 1 grid   !Formats the axis and adds a grid
xaxis min 0 max 0.0006 grid

xlabels hei 0.2
ylabels hei 0.2
xplaces 0.0001 0.0002 0.0003 0.0004 0.0005 0.0006 
xnames "1" "2" "3" "4" "5" "6"  !Labels the axis

yticks lstyle 2                 !Changes the grid to a dotted line
ysubticks lstyle 2
xticks lstyle 2

xtitle "Frequency (1\times 10^{4} Hz)" hei 0.3
ytitle "Voltage (V)" hei 0.3

d1 marker circle msize 0.2      !Draws the data
end graph

amove 7 0.5                     !Adds a title
set just CC hei 0.3
text Figure 4b: Measured frequency dependence responce of target circuit

As we can see from above, the command xaxis log either on its own or with other x-axis commands will tell GLE to draw a logaritmic scale on the x-axis. A similar command, yaxis log, will produce a logarithmic scale on the y-axis.

Filling between the lines

Another possible formatting option is the ability to fill the areas between datasets, or between a dataset and an axis, with a solid block of colour.


!fill.gle - Demonstrates the options for filling between lines
size 16 8
amove 0 0
begin graph
      data fill.dat d1=c1,c2 d2=c1,c1
      fill x1,d2 color grey20
      fill d1,d2 color grey80 xmin 1 xmax 4
      fill y2,d1 color black ymin 20 ymax 25
      fill d1 color green
      end graph

The fill command instructs GLE to fill the lines immediately following the command, these can be either a dataset or one of the axes referred to with the labels, x1, x2, y1, and y2.
fill x2,d2 color green
This will fill the area between the dataset d1 and the upper x-axis with a green colour. The fill style is clipped according to the line joining the points. At the moment this means that both the line and the filling appear as a jagged polygon; in later sections we will fit a smoothed line to the dataset, and in this case, the filling will also be smoothed. We can also fill between a dataset and the y-axis, though in this case, the filling will be clipped at the edge of the data and not necessarily at either y-axis. We can also specify a maximum and minimum range of values to fill between using the xmin, xmax, ymin, and ymax commands. It is normally a good idea to specify the limits, particularly when filling from the y-axis, as GLE may have trouble interpreting some of the fill commands if the function is undefined at any point.

A final command allows us to fill between a data set itself,

fill d3 color blue xmin 4 xmax 40
In this case the maximum and minimum points are joined by a straight line to form one or more closed polygons. The fill colour is then applied to the inside of these shapes.

5.3 Plotting graphs from user defined formulae

Often it is necessary to reproduce the expected curve from a theory, or to demonstrate the behaviour of a function. For this GLE provides the ability to generate graphs from a given function as well as from sets of data.


!gamma.gle
size 12 9

set lwidth 0.05                 !Formats the text and line width
set font texcmss

begin graph
        size 12 9
        nobox                   !Defines data set from the value of gamma
        let d1 = 1/(sqrt(1-x*x)) from 0.001 to 0.999 step 0.01
        d1 line                                 
        let d2 = 1.0 from 0 to 10 step 2        !Produces a comparison data set
        d2 line lstyle 2
        xaxis min 0.0 max 1.0 hei 0.8           !Formats the axis
        yaxis min 0.0 max 7.0 hei 0.8
        xplaces 0 0.2 0.4 0.6 0.8 1.0
        yplaces 0 1 2 5
        xlabels hei 0.2
        ylabels hei 0.2 
        xtitle "\beta=v/c" hei 0.5 dist 0.3
        ytitle "\gamma = (1-\beta^2)^{-1/2}" hei 0.5 dist 0.3
        xticks length 0.2
        xsubticks off
        yticks length 0.2
        x2ticks off
        y2ticks off

end graph

We can define data sets from a mathematical function using the let command. We must also set the sample rate and range as we would do if we were defining a programming loop. GLE reads the data into the set at the rate and according to the same rules set out in the section on conditional logic. Any function that can be used in a programming loop can also generate data for a graph.

The graph itself is made up of a number of straight line segments, which is why the sampling rate must be set so high. In the next section we will look at ways of drawing smooth continuous curves through a section of points, though even this will require a high sample rate if we are to have an accurate graph.

We can also create data sets that are functions of other data sets. For example, if we wish to take the average of two data sets d1 and d2,

data experiment.dat d1 d2 
let d3 = (d1+d2)/2
d1 line lstyle 4
d2 line lstyle 4
d3 line lstyle 1
Which will draw both data sets d1 and d2, and their average value d3.

Datasets can, and often are, created solely for the purpose of calculation and are never plotted on their own. A combination of data sets should be defined over the same range if they are to be successfully combined.


!Square.gle - Example of combining datasets

size 18 20
pi = torad(180)
amove 0 0

begin graph 

yaxis max 1.1 min -1.1 
xaxis max 15 min 0

let d1 = sin(x) from 0 to 15 step 0.1           !The fundamental sine wave
let d2 = sgn(d1)                                !The square wave
let d3 = sin(3*x) from 0 to 15 step 0.1         !Various harmonics over
let d4 = sin(5*x) from 0 to 15 step 0.1         !the fundamental
let d5 = sin(7*x) from 0 to 15 step 0.1
let d6 = sin(9*x) from 0 to 15 step 0.1

let d10 = d1+(1/3)*d3                           !We take linear combinations
let d11 = d10+(1/5)*d4                          !of the various frequencies
let d12 = d11+(1/7)*d5
let d13 = d12+(1/9)*d6

d1 line color grey10                            !These could also be plotted
d2 line lstyle 2                                !in different colors or line
d10 line color grey20                           !styles to make the difference
d11 line color grey40                           !clearer. A key may also help
d12 line color grey60
d13 line color grey80

xplaces 0 pi 2*pi 3*pi 4*pi                     !Labels the xaxis
xnames "0" "\pi" "2\pi" "3\pi" "4\pi"
xsubticks off

end graph

set just cc hei 0.3                             !Adds a title
amove 9 1
text Figure 7b: Synthesis of a square wave from harmonic components

Notice that we use the sgn() function to return a 1 if d1 is positive and a -1 if d1 is negative. We cannot define the function piecewise with the commands,

let d2 = 1 from 0 to pi step 0.001
let d2 = -1 from pi to 2*pi step 0.001
let d2 = 1 from 2*pi to 3*pi step 0.001
let d2 = -1 from 3*pi tp 4*pi step 0.001

Each use of the let command will wipe any data previously stored in the dataset, the above commands would produce a dataset that was defined to be -1 from 3{[pi ]} to 4{[pi ]} and undefined, that is zero, elsewhere. We could, of course, have defined four datasets each with part of the function and then added them together with the let command; though, in this case, we took a short cut and used the sgn() function.

5.4 Bar charts

The bar graph command is often complex, representing the number of possible options that we may choose to plot. It exists as a subset of the graph module so that we can plot both bar and line data on the same graph.

Combining lines and bars


!decay.gle - Demonstration of the bar command with data from radioactive decay
 
size 18 18
pi = 3.1415
mu = 59.51              !These are the parameters of the gaussian approximation
sigma = mu^0.5
N = 100                 !The number of timed intervals

amove 0 0
begin graph
nobox
                        !Sets our Gaussian into both "continuous" and 
                        !discrete forms
let d1 = ((N/3)/(((2*pi)^(0.5))))*exp(-((x-mu)^2)/(2*(sigma^2))) from 40 to 80 step 0.1
let d2 = ((N/3)/(((2*pi)^(0.5))))*exp(-((x-mu)^2)/(2*(sigma^2))) from 41 to 90 step 3

data decay.dat d3=c1,c2         !Data taken from the experiment

d1 line                         !Plots the approxmation and the data
d2 marker circle
bar d3 width 3 fill yellow

key hei 0.3 pos tr nobox        !Adds a key
d1 key "Gaussian approximation with N=100"

                                !Formats the axis
xplaces 41 44 47 50 53 56 59 62 65 68 71 74 77 
xaxis min 39 max 80 hei 0.3 dsubticks 1
yaxis min 0 max 18 hei 0.3 
x2axis off
y2axis off
                                
                                !Adds the title
xtitle "Number of detected events in 5 second interval"
ytitle "Frequency"
end graph

We have met much of the above before, the important command to notice is the bar command. The command instructs GLE to draw a set of bars of width 3 units, with the position and height determined by the values in dataset d3. The position is taken to be the midpoint of the graph so our data set must refer to the midpoint values. Unfortunately it is not possible to use a second data set for individual widths, so we must either settle for fixed widths or draw the chart as a combination of individual datasets, one for each different width.

The format commands that apply to the bar charts are fairly straightforward,

bar d1 width 2 fill blue color green
This will draw bars of width 2 with a green outline and filled with blue. In the following sections we shall see that there are other formatting commands that can produce more interesting effects.

Comparing data - grouped and 3D bar charts

We often need to present grouped data on a chart, to do this we can either display the bars side by side or stacked on top of each other. We look at an example which shows the various option available, including the ability to display a 3 dimensional representation of the data.


!bean.gle - Demonstrates the various formatting options for a bar chart
size 20 20

amove 0 10

begin graph             
size 10 10
data bean.dat
                                !The first graph draws a set of bars side 
                                !by side
bar d1,d2,d3 fill green,red,yellow

d4 line                         !These help with the generation of the key   
d5 line 
d6 line 

xaxis hei 0.2 
yaxis hei 0.2 min 0 max 30
xtitle "No. weeks growth"
ytitle "Height (cm)"

key pos tl hei 0.2              !The key uses the blank data sets - we can 
                                !create more advanced keys using the key module
d4 key "Natural Growth" color green
d5 key "Grow-fast Fertilizer" color red 
d6 key "Super-grow Fertiliser" color yellow
end graph


                        !The three following graphs have the same format and
                        !data as the previous - the only difference is the 
                        !way the bars are plotted
amove 10 10
begin graph

size 10 10
data bean.dat
                        !This stacks one of the data sets ontop of the 
                        !other two
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 
bar d3 from d1 fill yellow width 0.8
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 
                        
d4 line   
d5 line 
d6 line 

xaxis hei 0.2 
yaxis hei 0.2 min 0 max 30

xtitle "No. weeks growth"
ytitle "Height (cm)"

key pos tl hei 0.2
d4 key "Natural Growth" color green
d5 key "Grow-fast Fertilizer" color red 
d6 key "Super-grow Fertiliser" color yellow
end graph

amove 0 0

begin graph
size 10 10
data bean.dat

                        !This changes the bars into 3D blocks
bar d1,d2,d3 fill green,red,yellow  width 0.2,0.2,0.2 dist 0.3 3d 0.5 0.3  

d4 line   
d5 line 
d6 line 

xaxis hei 0.2 
yaxis hei 0.2 min 0 max 30

xtitle "No. weeks growth"
ytitle "Height (cm)"

key pos tl hei 0.2
d4 key "Natural Growth" color green
d5 key "Grow-fast Fertilizer" color red 
d6 key "Super-grow Fertiliser" color yellow
end graph

amove 10 0
begin graph
size 10 10
data bean.dat

                        !We can also stack a 3D bar graph
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 3d 0.5 0.3 side green,red 
bar d3 from d1 fill yellow width 0.8 3d 0.5 0.3 side yellow top yellow
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 3d 0.5 0.3 side green,red top green,red

d4 line   
d5 line 
d6 line 

xaxis hei 0.2 
yaxis hei 0.2 min 0 max 30

xtitle "No. weeks growth"
ytitle "Height (cm)"

key pos tl hei 0.2
d4 key "Natural Growth" color green
d5 key "Grow-fast Fertilizer" color red 
d6 key "Super-grow Fertiliser" color yellow
end graph

To group bars together on the same line we list the appropriate datasets under the same bar command.

bar d1,d2 fill green,red width 1,2 color black,red
The datasets are separated by a single comma (without space). Each option that may be specified for a single bar may be specified for grouped bars, but we separate the options with a comma and in the same order as the datasets are listed. The example above fills the first dataset, d1, in green with a black outline and a width of 1 unit on the x-axis.

We can also stack single bars on top of each other, and if we wish, stack grouped bars on top of each other too.

bar d1,d2
bar d3,d4 from d1,d2
bar d5,d6 from d3,d4
This will draw the datasets d1 and d2 next to each other, then d3 and d4 on top of these two, and finally, d5 and d6 at the very top. The bars are plotted sequentially so GLE will overwrite anything that has already been plotted. In the program bean.gle we wrote,
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 
bar d3 from d1 fill yellow width 0.8
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4 
This will plot the datasets d1 and d2, then partially obscure d2 as d3 is drawn (if you have a slow enough postscript viewer then you can watch this happening). We need to redraw the first two data sets if we keep the commands in this order. It is not however necessary to draw the two data sets first; we can remove the first bar command to leave,
bar d3 from d1 fill yellow width 0.8
bar d1,d2 fill green,red width 0.4,0.4 dist 0.4    
This will accomplish the same thing, although in a slightly less intuitive order.

3D bar charts are subsection of the bar command; to use these we tell GLE that we require a 3D plot by adding the 3D command on the same line as the bar command.

bar d1 3d 0.5 0.3
The two numbers following the 3D command define the x and y vectors used to draw the receding lines, given in terms of a fraction of the width of one bar. The pair of vectors control how ‘3D’ the graph appears: small fractions give a very subtle effect, larger ones can cause the bars to overlap.

Charts with 3 dimensional bars can be stacked, grouped, and formatted in exactly the same way as the ordinary 2 dimensional variety. Some of these effects are best used with caution since sometimes the results can be confusing, both for the programmer and for the final audience. In addition to these, there are several formatting options that apply specifically to the 3 dimensional case. A typical command may have the form,

bar d2,d3 3d 0.2 0.2 side green,blue top green,blue fill green,blue
The side command gives the colour to be used for the sides of the bars, if there are more than one then we list the various colours separated by a comma as in the 2 dimensional case. Similarly the top command gives the colours to be used for the tops of the bars. We can replace the top command with the notop command which leaves the top of the bar open for use with stacked bar 3D bar charts.

5.5 Scientific graphs

GLE is ideal for producing technical graphs for inclusion in reports and papers, with this in mind we look more closely at some of the graph commands that are useful to scientists.

Treatment of errors

GLE allows for the errors in a set of data-points to be displayed with error bars that are taken from a second dataset, or from a certain fractional or absolute error in each data point.


!error.gle - Example of the use of error bars
size 10 10

begin graph
data error.dat
let d2 = x^2 from 0 to 50       !Two different possible models
let d3 = 2*x+1 from 0 to 5
d3 lstyle 4
d2 line smooth
d3 line smooth 

xaxis min 0 max 5
yaxis min 0 max 20
xtitle "Voltage (V)"
ytitle "Resistance (\Omega)"    !Notice the difference between Omega and omega

                                !Adds the markers and error bars
d1 marker circle err 10% errwidth 0.2  herrleft 0.4 herrright 10%

end graph

There are two separate error bars, horizontal and vertical, which can can be formatted individually and independently. We shall look mainly at the command options for the vertical bars, but the horizontal bars can be formatted by very similar commands.

The simplest possible case would be if we had an absolute error in the y coordinate for each data point. We assume, to start with, that the error is symmetrical such that the mean value is at the centre of the two error bars.

d1 err 10%
This will produce an error bar that extends above the data point for 10% of the absolute y value, and a similar distance below. The command herr 10% will do the same for the horizontal bar, except the error will be 10% of the absolute x value.

If we do not have a symmetric distribution of errors then we may specify individual errors for the up and down error bars.

d1 errup 10% errdown 5%
This will take 10% of the y value up, but only 5% down. For the horizontal bar we use the commands herrleft 5% and herrright 10%.

We can also specify absolute errors using the same set of commands,

d1 err 0.2
d1 errup 0.2 errdown 0.2
These are commands that accomplish the same thing, the error bars extend for 0.2 y units above and below the actual data point.

If we wish to we can control the size of the lines that terminate the error bars. The commands errwidth 0.5 and herrwidth 0.5 will set both the horizontal and vertical lines to 0.5 in their respective units.

Errors are an integal part of many technical graphs, and there are occasions when we need more control over the displayed errors. We may, for example, wish to use a separate program to calculate the error on each individual data point. If this is the case then we can use a second dataset to store the error values and produce error bars that are unique to each point.


!Planck.gle - Demonstration of errors defined by separate dataset
size 12 12

amove 0 0
begin graph

yaxis min 6.623 max 6.6265 hei 0.2
xaxis hei 0.2

data planck.dat d1=c1,c2 d2=c1,c3       !Reads the data and errors into 
                                        !two different data sets

d1 line smooth err d2                   !Uses the second data set to 
                                        !Define the error on the first

ytitle "Experimental value of Plancks constant (\times 10^{-34} J\cdot s)"
xplaces 1951 1955 1963 1973 1988
xsubticks off
x2axis off
y2axis off

key pos br nobox hei 0.2                !We use undefined datasets to add 
d3 key "1951 - Bearden and Watts"       !a key - Notice that the order is 
d4 key "1955 - Cohen et al."            !the same as the number of the 
d5 key "1963 - Condon"                  !dataset, not the order on the page
d6 key "1973 - Cohen and Taylor"
d7 key "1988 - Cohen and Taylor"

end graph

amove 3 0.75                            !Adds a title
set hei 0.3 font rmb  
text Fig 4: 
amove xend() yend()
set font rm
text \glass How constant is constant? 

This is the separate data file, the figure given in the third column is the absoulte error in each measurement. For example, 6.2363 ± 0.00016 Js.


1951  6.62363    0.00016
1955  6.62517    0.00023
1962  6.62560    0.00017
1973  6.626176   0.000036
1988  6.6260755  0.0000040

All the error commands can be used with a separate data set, except instead of specifying an absolute or fractional error in every point we can now specify the individual errors.

d1 errup d2 errdown d3 herr 10%
This will give a 10% error in the x coordinate and an error in the y coordinate dictated by the datasets d2 and d3.

Curve fitting

GLE contains two separate routines that allow for a discrete set of data to be connected by a smooth curve. In the simplest possible case GLE will fit a third degree polynominal piecewise to a set of data points. To do this we add the smooth command.

d3 line smooth

The command is useful if we either do not know the simple form of the equations that produced the data points, or we know that a simple form does not exist. By using a high sampling rate and the smooth command we can approximate most functions to an arbitarily high degree. GLE also provides a number of fitting routines for commonly used functions. To use the routines we must define another dataset which contains the approximation data; we can then plot the fitted dataset just as we would with any other set of points.

let d4 = logefit d3 from 0 to 100
This will create data in d4 that best represents a logarithmic (base e) fit of the data in d3. There are three other fitting routines available, log10fit uses a base 10 logarithm, linfit a straight line, and powxfit a power law.

The range of the data can either be defined explicitly as above, or we can choose the same range as the original dataset with one of the following commands,

let d4 = linfit d3 limit_data
let d4 = linfit d3 limit_data_x
let d4 = linfit d3 limit_data_y
limit_data_x gives the fitted data, d4, the same range as the x values in d3, limit_data_y gives the fitted data the range of the y values in d3. limit_data will give d4 a range that can extend from the minimum x or y value to the maximum x or y value, whichever option gives the greatest range.

Dealing with very large data sets

Although the steady evolution of computer hardware has rendered it less and less important GLE provides a number of commands for dealing with very large data sets where the physical memory of the computer becomes an issue.


!dna.gle - Demonstrates the use of the bigfile command for use with large datasets
size 10 10

begin graph             !dna.dat is a list of the positions of palendromic 
                        !sequences in a viruses DNA
d1 bigfile "dna.dat,1,2" marker dot msize 0.2

                        !The position is represented by two columns, one is
                        !the position single units, the other in tens of 
                        !thosands
xaxis min 0 max 10000 grid hei 0.2
yaxis min 0 max 22 grid dticks 1 hei 0.2
yticks color grey20
xticks color grey20
ysubticks off
xnames "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "10"
xtitle "Position (\times 10^{3})" 
ytitle "Position (\times 10^{5})" 
end graph

amove 5 0.5
set just cc hei 0.3
text Distribution of palendromic sequences in viral DNA

The data file has the form,
(...)
5151 19
5221 19
5262 19
5835 19
6992 19
7022 19
7191 19
8195 19
8709 19
1023 20
1056 20
2198 20
4548 20
(...)

The first column represents the position in single units the second in tens of thousands so that the first sequence is 195151.

The dataset in the example is only a few thousand lines long, this may have caused trouble a few years ago but modern PCs are perfectly capable of dealing with datasets far in excess of this. Nevertheless it is occasionally necessary to deal with extremely large data sets. If the DNA above was taken from a human and not a virus we would have wanted to reduce the pressure on computing power as much as possible. The bigfile command used above saves on memory by plotting the data point by point straight from the file instead of being reading the data into memory and then plotting.

d1 bigfile "data.dat,2,3" autoscale marker circle line
This will plot columns 2 and 3 from the file data.dat with circular markers and joined with straight lines. The autoscale command pre-reads the data and scales the axes, before re-reading it and plotting. This can be slow, but is useful if we do not know the exact extent of the data. Without the command we must specify the minimum and maximum values of the x and y axes.

Virtually all of the graph module commands will work with the bigfile option. It is, however, impossible to draw bar charts using the command, or to use the let command to create new datasets.

5.6 The key module

Although it is perfectly possible to draw a key from within the graph module, GLE provides a dedicated set of commands that allow the user to draw up a key of points for a graph.

A basic key

Each key follows the graph module to which it refers; we begin the module with a begin key command, and end it with an end key command. In between these two lines a special command set applies.


!etalon.gle - Transmission function of the Fabry-Perot Etalon to demonstrate
                !the use of the key module
size 18 18
pi = 3.1415
f1 = 2          !These define the finesse of each line
f2 = 5
f3 = 10
f4 = 20
f5 = 50
 
amove 0 1
begin graph
nobox
size 18 18

                !This is the transmission function for the etalon
let d1 = 1/(1+(4*(f1)/pi)*((sin(x))^2)) from -2*pi to 2*pi step 0.001
let d2 = 1/(1+(4*(f2)/pi)*((sin(x))^2)) from -2*pi to 2*pi step 0.001
let d3 = 1/(1+(4*(f3)/pi)*((sin(x))^2)) from -2*pi to 2*pi step 0.001
let d4 = 1/(1+(4*(f4)/pi)*((sin(x))^2)) from -2*pi to 2*pi step 0.001
let d5 = 1/(1+(4*(f5)/pi)*((sin(x))^2)) from -2*pi to 2*pi step 0.001

                !We use a logarithmic scale to increase the contrast between
                !the different values of finesse
yaxis min 0.01 max 1.1 log grid
xaxis min -1 max 4              

xsubticks off
yticks color grey10
ysubticks color grey10
xaxis hei 0.5
yaxis hei 0.5
xplaces 0 pi
xnames "\phi \: = 0" "\phi \: = \pi"
xtitle "Phase shift"
ytitle "Transmission fraction"


d1 line lstyle 4        !These commands draw the various lines
d2 line lstyle 2
d3 line lstyle 3
d4 line lstyle 5
d5 line lstyle 1
end graph

set just CC hei 0.5     !Adds a title
amove 9 1
text Transmission fraction of the Fabry-Perot Etalon

amove 11 4              !We move to where we want to draw the key

begin key               !The key module
hei 0.4
offset 0.1 0.1
text "Finesse = 2" lstyle 4
text "Finesse = 5" lstyle 2
text "Finesse = 10" lstyle 3
text "Finesse = 20" lstyle 5
text "Finesse = 50" lstyle 1
end key

The key module is an extension of the key command we have used previously. Within the module we may specify any formatting options that we used with the single line command, plus a few extra ones that we could not.

begin graph
...
end graph
begin key
hei 0.5
positon tr
text "This is the first title" marker dot msize 0.2 mscale 0.5 color red fill blue lstyle 2 
end key

This will produce a key in the top-right hand corner of the previous graph. The text command uses the quoted text string as first line of the key, the qualifiers following this title represent the format of the line. If we add a marker command then it will be displayed next to the title, with a size defined by the msize command. The mscale command is similar except the size is taken to be a fraction (0.5 in the example above) of the default size. If we define a line style with the text command then a line in the appropriate style will also appear next to the title. The fill command adds a coloured box next to the title. The colour of the text, the line, and the marker are all set by the color command.

The key syntax

The syntax of the key module is a little different to the rest of the GLE commands we have dealt with. We shall classify commands into two types: those which relate to global features of the key module, and those which relate to a specific dataset. The global commands in the key module are,

offset, nobox, hei, pos

Within the key module these can appear anywhere except on the start of a line that defines a new dataset.

begin key
        offset 2 3 hei 2
        text "abc" nobox
        nobox text "abc" !This line is not valid
end key

The single dataset commands are,

text, marker, msize, mscale, color, fill, lstyle, line, lwidth

These must appear together on a single line corresponding to a single dataset, within this line the order is not important.

begin key
        marker circle text "abc" lstyle 2
        lstyle 2 marker square
end key
The (entirely arbitrary) convention is to put the global commands at the start of the module, and follow them by a single line for each line in the key.

5.7 Integrating graphs and diagrams

A single graph may form part of a larger diagram, even if that diagram contains only a few additional notes or titles. To make the transition between lines drawn inside the graph module and those drawn outside as seamless as possible we may use two commands, xg() and yg(), that refer to a point on a graph while we are outside the main graph module.


!lorentzian.gle - Demonstrates the xg() and yg() commands
size 10 10
E = 100                 !This is the energy, E, and width, W, of the state
W = 20

begin graph

!These two datasets produce the Lorentzian profile
let d1 = (x-E)/(W/2) from 0 to 200 step 2    
let d2 = 1/(1+((d1)^2)) 

                                                !This formats the axis
yaxis min 0 max 1.2 hei 0.2
yaxis off       !Remove this line to add the y-axis
xaxis min 0 max 200 hei 0.2
yplaces 0 0.5 1
xtitle "Energy (eV)"
title "The energy spectrum of an isolated state with finite lifetime" hei 0.2 dist -8

d2 line smooth          !Draws the profile and fills in the width at half maximum
fill x1,d2 xmin 90 xmax 110

end graph

set hei 0.5                             !Labels the FWHM
amove xg(90) yg(0.5)
rline -0.4 0 arrow start
amove xg(110) yg(0.5)
rline 0.4 0 arrow start
set hei 0.2

amove xg(125) yg(0.5) 
begin text width xg(190)-xg(130)
Full width at half maximum, \Delta E 
end text
                                        !Labels the mean energy of the state
set just center lstyle 2
amove xg(100) yg(0)
aline xg(100) yg(1.05)
text Mean energy, E_{0}

The commands xg(a) and yg(b) return the absolute x and y coordinates of a point (a,b) measured in the x and y units of the most recently drawn graph. We may use these two functions to label points of interest on a graph.

begin graph
  (...)
end graph
amove xg(80.6) yg(1.2)
rline 0.5 0.25
text \glass \: Production of W^{+}
This will move to the point (80.2,1.2) on the graph, where the coordinates are in the same units units the x- and y-axis, and add a label. We may also join two points on a graph using these commands, or use them to format text. One of the uses may be to add complex mathematical curves, particularly those in cylindrical coordinates, to a set of axes.


Next Previous Contents