Axis PlottingIntroductionMagics 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 PositioningAxes 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 stylingThe 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 LinesGrid 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 TicksAxis 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 TicksMinor 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 LinesIn 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 LabelsLabelling of axes consists of two different types; text labelling and unit labelling.Text LabelsThere 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 LabelsUnit 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 PlottingThere 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_TYPEThe 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 UnitsThe 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 LabelsThe 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 GridsFor 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 PlottingPlease 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 PythonThe following example shows how to use a simple date axis in a Python program.Resultant plot from example Python axis programThe next example shows how to generate the same simple date axis with the MagMacro module in Python.Resultant plot from example Python axis program