Graph Plotting
Introduction
Graph plotting in Magics is the plotting of
line charts (curves), bar charts, area charts and box plots within a
set of axes.
To plot a graph, it is necessary to pass information to
Magics that
describes the graph required. This information is passed to
Magics via
one-dimensional arrays, holding the X and Y values of the graph.
The X/Y values refer to the X and Y axes which may be set up by using
Magics AXIS facilities or may be defined
automatically from the input graph data.
There are facilities in graph plotting that allow the user to
control the line style, colour and thickness of each graph and,
if required, a legend describing the graph may be plotted.
A summary of GRAPH parameters and examples of graph plotting can be found toards the end of this chapter.
Magics++
Magics++ requires that a user program
specifies Cartesian projection when plotting graphs:
CALL PSETC ('SUBPAGE_MAP_PROJECTION', 'CARTESIAN')
Please do this at the start of your program. This requirement is new to Magics++.
Action Routine PGRAPH
Plotting of line charts (curves), bar charts, and area charts is
achieved in Magics by calling action routine
PGRAPH which, like all Magics
action routines, has no arguments.
PGRAPH will only draw one graph each time it is called.
Parameters associated with graph plotting may be set before
PGRAPH is called. PGRAPH will
take into account only those parameters which have been set before it is called.
All other graph parameters will be assigned their default values,
if they exist.
Plotting of box plots is achived by calling a separate action routine,
PBOXPLOT - see
.
Graph Plotting Parameters
Parameters associated with graph plotting start with
the prefix GRAPH,
e.g. GRAPH_LINE_STYLE.
These parameters describe the input data and the type of graph
plotting required, i.e. curve, bar chart or area chart.
The parameters
describe the attributes of the graphs, e.g. line style, colour and
thickness of plotted output. Thus, the user has full control over
all aspects of graph plotting.
A full list of GRAPH parameters appears in
Mapping of X/Y Values
The X and Y values passed by the input arrays are relative to the values of the X and Y
axes respectively. The X/Y axis system may be defined by setting the parameters
AXIS_MIN_VALUE and AXIS_MAX_VALUE
to the required values or may be defined automatically. To define the axes automatically,
the parameter GRAPH_AXIS_CONTROL should be set to
AUTOMATIC, the default being OFF. If set to
AUTOMATIC, Magics will calculate
the minimum and maximum values of the X/Y axes from the incoming GRAPH data.
When the axis system is not automatic, incoming GRAPH data should be within
the range of AXIS_MIN_VALUE and AXIS_MAX_VALUE.
Any part of the graph falling outside the current axis limits is not plotted.
Setting GRAPH_POSITION_MODE to GEOGRAPHIC or
PAPER allows for the facility of drawing curves on maps.
It is not necessary to set up an axis system as Magics will
set up a system that matches the current map requirements. If the mode is
GEOGRAPHIC, the incoming X/Y curve values should be the positions in
latitude and longitude of the curve points. If set to PAPER, the points
should be defined as offsets in centimetres from the bottom left hand corner of the
subpage. This feature applies to curves only and not bars or area curves.
The default value for GRAPH_POSITION_MODE is AXIS.
DATE/TIME axes can be drawn on both horizontal and vertical axes.
When the axis system has been set up as a DATE/TIME axis, the incoming data
for all three types of graph plotting should be in format
YYYY-MM-DD HH:mm:ss (YYYY =year, e.g. 1991), MM =month,
e.g. June=06, DD =day of month (1-31), HH =hour, mm =minutes,
ss =seconds). Therefore 1200UTC on 15 June 1991 would have the value
'1991-06-15 12:00:0' .
Types of Graph Plotting
There are three types of graph plotting available, Line Charts (Curves),
Bar Charts and Area Charts. The type required may be defined by setting the parameter
GRAPH_TYPE to 'BAR', 'AREA' or
'CURVE' (default).
Curve Plotting
Curve plotting in Magics means the drawing of polylines,
where the lines to be drawn are described by their X and Y values within a set of X/Y axes.
Any number of curves may be drawn on the same set of axes. Action routine
PGRAPH must be called for each curve.
The user may define the line style, colour and thickness of each curve to be plotted
by setting the parameters GRAPH_LINE_STYLE,
GRAPH_LINE_COLOUR and GRAPH_LINE_THICKNESS.
By using variations of these three parameters, users can plot many curves and still
distinguish them from one another.
Methods of Curve Plotting
There are two different methods of drawing curves:
STRAIGHT, where the points on the curve are joined by straight lines.
There is no smoothing applied in this case.
ROUNDED, where a smoothing algorithm is applied to the curve.
The parameter GRAPH_CURVE_METHOD should be set to denote
the method required. The default is to have straight curves. For rounded curves,
there are various interpolations available, for example SPLINE
and CUBIC. Users may select an interpolation by setting
GRAPH_CURVE_INTERPOLATION to the desired one, the default being
SPLINE.
The degree of smoothing applied can be controlled by the user setting the parameter
GRAPH_SMOOTHING_FACTOR to an integer value. The default is
3 which means that the smoothing algorithm will be applied three times.
It is also possible to plot curves marked with marker symbols. Symbols in this case
are Magics marker symbols
and are plotted on the position of each data point on the curve.
The parameter GRAPH_SYMBOL controls the plotting of symbols on curves.
It has three valid values: ON, OFF and SYMBOLS_ONLY:
OFF - No symbol plotting will take place
ON - A symbol is plotted on the position of each data point in the curve.
The curve itself will not be drawn in the vicinity of the symbol, i.e. the symbols will be
blanked. A curve with symbols may be straight or rounded.
SYMBOLS_ONLY - A symbol is plotted on the position of each data point in the curve.
The curve itself will not be drawn in the vicinity of the symbol, i.e. the symbols will be
blanked. A curve with symbols may be straight or rounded.
GRAPH_SYMBOL_MARKER_INDEX should be set to the index number
of the marker symbol required. GRAPH_SYMBOL_HEIGHT
and GRAPH_SYMBOL_COLOUR enable the user to control the height
and colour of the marker symbols.
Blanking of Crossing Curves
Each curve drawn can have a blanking applied to it, if required. That is, a
certain area each side of the curve will be blanked and any previous plotting in
those areas will be deleted. The parameter GRAPH_BLANKING is
used to control blanking of curves, the default being 'OFF'.
GRAPH_BLANKING_GAP may be used to define the width of the
blanking area around the curve. The default is 0.2 cm.
Missing Data
Missing data occurs when the data presented for graph plotting contains data
that is outside the current axis system in either the X or Y direction.
The user may also instruct Magics to ignore data above
or below certain values. For the Y axis, the parameters
GRAPH_Y_SUPPRESS_ABOVE and
GRAPH_Y_SUPPRESS_BELOW may be used to achieve this.
The default values for these parameters are 21.E6 and -21.E6
respectively. Similarly, for the X axis, the parameters
GRAPH_X_SUPPRESS_ABOVE and
GRAPH_X_SUPPRESS_BELOW may be used.
If data falls outside the axis system but inside the suppress values,
an error will be printed.
For DATE/TIME axis, there are separate suppress parameters:
GRAPH_DATE_X_SUPPRESS_ABOVE
GRAPH_DATE_X_SUPPRESS_BELOW
GRAPH_DATE_Y_SUPPRESS_BELOW
GRAPH_DATE_Y_SUPPRESS_ABOVE
The format of the values for these parameters is the same as for
GRAPH_CURVE_DATE_X_VALUES described above
(see ).
Magics gives the user three options to deal with
missing data. The parameter GRAPH_MISSING_DATA_MODE is used to
control missing data and may be set to one of the three following values:
IGNORE, JOIN or DROP:
IGNORE - Magics will only plot that
part of the curve for which data exists. This means that, if there are missing data,
no lines will be drawn from the point preceding the missing data or to the point following.
JOIN - this option means that the curve will be drawn as if
the missing points do not exist. In this case the part of the curve, from the
point preceding the missing data to the point following it, will be drawn.
DROP - this means that, if there are missing data, the curve
will continue to be drawn but, the curve will be drawn from the point preceding the
missing data towards the point outside the axis until it reaches the X axis. It is
then drawn along the X axis until the last point outside the axis when it will be
drawn towards the point following the missing data.
There are parameters to control the colour, line style and thickness of missing
data when plotted.
Bar Chart Plotting
Bar chart plotting in Magics is the plotting of
vertical Bars within an axis system. Each Bar in the chart is defined by its X values
and by the lower and upper Y values. The X and Y values relate to the X and Y axes
respectively. X values give the positions of centres of the Bars in the X direction
and may be passed in an array using the parameter
GRAPH_BAR_X_VALUES. The starting positions of the bars in the
Y direction is given by the values in the array set by the parameter
GRAPH_BAR_Y_LOWER_VALUES. The end positions are given by the
values in the array set by GRAPH_BAR_Y_UPPER_VALUES.
If GRAPH_BAR_Y_LOWER_VALUES is not set by the user,
Magics will assume that all the Y values start at the X axis,
i.e. they all have a value of 0.0. The width of the Bar may be set by the
user by setting the parameter GRAPH_BAR_WIDTH to the desired width.
The default value for the width is half the distance between major ticks on the X axis.
If any of the X and Y values would cause any part of the Bar to be drawn outside the
subpage, this part of the Bar will not be plotted and an error message will be given.
For DATE/TIME axis the appropriate parameters can be found in
.
The parameter GRAPH_SHADE should be set to OFF
if no shading of the bars is required. The default is ON. When shading
is turned off, the outline of the bars will be drawn. GRAPH_SHADE_STYLE
may be set to define the type of shading required. Three types of shading are available:
AREA_FILL (solid shading), HATCH and DOT.
GRAPH_SHADE_COLOUR and GRAPH_SHADE_DENSITY
may be set to define the shade colour and density of dots required.
The standard Bar Chart in Magics consists of one set of
data per graph. Action routine PGRAPH will only draw one Bar chart
each time it is called. However, by using the Magics graph
facilities, users can display more than one set of Bar Chart data on the same graph.
Following are some examples of bar charts the user can plot. Please note that these
bar charts are not available in Magics by name but can be
user-generated.
Clustered. In this case, a different bar chart can be plotted for each different
set of data. The different bars can be placed next to each other, by varying the X axis
values, and can be coloured and/or shaded differently.
Overlapping. Here, the bars for the second set of data can be moved slightly
to one side and then plotted over the first set.
Hidden. This is like overlapping bars, except that the second set of bars is
plotted in the same position as the first.
Stacked. The second set of bars can be plotted on top of the first set. Thus,
both sets of bars should be completely visible.
The above bar charts can only be achieved by calling PGRAPH
for each set of data to be plotted. It is the user's responsibility to change the
width, colour, shading etc. of the bars for each call. The parameter
GRAPH_BLANKING should be set to 'ON' for overlapping
or hidden bar charts. It is also the user's responsibility to provide the correct
X values for clustering/overlapping bars and the correct Y values for stacked/hidden bars.
Area Chart Plotting
An area chart is one in which the area between two curves can be shaded.
To plot area curves, the parameter GRAPH_TYPE
should be set to AREA. Data for the first curve should be passed
in the same way as for CURVE plotting, e.g.
CALL PSET1R('GRAPH_CURVE_X_VALUES', XAR, M)
CALL PSET1R('GRAPH_CURVE_Y_VALUES', YAR, M)
The data for the second curve may be passed to Magics
in two arrays as follows:
CALL PSET1R('GRAPH_CURVE2_X_VALUES', XAR2, M2)
CALL PSET1R('GRAPH_CURVE2_Y_VALUES', YAR2, M2)
For DATE/TIME axes the appropriate parameters can be found in
.
If the CURVE2 values are not set, it is assumed by
Magics that the second curve is all zeros, i.e.
the second curve travels along the X axis.
The curve lines will not be plotted. If required, they may be plotted by setting
GRAPH_TYPE to CURVE and calling PGRAPH
again.
The parameter GRAPH_SHADE_STYLE may be set to define the
type of shading required. Three types of shading are available:
AREA_FILL (solid shading), HATCH and DOT.
The parameters GRAPH_SHADE_COLOUR, GRAPH_SHADE_DOT_SIZE
and GRAPH_SHADE_DENSITY may be set to define the colour of the
shading, size and the density of dots required.
There are two type of area charts, straight and rounded, and these are similar to
straight and rounded curves. The parameter GRAPH_CURVE_METHOD should
be set to the required value, the default being straight.
Graph Legend
It is possible to plot a legend to describe the graph(s) plotted.
This may be achieved by setting the parameter LEGEND to
'ON', e.g.
CALL PSETC('LEGEND','ON').
The legend plotted depends on the type of graphs required - bars, curves or area curves.
A curve legend will basically consist of a description of each curve plotted in the current page,
i.e. line style, colour, thickness.
If symbols have been plotted, an example will appear in the legend. A bar chart or
area chart legend will consist of a box filled with the same type of shading as used in
the plotting.
The legend text in graph plotting should be supplied by the user. If not supplied,
Magics will plot a default text of a question mark (?)