XAXIS directive

Defines the x-axis in each window for high-resolution graphics.

Option

RESET = string

Whether to reset the axis definition to the default values (yes, no); default no

Parameters

WINDOW = scalars

Numbers of the windows

TITLE = texts

Title for the axis

TPOSITION = strings

Position of title (middle, end)

TDIRECTION = strings

Direction of title (parallel, perpendicular)

LOWER = scalars

Lower bound for axis

UPPER = scalars

Upper bound for axis

MARKS = scalars or variates

Distance between each tick mark (scalar) or positions of the marks along the axis (variate)

MPOSITION = strings

Positioning of the tick marks on the axis (inside, outside, across)

LABELS = texts

Labels at each major tick mark

LPOSITION = strings

Position of the axis labels (inside, outside)

LDIRECTION = strings

Direction of the axis labels (parallel, perpendicular)

NSUBTICKS = scalars

Number of subticks per interval (ignored if MARKS is a variate)

YORIGIN = scalars

Position on y-axis at which the axis is drawn

ZORIGIN = scalars

Position on z-axis at which the axis is drawn

PENTITLE = scalar

Pen to use to write the axis title

PENAXIS = scalar

Pen to use to draw the axis

PENLABELS = scalar

Pen to use to write the axis labels

ARROWHEAD = strings

Whether the axis should have an arrowhead (include, omit)

ACTION = strings

Whether to display or hide the axis (display, hide)

TRANSFORM = strings

Transformed scale for the axis (identity, log, log10, logit, probit, cloglog, square, exp, exp10, ilogit, iprobit, icloglog, root); default iden

LINKED = scalars

Linked axis whose definitions should be used for this axis in 2-dimensional graphs; default * i.e. none

MLOWER% = scalar

How large a margin to set between the lowest x-value and the lower value of the axis, if not set explicitly by LOWER (expressed as a percentage of the range of the x-values)

MUPPER% = scalar

How large a margin to set between the largest x-value and the upper value of the axis, if not set explicitly by UPPER (expressed as a percentage of the range of the x-values)

DECIMALS = scalars or variates

Number of decimal places to use for numbers printed at the marks

YOMETHOD = string

Method to use to set the position of the origin on the y-axis if not set explicitly by YORIGIN (upper, lower, center, centre)

ZOMETHOD = string

Method to use to set the position of the origin on the z-axis if not set explicitly by ZORIGIN (upper, lower, center, centre)

SAVE = pointers

Saves details of the current settings for the axis concerned

Description

There is a definition for the x-axis associated with each GenStat graphics window. This specifies how the x-axis is to be drawn when graphical output is produced in that window. The default definition for each axis requires some of the features to be determined from the data, as described below. Others have fixed defaults that are independent of the data. The XAXIS directive can be used to override the default action and specify particular aspects of the x-axis explicitly. (Similarly, directives YAXIS and ZAXIS modify the y- and z-axis definitions, respectively.) All the parameters of XAXIS are relevant when using DGRAPH, but for other directives only some of the parameters are used.

The WINDOW parameter specifies the window whose axis definition is to be altered. WINDOW can be set to a list of window numbers, in which case the other parameter lists are cycled in parallel, in the usual way. By default, only those aspects specified by subsequent parameter lists are modified; any parameters that are not set will retain their current settings. Alternatively, you can specify option RESET=yes to reset the values of any parameters that are not set for each window, back to the default values that are set up by GenStat at the start of a job.

The LOWER and UPPER parameters specify the lower and upper bounds for the axis. By default, GenStat derives suitable axis bounds from the data, as described for the appropriate directive. You can set the lower bound to a value greater than the upper bound, to obtain an inverted data scale, but the bounds must not be equal. The values specified with these parameters are on the scale of the data values that are plotted, and are independent of the normalized device coordinates used to define the window size in FRAME. The MLOWER% parameter controls the size of margin that is provided between the lower value of the axis and the smallest x-value, if the lower axis value is not set explicitly by UPPER. This is expressed as a percentage of the range of the x-values, and has the initial default of 5%. Similarly the MUPPER% parameter controls the size of the upper margin.

The YORIGIN parameter determines the value on the y-axis through which the axis is drawn. If its value is outside the y-axis bounds, the upper or lower bound is adjusted so that the axis will extend up to the specified origin. This applies whether you have set the bounds explicitly or have left GenStat to calculate them from the data. If YORIGIN is not set, the YOMETHOD parameter can specify how the position should be determined: either at the upper end of the y-axis, or the lower end, or in the centre. The initial default (if neither of these parameters has been specified) is to put the axis at the lower end. The ZORIGIN and ZOMETHOD parameters set the position of the origin on the z-axis in a similar way.

You can specify a title for the axis using the TITLE parameter. This is limited to a single line of characters. The TPOSITION parameter controls whether the title is placed in the middle or at the end of the axis, and the TDIRECTION parameter controls whether it is written parallel or perpendicular to the axis.

The axis is marked with a scale, determined automatically so that tick marks are evenly spaced and positioned to give "round" numbers for the scale values. You can set the MARKS parameter to a scalar to define the increment between tick marks. For example, setting MARKS=1.5 with bounds 10 and 2 causes tick marks to appear at 2, 3.5, 5, 6.5, 8 and 9.5. The interval must be a positive number, irrespective of the values of the bounds. Alternatively, you can set MARKS to a variate (with more than one value) to specify the actual positions of the tick marks on the axis. Any values that lie outside the axis bounds are ignored. The scale values printed next to the tick marks use a format that is determined automatically from the values, but if you set MARKS to a variate it will use the number of decimals specified in the variate declaration. If MARKS is unset or set to a scalar, you can use the NSUBTICKS parameter to specify a number of "subticks" to be drawn between each of the (major) tick marks.

When you set MARKS, you can also use the LABELS parameter to specify a set of labels to print at the (major) axis marks, instead of the numbers. For example,

TEXT [VALUES=Mon,Tues,Wed,Thur,Fri,Sat,Sun] Day

VARIATE [VALUES=1...31] Month

XAXIS 1; MARKS=Month; LABELS=Day

The strings within the text are cycled if necessary, so the number of strings can be less than the number of tick marks. The DECIMALS parameter can set the number of decimal places to use if you are printing numbers at the marks.

The MPOSITION parameter controls the positioning of the tick marks, which can be drawn on the inside or the outside of the axis, or can be drawn across the axis. With the outside setting, the tick marks are drawn towards the outside of the plot; that is below the axis if the axis is in the lower half of the plot, or above the axis if it is in the top half of the plot. The aim is then to position the tick marks away from the main part of the plot, so that they interfere with the plotted points as little as possible. With the inside setting, the marks are drawn on the opposite side (that is, to the inside of the plot), while the across setting draws them across the axis. Similarly, the positioning of the scale markings or labels is controlled by the LPOSITION parameter, with settings inside or outside. The LDIRECTION parameter controls whether the scale markings or labels are written parallel or perpendicular to the axis. Setting MARKS=* will return to the default positioning of the tick marks; LABELS=* will switch off any labels previously specified; and MPOSITION=* and LPOSITION=* will switch off tick marks or labels altogether.

The TRANSFORM parameter allows you to transform the scale of the axis. The tick marks are still defined and labelled according to the original scale, but their physical positions on the graph are transformed. So, for example, with TRANSFORM=log10, the equal physical distance between 1 and 10 would be the same as the distance between 10 and 100. The settings are the same as the names of the equivalent GenStat functions, with the addition of exp10 for the antilog transformation (i.e. 10^x), and square for x².

There are three parameters to control the pens to be used to draw the axis. These are PENTITLE, PENAXIS and PENLABEL, specifying the pen for the title, the axis and the labelling, respectively. The initial default is to use pens -1, -2 and -3 in every window. These pens are given negative numbers to allow them to be distinguished from the pens used for the contents of the plot. They are initially set up to use colour 1, line style 1, thickness 1, size 1 and font 1. You can thus control which pens are used for drawing the axis in each window, and the attributes of those pens. For example, if no XAXIS statement has yet been given,

PEN -1; LINESTYLE=4; COLOUR=2

will request that the titles in every window should be written in line style 4 and colour 2; while

PEN 29; LINESTYLE=3; COLOUR=4

XAXIS 1; PENAXIS=29

will change the appearance of just the x-axis in window 1, as pen 29 is not used for the other windows. You should of course be careful of side-effects when changing the pen numbers. For example, pen 29 may also have been modified for use in a DGRAPH statement and other attributes may have been set that are not wanted when drawing the axis. You must use the RESET option if you want to restore these pen numbers to the initial defaults. (GenStat does not allow you to set negative pen numbers explicitly.)

The ARROWHEAD parameter controls whether the axis is drawn with an arrowhead at the end.

You may sometimes wish to use the axis definitions merely to control the positioning of the plot in the x-direction (using the UPPER and LOWER parameters), or you may wish to hide the axis temporarily in case it is obscuring information in the plot. You can do this by setting parameter ACTION=hide.

Axis annotation is plotted in the margins specified by the FRAME directive. You may wish to reduce the size of these margins if you have defined axes that use less space, for example by keeping within the area of the graph itself, or by omitting titles or labels. Space can thus be regained and used for plotting data. However, if the margins are too small the axis annotation may be "clipped" at the boundaries of the margins; if this happens, you can use FRAME to increase the margin size. The margins are used by DGRAPH, DHISTOGRAM and DCONTOUR, but they are ignored by other directives.

The LINKED parameter is useful when you have several related plots in different windows within the frame. If, for example, you set LINKED=n, the attributes of the current x-axis will all be taken (at the time of plotting) from the definition of the x-axis for any 2-dimensional graph in window n. Also, you can edit the attributes of all the linked axes simultaneously in the graphics viewer in GenStat for Windows.

The current settings of the axis for a particular window can be saved in a pointer supplied by the SAVE parameter. The elements of the pointer are labelled to identify the components. The settings are those for the axis itself, so you should check that the axis is not linked to one in another window. (The 'linked' element contains the window number, or a missing value there is no link.) The SAVE parameter is of most use within procedures, where it may be necessary to check or modify particular XAXIS settings before constructing complicated graphs. Also, the DKEEP directive allows you to extract the actual bounds used when plotting; these will be the bounds determined from the data if none have been defined explicitly by XAXIS.

Option: RESET.

Parameters: WINDOW, TITLE, TPOSITION, TDIRECTION, LOWER, UPPER, MARKS, MPOSITION, LABELS, LPOSITION, LDIRECTION, NSUBTICKS, YORIGIN, ZORIGIN, PENTITLE, PENAXIS, PENLABELS, ARROWHEAD, ACTION, TRANSFORM, LINKED, MLOWER%, MUPPER%, DECIMALS, YOMETHOD, ZOMETHOD, SAVE.