# Axis Plotting

## Introduction

Magics axis facilities allow users to plot horizontal and vertical axes on non-geographical plots. These facilities include axis labelling, axis title plotting and subdivision of axes with ticks. There is also a facility for plotting automatic date/time axes.

Parameters exist which give the user control over all aspects of axis plotting, e.g. position, orientation, colour, thickness etc. Axis plotting is achieved by calling the action routine `PAXIS`, which draws one axis each time it is called. Any axis parameters required must be set before `PAXIS` is called. `PAXIS` may be called as often as it is needed. If more than one axis is to be drawn with the same axis orientation and position, users should ensure that there is sufficient room between the subpage and page frame lines.

Axis plotting is based on the Magics subpage. It is necessary to ensure that the dimensions of the subpage are set before `PAXIS` is called, as the requested axis will be drawn on one of the subpage frame lines. This means that the parameters SUBPAGE_X_LENGTH and SUBPAGE_Y_LENGTH should be set to the required values and SUBPAGE_MAP_PROJECTION should be set to '`CARTESIAN`'. Horizontal axes are always plotted along the bottom or top line of the subpage frame. Vertical axes are plotted along the left or right side of the subpage frame.

The axes, which may be regular, logarithmic or user-defined, may be subdivided with tick marks. Further subdivision between tick marks, i.e. minor ticks, is also possible. Grid lines, i.e. lines joining corresponding tick marks, may be plotted. Ticks may be labelled either on the tick marks or between tick marks.

Magics parameters exist to control all aspects of axis drawing. These parameters start with the prefix AXIS, e.g. AXIS_LINE_THICKNESS.

An axis consists of seven different parts and the drawing of each part can be turned on or off. The parts are: line, title, tip title, ticks, minor ticks, tick labels and grid. The line, ticks, tick labels and title are on by default. The grid, minor ticks and tip title are off by default.

Axes may be annotated in two ways, one called the axis title and the other called the axis tip title. The axis title is centred on the axis and the tip title is plotted at the end of the axis. The tip title would normally be used as a unit specification. The default text string for the title and tip title are blank.

## Axis Positioning

Axes may be drawn on any of the subpage frame lines. This is controlled by the parameter AXIS_ORIENTATION which may be set to '`HORIZONTAL`' (X-axis) or '`VERTICAL`' (Y-axis), the default being '`HORIZONTAL`' .

The position of an axis is controlled by the parameter AXIS_POSITION. For the x-axis it can take one of the values '`BOTTOM`' or '`TOP`' and for the y-axis the values '`LEFT`' or '`RIGHT`' may be used.

An axis is normally drawn on one of the subpage frames. However if `PAXIS` is called more than once with the same AXIS_POSITION value, each subsequent axis will be drawn between the previously drawn axis and the page frame, if there is sufficient room available. For example two calls with AXIS_POSITION set to '`RIGHT`' will draw the first axis on the right-hand subpage frame, and the second axis to the right of the first one, if there is room between the subpage and page.

It is possible to draw the lines of an axis in any position and not just at the bottom/top/left/right of the axis. This is achieved by setting the parameter AXIS_POSITION to '`AUTOMATIC`' and the parameter AXIS_LINE_POSITION to the required position. The position of the line should be given in centimetres from the lower left hand corner of the subpage. AXIS_LINE_POSITION may be used for both the X and Y axes, depending on the value set in the parameter AXIS_ORIENTATION (`HORIZONTAL` or `VERTICAL`). It is possible to plot ticks, minor ticks, titles etc on `POSITIONAL` axes. However, users should be aware that the ticks etc will only be plotted on the left side of vertical lines and on the bottom side of horizontal lines.

There is no limit to the number of times `PAXIS` may be called, even with the same AXIS_POSITION, as long as there is sufficient room. When there is insufficient room for the axis, an error message is generated and the axis is not drawn.

The parameter AXIS_LINE controls whether the axis line is actually drawn or not. The default value is '`ON`' and it should be set to '`OFF`' if the line is not required.

## Axis Line styling

The colour and thickness of the axis may be set by using the parameters AXIS_LINE_COLOUR and AXIS_LINE_THICKNESS. The default colour of the axis line is the colour of the subpage frame, i.e. SUBPAGE_FRAME_COLOUR, and the default thickness is `2`.

### Axis Grid Lines

Grid lines may be drawn from every tick by setting the parameter AXIS_GRID to '`ON`' . The colour, thickness and line style of grid lines may be controlled with the parameters AXIS_GRID_COLOUR, AXIS_GRID_THICKNESS and AXIS_GRID_LINE_STYLE. The default values for these parameters are '`YELLOW`', `1` and '`SOLID`' respectively. Axis grids will always be drawn within the subpage even if the axis itself is outside the subpage.

### Axis Ticks

Axis ticks are tick marks showing the subdivision of an axis. Users may control the drawing of tick marks by setting the parameter AXIS_TICK to '`ON`' or '`OFF`', the default being '`ON`'.

The axis tick attributes colour, size and thickness are controlled by the parameters AXIS_TICK_COLOUR, AXIS_TICK_SIZE and AXIS_TICK_THICKNESS.

An axis can be defined in four different ways with the AXIS_TYPE values '`REGULAR`' (the default), '`LOGARITHMIC`', '`POSITION_LIST`' and '`DATE`'.

- The '`REGULAR`' type is a regular axis defined by a first and a last value. The spacing of the ticks may be controlled by the user by setting AXIS_TICK_INTERVAL to the required interval. If not set by the user, Magics will select an interval that gives about 8 tick marks.

- The '`POSITION_LIST`' type may be a regular or irregular axis with the positions of the ticks specified by the user. Tick positions are measured from the starting point of the axis, i.e. from the left side for horizontal axes and from the bottom for vertical axes. They should be passed to Magics in a real array as follows:

          CALL PSET1R('AXIS_TICK_POSITION_LIST',PLIST,N)

  where `PLIST` is a real array of size `N` holding the tick positions.

  Normally the positions of the ticks for POSITION_LIST are specified in centimetres but can be given in axis (or user) units by setting the parameter AXIS_TICK_LABEL_UNITS to '`USER`' , the default being '`CM`'. In this case Magics will assume that the positions of the ticks in AXIS_TICK_POSITION_LIST are in axis units and will calculate the actual positions on the axis.

  'DATE' is a date/time axis and is fully described in Date/Time Axis Plotting

- '`DATE`' is a date/time axis and is fully described in the following section.

#### Axis Minor Ticks

Minor tick marks are smaller than, and plotted between, tick marks. They may be obtained by setting AXIS_MINOR_TICK to '`ON`' and setting AXIS_MINOR_TICK_COUNT to an integer specifying the number of minor tick marks desired between two ticks. The default values for AXIS_MINOR_TICK and AXIS_MINOR_TICK_COUNT are '`OFF`' and 1, respectively.

The colour, size and thickness of minor ticks may be controlled by setting the parameters AXIS_MINOR_TICK_COLOUR, AXIS_MINOR_TICK_SIZE and AXIS_MINOR_TICK_THICKNESS.

### Spacing Control of Axis Ticks, Minor Ticks, Grid Lines

In order to achieve good quality axis plotting without cluttering, it is important that ticks, minor ticks and grid lines do not come too close to each other. One parameter controls this: AXIS_MINOR_TICK_MIN_GAP. Using this parameter, the user may specify the smallest acceptable gap between ticks etc. The default value is 0.05cm . Note that the same parameter controls the three different features.

## Axis Labels

Labelling of axes consists of two different types; text labelling and unit labelling.

### Text Labels

There are two different types of text labelling, labelling of the axis itself, called the title text, and labelling of the end of an axis, called the tip title text .

A title text may be plotted by setting the AXIS_TITLE_TEXT to the text required, the default is a blank text string. The parameter AXIS_TITLE should be set to '`ON`' which is the default. It should be set to '`OFF`' if no title text is required. Likewise, a tip title text may be plotted by setting AXIS_TIP_TITLE_TEXT to the text required and setting AXIS_TIP_TITLE to '`ON`', which is the default.

The title text is always centre justified but the orientation of the text may be altered with the parameter AXIS_TITLE_ORIENTATION. The three valid values for this parameter are '`PARALLEL`' (the default), '`HORIZONTAL`' and '`VERTICAL`'. The orientation of the tip title text is controlled by the parameter AXIS_TIP_TITLE_ORIENTATION. Valid values are '`PARALLEL`', '`HORIZONTAL`' (the default) and '`VERTICAL`'.

Parameters exist to control the colour, height and quality of the title text and the tip title text, e.g. AXIS_TITLE_COLOUR, AXIS_TIP_TITLE_QUALITY .

### Unit Labels

Unit labelling is actually the labelling of the axis ticks. This is controlled by the parameter AXIS_TICK_LABEL which may be set to '`ON`' or '`OFF`', the default being '`ON`'.

Parameters exist to control the height, quality and colour of the tick labels, e.g.

        CALL PSETC('AXIS_TICK_LABEL_COLOUR','BLUE')

The format of the tick label may be specified by setting the parameter AXIS_TICK_LABEL_FORMAT, the default being '`(AUTOMATIC)`' .

Tick labels can be '`HORIZONTAL`' (default) or '`VERTICAL`' and this is controlled by the parameter AXIS_TICK_LABEL_ORIENTATION. The user has control over the position of the tick label, by setting the parameter AXIS_TICK_LABEL_POSITION.

The default position '`ON_TICK`' centres the value around the tick mark. The '`INTER_TICK`' position shifts all tick labels to the right, centring them between two tick marks. For example, the first tick label will be drawn between the first and the second tick.

It is also possible to suppress printing of first and/or last tick label which is sometimes useful for space reasons. This may be achieved by setting the parameters AXIS_TICK_LABEL_FIRST and AXIS_TICK_LABEL_LAST respectively. The default value for both is '`ON`', which means that the first and last tick labels will be plotted.

The parameter AXIS_TICK_LABEL_TYPE enables the user to specify the type of tick labels to be plotted, e.g. '`LABEL_LIST`', '`NUMBER`', '`LATITUDE`' and '`LONGITUDE`'. The default tick label type depends on the value set in AXIS_TYPE which may be '`REGULAR`', '`LOGARITHMIC`' or '`POSITION_LIST`'. For '`REGULAR`' and 'LOGARITHMIC', the user may specify any of the valid values for AXIS_TICK_LABEL_TYPE and the default value in these two cases is '`NUMBER`'. However, if AXIS_TYPE is set to '`POSITION_LIST`' then '`LABEL_LIST`' is the only value allowed for AXIS_TICK_LABEL_TYPE.

User defined tick labels should be passed to Magics in a character type array as follows:

        CALL PSET1C('AXIS_TICK_LABEL_LIST',TLIST,M)

where `TLIST` is an array of dimension `M`. The nth element of the array will be the label of the nth tick mark. If some of the ticks are to be unlabelled, the appropriate elements of the array should be set blank.

Label types '`NUMBER`', '`LATITUDE`' and '`LONGITUDE`' produce numeric values calculated from the first axis value and the tick interval. The special cases, '`LATITUDE`' and '`LONGITUDE`', plot the number with a degree sign and the direction (N/S/E/W).

It is possible to suppress the labelling of selected ticks using the parameter AXIS_TICK_LABEL_FREQUENCY. If set to n, only every nth tick mark will be labelled.

Logarithmic axes are labelled only at the cycle end points (i.e. ..,0.1,1,10,..). However if no endpoint exists (e.g. 2 to 9) all ticks are labelled. If there is only one endpoint it is labelled together with the first and the last ticks.

## Date/Time Axis Plotting

There are facilities for plotting an automatic date/time axis in Magics. The parameter AXIS_TYPE should be set to '`DATE`' when a date/time axis is required and the parameter AXIS_DATE_TYPE should be set to indicate the type of date/time axis required. Following is a description of how to use the date/time axis facilities.

### AXIS_DATE_TYPE

The parameter AXIS_DATE_TYPE allows the user to determine which type of axis is to be drawn. Valid values are '`HOURS`', '`DAYS`', '`MONTHS`' and '`YEARS`'. The value set will determine the axis units for a date/time axis and will indicate that the user requests Magics to label the major tick marks on the current axis with date/time and that the text of the labels to be plotted at ticks etc be calculated by Magics.

For `HOURS`, `DAYS`, `MONTHS` and `YEARS`, the parameters AXIS_DATE_MIN_VALUE, AXIS_DATE_MAX_VALUE and AXIS_TICK_INTERVAL will enable Magics to calculate the number of days/months/years to be plotted on the axis. AXIS_DATE_MIN_VALUE should be set to the starting date required with the format YYYY-MM-DD HH:mm:ss (YYYY =year, e.g. 1991, 2002, MM =month, e.g. June=06, DD = day of month (1-31), HH =hour, mm =minutes and ss =seconds). This is a character value, i.e. for 1200UTC 15 June 1991 the value set in AXIS_DATE_MIN_VALUE is '`1991-06-15 12:00:00`'. Likewise, the ending date should be set in AXIS_DATE_MAX_VALUE. The actual units used to plot the axis, i.e. days, months or years, is determined by the value set in AXIS_DATE_TYPE. The parameter AXIS_TICK_INTERVAL can be used to control the amount of major ticks to be plotted. For example if set to 2.0, every second tick will be plotted. Magics will calculate the appropriate date for each of the labels.

The major ticks on the axis will represent the main units of the axis as given by AXIS_DATE_TYPE. Minor ticks may be plotted for the entity below the main units of the axis. For example, if `DAYS` are the main units, `HOURS` may be plotted as minor ticks. Minor ticks will not be labelled.

### Axis Units

The units of the axis determine, to a large degree, the type of tick labels plotted. When set to '`HOURS`', it means that hours, days, months and years may appear on the axis tick labels. When set to '`DAYS`', it means that days, months and years may appear. If set to '`MONTHS`', only years and months may appear and, If AXIS_DATE_UNITS is set to '`YEARS`', only years may appear. Note that 'day' labels consist of the day of the week and the number of the day in the month.

### Tick Labels

The user may also decide to plot any combination of tick labels, i.e. year, month, day/date or hour. Parameters exist to enable this, i.e. AXIS_HOURS_LABEL, AXIS_DAYS_LABEL, AXIS_MONTHS_LABEL and AXIS_YEARS_LABEL. These parameters may be set to '`ON`' or '`OFF`'. The default is '`ON`', except for AXIS_HOURS_LABEL which is '`OFF`'.

Furthermore, the parameter AXIS_DAYS_LABEL is different to the others as it may be set to '`DAY`', '`NUMBER` or '`BOTH`' as well as '`off`'. The default for AXIS_DAYS_LABEL is '`BOTH`'.

Parameters exist to control the colour, height and quality of all the label types and, for `DAYS` and `MONTHS`, the number of characters in the name may be selected, e.g. `SEPTEMBER`, `SEP` or `S`.

### Axis Grids

For date/time axes only, axis grids may be positioned by the user, i.e. grids may be drawn in positions other than the tick positions. To achieve this, the parameter AXIS_DATE_GRID_POSITIONING should be set to '`POSITIONAL`', the default being '`AUTOMATIC`'. A list of positions for placing the grids should be passed using the parameter AXIS_DATE_GRID_POSITION LIST, e.g.

        CALL PSET1C ('AXIS_DATE_GRID_POSITION_LIST',GLIS,N)

where `N` is the number of positions and `GLIS` is an array containing the positions which should be in the same format as AXIS_DATE_MIN_VALUE and AXIS_DATE_MAX_VALUE described above.

### Curve Plotting

Please note that, when using a date/time axis, the X axis units used for plotting graphs (curves and bar charts) will have the format `YYYY-MM-DD HH:mm:ss` as described above.

## Axis examples using Python

The following example shows how to use a simple date axis in a Python program.

Resultant plot from example Python axis program

The next example shows how to generate the same simple date axis with the MagMacro module in Python.

Resultant plot from example Python axis program