Defines the x-axis in each window for high-resolution graphics.
Option
RESET = string token |
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 = string tokens |
Position of title (middle, end) |
TDIRECTION = string tokens |
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 = string tokens |
Positioning of the tick marks on the axis (inside, outside, across) |
LABELS = texts or variates |
Labels at each major tick mark |
LPOSITION = string tokens |
Position of the axis labels (inside, outside) |
LDIRECTION = string tokens |
Direction of the axis labels (parallel, perpendicular) |
LROTATION = scalars or variates |
Rotation of the axis labels |
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 = scalars |
Pen to use to write the axis title |
PENAXIS = scalars |
Pen to use to draw the axis |
PENLABELS = scalars |
Pen to use to write the axis labels |
ARROWHEAD = string tokens |
Whether the axis should have an arrowhead (include, omit) |
ACTION = string tokens |
Whether to display or hide the axis (display, hide) |
TRANSFORM = string tokens |
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% = scalars |
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% = scalars |
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 |
DREPRESENTATION = scalars, variates or texts |
Format to use for dates and times printed at the marks |
VREPRESENTATION = string tokens |
Format to use for numbers printed at the marks (decimal, engineering, scientific); default deci |
YOMETHOD = string tokens |
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 tokens |
Method to use to set the position of the origin on the z-axis if not set explicitly by ZORIGIN (upper, lower, center, centre) |
REVERSE = string tokens |
Whether to reverse the axis direction to run from upper to lower instead of the default lower to upper (yes, no); default no |
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 obtain an inverted scale by setting parameter REVERSE=yes. 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 LOWER. 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 value on the y-axis, or the lower value, or in the centre. The initial default (if neither of these parameters has been specified) is to put the axis at the bottom of the y-axis, which will be the lower value unless the scale is reversed. 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. If the numbers represent dates or times, you can specify their formats using the DREPRESENTATION parameter (see the PRINT directive for details). By default, numbers are printed in decimal form. If you would prefer scientific format you can set parameter VREPRESENTATION=scientific; numbers are then printed as a decimal number with absolute value less than 10, followed by an exponent (e.g. 3.4567 E4 for 34567). Alternatively, you can set VREPRESENTATION=engineering to use engineering format; the decimal number then has an absolute value less than 10000, so the exponent is a multiple of 3 (e.g. 34.567 E3 for 34567). With scientific or engineering formats, the DECIMALS parameter sets the number of significant figures to use rather than the number of decimal places.
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. Alternatively, you can use the LROTATION parameter to specify the direction of the labels more precisely, as a rotation in degrees from the horizontal (i.e. parallel) direction. If LROTATION is specified, any setting of LDIRECTION is ignored.
Setting MARKS=* will return to the default positioning of the tick marks. Setting LABELS=* will switch off any labels previously specified. Setting MPOSITION=* will switch off any tick marks, and setting LPOSITION=* or LDIRECTION=* will switch off any labels.
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. 10x), and square for x2.
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, LROTATION, NSUBTICKS, YORIGIN, ZORIGIN, PENTITLE, PENAXIS, PENLABELS, ARROWHEAD, ACTION, TRANSFORM, LINKED, MLOWER%, MUPPER%, DECIMALS, DREPRESENTATION, VREPRESENTATION, YOMETHOD, ZOMETHOD, SAVE.
See also
Directives: YAXIS, ZAXIS, AXIS, FRAME.
Procedure: DHELP.
Commands for: Graphics.
Example
" Example DGRA-1: Draw a scatter plot" " File DGRA-1.DAT contains data on deaths from lung cancer and smoking rates in 11 countries in 1930, from a US report in 1964." " Read the data recorded in the file." FILEREAD [NAME='%gendir%/examples/DGRA-1.DAT'] country,deaths,cigarettes " Display the data in a high-resolution graph." TEXT cancer; VALUES='Lung cancer and smoking in 1930' DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Add the axis titles and bounds, and a grid." XAXIS WINDOW=3; TITLE='Cigarettes per man per year'; LOWER=0 YAXIS WINDOW=3; TITLE='Deaths per million'; LOWER=0 FRAME [GRID=xy] WINDOW=3 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Specify the axis labelling precisely." XAXIS WINDOW=3; MARKS=!(0,300...1500) YAXIS WINDOW=3; MARKS=!(0,100...500); NSUBTICKS=3 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Label the points with the names of the countries." PEN 1; LABELS=country; SYMBOLS=0 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes; PEN=1 " Fit a linear regression line (assuming variance proportional to the square of the mean) to the relationship and add the fitted line to the graph." MODEL [DISTRIBUTION=gamma; LINK=identity] deaths FIT [PRINT=*] cigarettes RKEEP FITTEDVALUES=fit PEN 2; METHOD=line; SYMBOLS=0; CLINE=2 DGRAPH [SCREEN=keep; WINDOW=3; KEYWINDOW=0] fit; cigarettes; PEN=2