# 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

## Input Data

All input data for graph plotting are passed to Magics via arrays. The parameter GRAPH_TYPE is used to describe the type of graph required. Valid values are `CURVE` (default), `BAR` and `AREA`. When set to `CURVE`, two one-dimensional arrays are used to pass the data describing the curve, e.g.

        CALL PSET1R('GRAPH_CURVE_X_VALUES', XAR, M)
        CALL PSET1R('GRAPH_CURVE_Y_VALUES', YAR, M)

where `XAR` and `YAR` are arrays of `M` elements. The first array should contain the X values and the second array should contain the Y values.

If GRAPH_TYPE is set to `AREA`, users may shade the area between two curves. The first curve is defined in the same way as for `CURVE` and the second one as follows:

        CALL PSET1R('GRAPH_CURVE2_X_VALUES', XAR2, M2)
        CALL PSET1R('GRAPH_CURVE2_Y_VALUES', YAR2, M2)

Input data for `BAR` charts are passed in three arrays as follows:

        CALL PSET1R('GRAPH_BAR_X_VALUES',       XAR1, M)
        CALL PSET1R('GRAPH_BAR_Y_LOWER_VALUES', YAR1, M)
        CALL PSET1R('GRAPH_BAR_Y_UPPER_VALUES', YAR2, M)

where `XAR1`, `YAR1` and `YAR2` are arrays of `M` elements each. `XAR1` should contain the X values for the bars. The lengths of the bars in the Y direction are defined by their upper and lower Y values. This means that users have the capability of plotting 'hidden' and 'overlapping' `BAR` charts.

When the axis system has been set up as a `DATE/TIME` axis, there are separate parameters for the incoming data for all three types of graph plotting. For a `DATE/TIME` curve on the X axis values are passed as follows:

        CALL PSET1C('GRAPH_CURVE_DATE_X_VALUES', CXAR, M)

where `CXAR` is a character array of `M` elements. Similarly, for a `DATE/TIME` curve on the Y axis values are passed as follows:

        CALL PSET1C('GRAPH_CURVE_DATE_Y_VALUES', CYAR, M)

The format for date values is given in . For `BAR` and `AREA` graphs, the values are defined by the parameters:

        GRAPH_BAR_DATE_X_VALUES
        GRAPH_BAR_DATE_Y_UPPER_VALUES
        GRAPH_BAR_DATE_Y_LOWER_VALUES
        GRAPH_CURVE2_DATE_X_VALUES
        GRAPH_CURVE2_DATE_Y_VALUES

## 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 (?)