# Symbol Plotting

## Introduction

Symbol plotting in Magics is the plotting of different types of symbols at selected locations. A symbol in this context is a number, a text string, a Magics marker (see marker symbols in Figure XII-2 on page XII-13) or a wind flag/arrow.

To plot symbols, it is necessary to pass information to Magics that describes the symbols as well as the positions where the symbols are to be plotted. All this information is passed to Magics via arrays, which may consist of one or more elements. The position of a symbol may be defined by its geographical location (latitude/longitude), by its position in centimetres from the bottom left hand corner of the SUBPAGE or by its position, in axis units, within an axis system. Only those symbols whose positions are within the subpage will be plotted. There are facilities in symbol plotting that allow the user to control the height and colour of each symbol and, if required, a legend describing the symbols may be plotted. Examples of symbol plotting can be found in Symbol Program Examples.

## Action Routine PSYMB

Symbol plotting is achieved in Magics by calling action routine `PSYMB` which, like all Magics action routines, has no arguments. Parameters associated with Symbol plotting may be set before `PSYMB` is called. `PSYMB` will take into account only those parameters which have been set before it is called. All other symbol parameters will be assigned their default values, if they exist. Details of any errors that may be detected by `PSYMB` are given in SYMBOL Plotting : Error Codes.

## Input Data

### Position Data

All input data for symbol plotting are passed to Magics via arrays. The parameter SYMBOL_POSITION_MODE is used to describe the input position data. Valid values are `GEOGRAPHIC`, `PAPER` and `GRAPH`, the default value being `GEOGRAPHIC`. Two arrays are used to pass the position information, e.g.

        CALL PSET1R ('SYMBOL_INPUT_X_POSITION',AR1,N)
        CALL PSET1R ('SYMBOL_INPUT_Y_POSITION',AR2,N)

where `AR1` and `AR2` are arrays of `N` elements.

In `GEOGRAPHIC` mode, the parameter SYMBOL_INPUT_X_POSITION should be used to pass the longitudes of the symbols and SYMBOL_INPUT_Y_POSITION should be used to pass the latitudes.

In `PAPER` mode, SYMBOL_INPUT_X_POSITION and SYMBOL_INPUT_Y_POSITION should be used to pass the X and Y positions respectively of the symbols in centimetres, these positions being relative to the lower left corner of the SUBPAGE.

In `GRAPH` mode, SYMBOL_INPUT_X_POSITION and SYMBOL_INPUT_Y_POSITION should be used to pass the X and Y positions in axis units. The X and Y values, i.e. the longitude and latitude positions or the paper coordinates, should be in the corresponding pair of array elements. If the position specified for a symbol does not fall within the current subpage, that symbol is not plotted.

### Symbol Input Data

There are four different types of SYMBOL input data, i.e. numbers, text, wind and markers. The parameter SYMBOL_TYPE is used to define the type of symbol required,e.g.

        CALL PSETC ('SYMBOL_TYPE','MARKER')

It can have one of four values: `NUMBER`, `TEXT`, `WIND` or `MARKER`, the default being `NUMBER`. Only one of the above four types can be plotted in any one call to `PSYMB`. `NUMBER` input data are the actual numbers to be plotted and are passed as follows:

        CALL PSET1R ('SYMBOL_INPUT_NUMBER_LIST',RARAY,N)

where `RARAY` is a real array of `N` elements. `TEXT` input data consists of text strings which are to be plotted and are passed as follows:

        CALL PSET1C ('SYMBOL_INPUT_TEXT_LIST',CARAY,N)

where `CARAY` is a character array of `N` elements. `MARKER` input data consists of indices to Magics MARKERS (see marker symbols in Figure XII-2 on page XII-13) and are passed as follows:

        CALL PSET1I ('SYMBOL_INPUT_MARKER_LIST',IARAY,N)

where `IARAY` is an integer array of `N` elements. `WIND` data consists of the wind speed and direction and are passed as follows:

        CALL PSETR ('SYMBOL_INPUT_WIND_SPEED',SPARAY,N)
        CALL PSETR ('SYMBOL_INPUT_WIND_DIRECTION',DARAY',N)

where `SPARAY` and `DARAY` are real arrays of `N` elements. Please note that wind symbols are only available in `INDIVIDUAL` mode.

The POSITION arrays and the DATA INPUT arrays should all have the same number of elements. The symbol in the i'th element of the DATA array will be plotted in the position given by the i'th elements of the POSITION arrays. It is the user's responsibility to ensure that they correspond correctly. If the arrays are of different lengths, Magics will limit all the arrays to the size of the smallest array and a warning message will be printed. There is an exception to this as SYMBOL_INPUT_MARKER_LIST may consist of only one element and, if it does, the marker indexed by this one value will be plotted for all the values in the data arrays.

## Methods of Symbol Plotting

There are three methods for plotting symbols: `TABLE`, `INDIVIDUAL` and `ADVANCED`. The required method may be specified by setting the parameter SYMBOL_TABLE_MODE to '`ON`' (`TABLE` mode), '`OFF`' (`INDIVIDUAL` mode) which is the default, or '`ADVANCED`'. Following is a description of the three different modes.

### INDIVIDUAL Mode

Symbol plotting in `INDIVIDUAL` mode means that the colour and height of the symbols to be plotted are controlled by the values set in the Magics parameters SYMBOL_COLOUR and SYMBOL_HEIGHT. All the symbols, for each `PSYMB` call, are plotted with the same colour and height. To plot symbols in `INDIVIDUAL` mode the parameter SYMBOL_TABLE_MODE should be set to '`OFF`'.

### TABLE Mode

TABLE mode allows users to plot symbols within specified ranges of values and with varying colours and heights. Wind symbols are not available in table mode. To plot symbols in TABLE mode, the parameter SYMBOL_TABLE_MODE should be set to '`ON`'. When calling `PSYMB` in TABLE mode, the user must pass information to Magics to describe the minimum and maximum of each range required and may also pass information to describe the height and/or colour for each of the desired ranges. All this information should be passed in the form of tables and Magics parameters exist to enable this.

The parameters for passing the minimum and maximum of the ranges are SYMBOL_MIN_TABLE and SYMBOL_MAX_TABLE, respectively. The minimum values of the required ranges may be passed to Magics as follows:

        CALL PSET1R ('SYMBOL_MIN_TABLE',RMIN,N)

where `RMIN` is a real array of `N` elements. The maximum values should be placed in the corresponding elements of an array and passed to Magics as follows:

        CALL PSET1R ('SYMBOL_MAX_TABLE',RMAX,N)

where `RMAX` is a real array of `N` elements. The colour to be used for each of the ranges may be passed using the parameter SYMBOL_COLOUR_TABLE , e.g.

        CALL PSET1C ('SYMBOL_COLOUR_TABLE',COLTAB,N)

where `COLTAB` is a character array of `N` elements. Similarly, the heights for each range may be passed as follows:

        CALL PSET1R ('SYMBOL_HEIGHT_TABLE',HGTAB,N)

The input data and plotting positions required to use these tables should be passed using the parameters described in . Only those symbols, whose values in SYMBOL_INPUT_NUMBER_LIST fit within one of the specified ranges, will be plotted. To fit within a range, the values must be greater than or equal to the minimum of the range and less than the maximum of the range. If ranges overlap, a symbol will be plotted in the first range in the table into which it fits.

#### Parameters Required in TABLE Mode

To plot symbols in table mode the parameter SYMBOL_TABLE_MODE should be set to '`ON`'. When in TABLE mode, it is necessary to pass the information relating to the minimum and maximum of the ranges (SYMBOL_MIN_TABLE / SYMBOL_MAX_TABLE) as well as the input number data (SYMBOL_INPUT_NUMBER_LIST). The tables containing the colours and heights of the ranges (SYMBOL_COLOUR_TABLE / SYMBOL_HEIGHT_TABLE) may be passed if required. If these are not passed the values set in SYMBOL_COLOUR and SYMBOL_HEIGHT will be used for all the ranges.

## ADVANCED Mode

Symbol plotting in `ADVANCED` mode means that the colour and height of the plotted symbols are determined automatically according to configurable rules. First, the data values can be clumped into ranges, by setting SYMBOL_ADVANCED_TABLE_SELECTION_TYPE to one of the following:

`COUNT`: specify the number of ranges

`INTERVAL`: specify the data value interval size

`LIST`: specify a list of ranges

Also configurable is the way that the colours are selected; by setting SYMBOL_ADVANCED_TABLE_COLOUR_METHOD to one of the following, different strategies can be used:

`CALCULATE`: automatically create a colour gradient using the HSL colour wheel

`LIST`: specify a user-defined list of colours

Likewise, the symbol heights can be specified in different ways by setting SYMBOL_ADVANCED_TABLE_HEIGHT_METHOD to one of the following:

`CALCULATE`: automatically create a height gradient

`LIST`: specify a user-defined list of heights

## TABLE Mode Types

TABLE mode may be used with the symbol types NUMBER, TEXT and MARKER but not with WIND. The symbol type required must be passed by setting the parameter SYMBOL_TYPE to one of the above valid values. Following is a description of how each of the symbol types is used in TABLE mode.

### NUMBER Data

The minimum and maximum values of the ranges and the input NUMBER data and position data should be passed to Magics as described above. Each number in the input NUMBER data will be checked against the values in the minimum and maximum tables to find the range in which this number falls, thus finding the appropriate index to the tables. If a colour table has been passed to Magics, the index is used to find the corresponding colour in the SYMBOL_COLOUR_TABLE. Likewise, the appropriate height may be found in SYMBOL_HEIGHT_TABLE. The number will then be plotted at the position given by the POSITION arrays with the colour and height extracted from the tables. If the colour and/or height tables have not been passed, the number will be plotted with the attributes given by SYMBOL_COLOUR and/or SYMBOL_HEIGHT. The following are diagrams showing the mechanism for plotting NUMBER symbols in TABLE mode

Do we really need these table examples here? Surely a couple of good examples (code & output) would be better...

### TEXT Data

To plot TEXT data in TABLE mode, a table of text strings corresponding to the ranges required must be passed as follows:

        CALL PSET1C ('SYMBOL_TEXT_TABLE',TEXTAB,N)

where `TEXTAB` is a character array of `N` elements. The colours and heights for the various ranges and the input data should be passed as described for NUMBER data. The mechanism for plotting TEXT data is the same as for NUMBER data except that instead of plotting the number the appropriate text string from SYMBOL_TEXT_TABLE is plotted. The following are diagrams showing the mechanism for plotting TEXT symbols in TABLE mode.

Tables? Surely not...!

### MARKER Data

The method of plotting MARKER data is the same as for TEXT data except that markers are plotted. The user must pass a table of marker indices corresponding to the required ranges, e.g.

        CALL PSET1I ('SYMBOL_MARKER_TABLE',MTAB,N)

No tables please...!

## SYMBOL_INPUT_MARKER_LIST

If only one symbol marker is required to be plotted at one or more positions, it is sufficient to pass a marker list with just one marker number, e.g.

        CALL PSET1I ('SYMBOL_INPUT_MARKER_LIST',IMARK,1)