ploticus: proc axis (xaxis or yaxis)

## proc axis (xaxis or yaxis) | Welcome Gallery Handbook |
| Manual page for proc_axis_(xaxis_or_yaxis)(PL)

## DESCRIPTION

proc xaxis generates an X axis.``
proc yaxis generates a Y axis.``

Both procs use the same attributes and operate in the same way.``

A typical axis is a line with some number of regularly placed marks called tics, each of which has a label called a stub The axis also usually has a descriptive text label nearby.``

Often axis attributes are specified within proc areadef using `xaxis.` or `yaxis.` prefixes on the attribute names. This is usually more convenient, and allows the entire areadef with axes specifications to be cloned for multiple plots on a page.`` However, you might want to use separate axis procs, for example, if multiple axes per plot are needed,

## FEATURES

proc xaxis/yaxis allows tics and stubs to be spaced incrementally or at irregular points. A number of automatic stub formats are provided for dates, times, etc.`` Axes may be placed anywhere, and grid lines or blocks may optionally be rendered.``

## EXAMPLES

See the Gallery Scaling and Axes examples

## PREREQUISITES

A plotting area must be defined using proc areadef.`` If stubs are to be taken from data fields, data must have already been accessed or defined using proc getdata.``

## MODES

Stubs may be automatically generated (incremental), specified within the script, or taken from plot data fields, an external file, or defined categories.`` Self-locating stubs (stubs that contain an embedded location) may be used.``

## VARIABLES THAT ARE SET

XINC or YINC will be set to hold the axis increment value.``

## MANDATORY ATTRIBUTES

None. Default behavior is automatic incremental stubs and small outward tics at every unit.``

## ATTRIBUTES

label text

  A text label that will be rendered near the axis, used to describe what is being plotted.
  Example: `label: Yearly Income`

tics `yes` | `none` | linedetails

  If anything other than `none` is specified, tics will be rendered.`` A linedetails specification may be given to control the color, etc. of tic marks.`` Tics will be placed whereever a stub is placed.`` Incremental tics may be rendered without stubs by setting `stubs: none`; they can be controlled using `ticincrement`.``
  Example: `tics: yes`

The stubs attribute controls the contents of the stubs. There are several mode variants described below:

stubs incremental [h] [units]

  Generate incremental stubs for numeric or date or time data.`` A stub will be generated and placed at every h units.`` h and units may both be omitted for numeric data in which case a reasonable default increment will be used (an h value of 0 has the same effect).``
  Example: `stubs: incremental 10` ..would place stubs at every 10 units.``
  units allows flexibility with stub increments.`` The following table illustrates some possibilities:

      scaletype  h units          result
      ---------  -------------    ------------
      linear     1 1000           one stub every 1000,
      				stubs expressed in # of thousands
      linear     1 0.01           one stub every 0.01,
      				stubs expressed in # of hundredths
      date       1 		    one stub per day
      datetime   1 		    one stub per day
      date       1 month	    one stub per month
      date       3 months	    one stub every three months
      date	   1 year           one stub every year
      time       20 minutes       one stub every 20 minutes
      time       1 hour           one stub every hour

  See scaleunits for more info on units.``

stubs text multi-line text

  Indicates that the following lines of the script contain literal stub text, with one line per stub, and terminating with a blank line.``
  Example:

      stubs:  text
      	New York
      	Atlanta
      	Detroit
      	Baltimore

  ``

stubs list text

  Same as `stubs text` except that all stubs are given on one line, with individual stubs separated by `\n`.``
  Example: `stubs: list New York\nDetroit\nBaltimore`

stubs file filename

  Same as `text` except that content is to be taken from filename.``
  Example: `stubs: /home/myplots/stubs2`

stubs datafields= dfield1 ,[dfield2]

  Stub content is to be taken from one or two data fields.``
  Example: `stubs: datafields=1,2` .. would use the first and second data field for stubs.``

stubs usecategories

  If the scaletype for this axis is `categories`, this indicates that the defined category names should be used as the stubs. Implies self-locating.``

stubs none

  Don't display any stubs.`` Example: `stubs: none`

selflocatingstubs (see `stubs`, above)

  Same as `stubs` except that stubs are self-locating. Each self-locating stub contains a plottable value that determines where it will be placed.``
  For the `text`, `list` and `file` modes, the first token (white-space delimited) in each stub is taken to be a plottable value. The remainder of the stub is displayed.`` To display the placement value specify the value twice.``
  For the `datafields` mode, the first field a is used for placement and the second field b is used for content. To display the placement value, specify the same field# twice.``
  Examples of selflocating stubs:
  stubs from datafields: lineplot3

stubrange min [max]

  Range (in scaled units where tics and stubs should start and stop along the axis. Default range is the plot area minimus and maximus.`` (If text stubs are being given, low end of range defaults to one unit in from the limit since this is usually what is desired for bar graphs, etc.) If only one value is given it is taken to be the minimum.`` Example: `stubrange: 5 95`

stubformat string

  Controls the format of numeric, date, or time stubs.

  For numeric stubs, string is a printf-spec Default is `%5.0f`.``
  Example: `stubformat: %5.3f`

  For other scale types such as date or time, a display format may be specified.`` See scaleunits for supported display formats. If `stubformat` is not specified when date/time scaling is being done, the current notation, or one similar to it, is used.``

stubevery n

  When doing stubs from a data field or categories, this will cause every nth stub (beginning with the first) to be displayed; the rest will not be displayed. May be useful to avoid display of all categories as stubs and when categories represent a logical series.``

location locvalue

  Position of the axis line. For an x axis this value is in y space; for a y axis this value is in x space. Append `(s)` to indicate scaled units. Tics and stubs will be placed relative to the position of the line.`` This attribute is important when placing multiple axes or axes at unusual locations.``
  Example: `location: 105(s)`

axisline linedetails

  Details pertaining to the axis line. Use `none` to completely suppress the axis line.``
  Example: `axisline: width=1.2 color=green`

axislinerange min [max]

  May be used to control the range of the axis line.`` If only one value is given it is taken to be the minimum.``
  Example: `axislinerange: 5 95`

labeldetails textdetails

  Details for rendering the label. Example: `labeldetails: size=13 style=I`

labeldistance n

  Distance of the label below / left of the axis line.`` Absolute units . This could also be done via `labeldetails: adjust=`.``
  Example: `labeldistance: 0.6`

stubdetails textdetails

  Details pertaining to stub text rendering.``
  Example: `stubdetails: size=7`

stubreverse yes|no

  If `yes`, reverses the placement of stubs so that the first stub is placed at the maxima and the last at the minima, as is often desired when placing text stubs along the Y axis.`` If `no`, no stub reversal is done.`` Default is for reversal to be done If text stubs are to be placed along the Y axis then the default is `yes`, otherwise the default is `no`.`` Example: `stubreverse: yes`

signreverse yes|no

  If `yes`, presents numeric stubs with sign reversed.`` May be useful in creating an axis that moves from high values to low values. (Introduced in version 1.3).``

stubvert yes|no

  If `yes`, renders X axis stubs using vertical text. This is useful if X axis stubs are too long to fit horizontally.`` Example: `stubvert: yes`

stubslide lenvalue

  If specified, axis stubs are shifted by the given amount.`` For example, a positive value would shift X axis stubs to the right.`` For example, a negative value would shift Y axis stubs downward.`` Tics are not shifted.``
  Example: `stubslide: 0.5`
  For another example see axis9b

ticslide lenvalue

  If specified, axis tics are shifted by the given amount.`` For example, a positive value would shift X axis stubs to the right.`` For example, a negative value would shift Y axis stubs downward.``

stubomit list

  Used to supress certain indiviual stubs. This may be useful when stubs are given with data and certain ones are too close together or should be omitted for some other reason.`` For a more automatic stub supression, such as for log axes, see `stubcull`.`` list is a space-delimited list of one or more strings. Each may include wild card characters * and ?. Any stubs matching any members of the list are suppressed (however the tic is not suppressed).``
  Example: `stubomit: 0.5 3.5`
  Another example that uses stubomit: lineplot3

stubcull `yes` | h

  If specified, stubs are suppressed when too close to the adjacent stub.`` This is useful with log axes to prevent "piling up" of stubs in the upper values.`` If `yes`, a default minimum separation distance (0.1 inches) is used; you can also specify a minimum separation distance h if desired. New in version 1.40.

ticlen len1 [len2]

  Length of tics in absolute units . len1 is the distance that tics will be drawn from the axis line leftward / downward and len2 (optional) is the distance that tics will be drawn from the axis line rightward / upward.`` The default is for tics to be drawn a short distance leftward / downward.`` Example: `ticlen: 0.1 0.05`
  Example: `ticlen: 0 0.05`

ticincrement n [units]

  When no stubs are being rendered, this attribute may be used to control tic placement. Tics will be placed at every n units.`` The units modifier may be used when working with date or time scaling; it may be `days`, `hours`, etc. (see scaleunits ).``

minortics linedetails

  Details pertaining to the minor tic marks.`` Default is `none` which suppresses minor tic marks.`` Use `yes` to activate minor tics using the default detail specifications.``

minorticinc n [units]

  Minor tics to be drawn every n scaled units along the axis line.`` The units modifier may be used when working in date or time units; it may be `days`, `hours`, etc.`` (see scaleunits ).``

minorticlen len1 [len2]

  Length of tics in absolute units . len1 is the distance that minor tics will be drawn from the axis line leftward/downward, and len2 (optional) is the distance that tics will be drawn from the axis line rightward/upward.``

grid linedetails | none

  If specified, causes background grid lines to be drawn at stub or tic locations.`` If no stubs or tics are being rendered, the `ticincrement` attribute may still be used to control placement of grid lines.`` Extent of the lines may be controlled using `gridlineextent`.`` Shaded blocks rather than lines may be done using `gridblocks`.`` Default is "none".``
  Example: `grid: color=yellow width=1`

gridblocks color1 color2 | none

  If specified, causes a background grid made up of shaded blocks.`` Blocks are shaded alternately using color1 and color2.`` Extent of the blocks may be controlled using `gridlineextent`.`` New in version 1.40.``
  Example: `gridblocks: gray(0.9) white`

gridlineextent minlocval maxlocval

  Allows explicit specification of where grid lines or shaded blocks begin and end. Normally grid lines or blocks are drawn from the minima to the maxima.`` For example if grid lines are being rendered along with a Y axis, this attribute may be used to control where the lines begin and end in X.`` Commonly used to extend grid structure into axis stubs area as an eye guide.`` New in version 1.40.``
  Example: `gridlineextent: min-1.5 max`

gridskip `min` | `max` | `minmax`

  Grid lines can sometimes interfere with a perpendicular axis line rendered earlier. Use this option to suppress the grid at the minima, maxima, or both.``

autoyears `yy` | `'yy` | `yyyy`

  This attribute may be used when doing incremental stubs by month, in order to add the year below the first month and then every January thereafter. It will be located just below the months.`` `yy` gives a two-digit year such as `99`; `'yy` gives a two-digit year such as `'99`; `yyyy` gives a four-digit year.``
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` September 12, 2001.