Search


Ploticus > Scripts >

proc axis (xaxis or yaxis)

proc xaxis generates an X axis. proc yaxis generates a Y axis. Both procs use the same attributes and underlying code, and operate in the same general way.

A typical axis includes a line, some number of regularly placed short line marks called tics and some stubs (incremental numeric, or text) which populate the axis. The axis also can have a descriptive text label nearby, often describing the axis units. Grid lines or shaded blocks may also be generated.

proc xaxis and proc yaxis may be invoked directly, and may be invoked more than once for a given plotting area to render multiple or overlaid axes. Or, axis attributes may be specified from within proc areadef using xaxis. or yaxis. prefixes on the attribute names.

See also the gallery scaling and axis examples.

Attributes

There are no mandatory attributes. An axis can be generated with any combination of stubs, tics, and/or axis line. To generate a basic numeric axis using an automatically determined increment, use stubs: inc

Stubs

Stubs are what we call the incremental numbers or text tags that populate an axis. The stubs attribute controls the contents of the stubs, and there are several mode variants described below. Use one of the following:

stubs: incremental     [h]     [units]

Generate incremental stubs for numeric, date or time data. If neither h or units are specified (or h is 0) reasonable default behavior will occur (same as datematic for date or time data - see below). Otherwise a stub will be generated and placed at every h units. units is optional for plain numeric data; otherwise it is used as shown in the examples below.
Some examples:
stubs: inc ...reasonable default behavior
stubs: inc 10 ...one stub every 10
stubs: inc 10 ...one stub every 5000
stubs: inc 1 1000 ...one stub every 1000, stubs expressed in # of thousands
stubs: inc 1 0.01 ...one stub every 0.01, stubs expressed in # of hundredths
stubs: inc 1 day ...one stub per day (date or datetime scaletype)
stubs: inc 1 month ...one stub per month (date)
stubs: inc 3 months ...one stub every three months (date)
stubs: inc 1 year ...one stub every year (date)
stubs: inc 1 hour ...one stub per hour (time or datetime)
stubs: inc 10 minutes ...one stub every 10 minutes (time or datetime)
See scaleunits for more info on units.

stubs: datematic

May be used with date, datetime, and time scaletypes. Stub increment and stub format are automatically set to reasonable defaults. Minor tics, autoyear, automonth, and autoday are also sometimes activated as appropriate. If you wish to override any of the automatic settings you can do so by specifying any desired attributes after this one. Datematic is new in version 2.31. Similar autorange functionality (nearest=datematic) is also available and is recommended.
Here's an example where minor tics are suppressed as an override:

  stubs: datematic
  minortics: none

Here's another example where automonths is turned off as an override:

  stubs: datematic
  automonths: no

stubs: usecategories

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

stubs text     multi-line text

Indicates that subsequent 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.

Security concern: user-supplied values (such as CGI user variables) should not be used to build the filename, unless proper measures are taken to detect and remove the ../ construct (used as a hack to see higher levels of the file system).

Example: stubs: file /home/myplots/stubs2

Note that an alternative way to accomplish this is:

   stubs: text
  #include  filename

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. No embedded whitespace in the datafields= construct.

stubs: minmaxonly

stubs: minonly

stubs: maxonly

Display stubs / tics at the axis minima and/or maxima only. Versions 2.31+

stubs: none

Don't display any stubs (presumably you only want tics , a grid, or an axis label). An alternative method that gives you more flexibility is to use one of the above stubs options, along with stubhide: yes ; then you can use all the available stub-related options to control placement of tics.

Irregularly placed stubs

selflocatingstubs (see stubs, above)

This attribute uses the same syntax as stubs (above). However, this attribute allows stubs to be 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

Stub formatting

stubformat     format | autoround

This attribute controls the presentation format of numeric, date, time, or datetime stubs. The scaleunits page gives an overview of available scale types and has links to the respective types and available display formats. This attribute applies only to incremental stubs that ploticus generates, not to stubs supplied as text or from a file.

For numeric stubs, format is a printf-spec (default is %g) or autoround. autoround causes values to be rounded with the precision being determined by the number's magnitude. You can also use autoround1, autoround2, etc. to increase the precision. (To add thousands separators or use European decimal notation, see proc settings.) autoround functionality works with numeric data only, not dates or times.

Example 1: stubformat: %5.3f
This would produce numeric stubs like this 72.350, 72.355, 72.360, etc.

Example 2: stubformat: %7.0f
This would produce numeric stubs like this 500000, 1000000, 1500000, etc.

For other scale types such as date, time, and datetime, any valid display format may be specified (see the dates page and the times page for available display formats). If you're using stubs: datematic then a stubformat will be automatically selected (but you can specify a stubformat as an override). Otherwise the fallback default is the current date/time notation.

Example 3 (dates): stubformat: MMMdd

Example 4 (times): stubformat: hhA

Example 5 (datetime): stubformat: MMMdd.hhA

Controlling where stubs begin and end

stubround     h | useinc | nearestspec

This attribute (2.33+) is useful where axis min and max are at exact "nonround" locations, but the stubs are to be at round locations. For example for a certain application the Y axis must range from 38.4 to 49.2 but stubs are to appear at whole number locations.

For numeric axes specify h as a number; this places stubs at even multiples of h. Or, for numeric axes you can specify useinc which will use the current stub increment value.

For date, time, and datetime axes specify nearestspec (allowable values for autorange nearest= as listed here. For example, stubround: 3hour would place stubs at 3, 6, 9, 12 o'clock, etc.

stubround is generally not used with the datematic feature, since datematic sets the axis min and max to nice even locations. stubround may be combined with stubrange below (it is applied after stubrange).

stubrange     min [max]

For situations where the default results aren't ideal, this attribute can be used to specify where stubs begin (and optionally, end). min is a value in scaled units where tics and stubs should start. If max is specified, it should be a value in scaled units where tics and stubs should stop.

Example: stubrange: 5 95

Example: suppose you have data in Y ranging from 38.4 to 48.5, and it is important to your application for the plotting area Y range to be 38.4 to 48.5 exactly, but you want stubs only on whole numbers. Here's a script that does this.

Omitting certain stubs

stubevery     n

Render every nth stub (beginning with the first) and omit the rest.

stubcull     yes | h

If specified, stubs are suppressed when too close (graphically) 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.

stubomit     list

Used to supress certain indiviual stubs, or all stubs. This will suppress the stub and the tic. 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). To suppress all stubs use this: stubomit: *
Example: stubomit: 0.5 3.5
A gallery example that uses stubomit: lineplot3

stubhide     yes | no

Hide all stubs, but render the accompanying tics. Allows you to have more control over tic placement (using any of the available stub-related options) when doing only tics. (new in version 2.21)

stubmininc f

For numeric stubs where the increment is automatically determined, this may be used to ensure that the increment will be at least f. One use of this is with integer data to prevent stubs from appearing in fractional increments.

nolimit yes|no

If yes, the internal stub drawing "circuit breaker" (preventing infinite loops in the stub rendering code) is disabled, for certain special situations where it is a hinderance.

Controlling stub positioning & appearance details

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

stubdetails     textdetails

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

stubreverse     yes | no

If yes, reverses the placement of text and category stubs so that the first stub is placed at the maxima and the last at the minima. Has no effect on incremental stubs which must always move from low to high. The default is no, except when text stubs are being placed along the Y axis where this defaults to yes. Example: stubreverse: yes

stubvert     yes | no | ndegrees

Default is no, to render stubs using horizontal text. If yes, X axis stubs are rendered using 90 ° (bottom up) vertical text (often useful with longer X axis stubs, and supported by all output types except X11). If your build supports an output type that can do it (such as SVG, postscript, or PNG/GIF/JPG w/Freetype2) you can supply an integer ndegrees such as 270 to get 270 ° (top down) vertical text, or 320 to get slanted X axis stubs (ndegrees is new in version 2.40). Note: non-Freetype2 PNG/GIF/JPG builds can only do horizontal and 90 degree text.
Example: stubvert: yes
Example: stubvert: 270

Adjusting stub content

stublen     n

If specified, stubs will be truncated at n characters. Truncated stubs will have two trailing dots (..) to indicate that truncation has taken place.
Example: stublen: 8

signreverse     yes | no

If yes, presents incremental numeric stubs with sign reversed. May be useful in creating an axis that moves from high values to low values. Default is no This attribute is useful only when incremental numeric stubs are being generated. Example:
stubs: inc
signreverse: yes

stubmult     f

For numeric stubs, this may be used to multiply stub values by f before displaying.

firststub     text

Set the contents of the first stub to text (for blank use ""). The "first stub" is the one nearest to the axis minima.

laststub     text

Set the contents of the last stub to text (for blank use ""). The "last stub" must lie on (or very near to) the axis maxima.
Example: laststub: and so on..
Example: laststub: ""

stubsubpat     pattern
stubsubnew     newtext

Any stub matching pattern will be changed to newtext (for blank use ""). Both attributes must be supplied. pattern may contain wild card characters * and ?. Example:
stubsubpat: *xyz
stubsubnew: ""

stubexp     yes | exp-1 | no

Displays incremental numeric stubs in real space when data are in log-transformed space. If yes, numeric stubs are rewritten as exp(x). If exp-1, numeric stubs are rewritten as exp(x)-1, (inverse of log+1). Default is no. This attribute is useful only when incremental numeric stubs are being generated. stubformat: autoround is often useful when this attribute is being used.
Example: stubexp: exp-1

Date-related convenience features

These attributes are superseded by the datematic feature (above), but remain for the occasional situations where they may be useful individually.

autoyears     yes | no | yy | 'yy | yyyy

With date stubs, automatically add the year below the first stub and then at every year transition thereafter. 'yy gives a two-digit year such as '99 (this is the default). yy gives a two-digit year such as 99. yyyy gives a four-digit year.

automonths     yes | no | Mmm | MMM | Mmmyy (etc.)

With date stubs, automatically add the month below the first stub and then at every month transition thereafter. Mmm gives a month abbreviation eg. Feb (this is the default). MMM gives an all-caps month abbreviation eg. FEB. Mmmyy gives a representation eg. Feb02. Other legitimate month and month/year constructs may also be used.

autodays     yes | no | Mmmdd | mm/dd (etc.)

With datetime stubs, automatically add the day below the first stub and then at every day transition thereafter. Mmmdd gives a month/day representation eg. Feb23 (this is the default). mm/dd gives a month/day representation eg. 02/23. Other legitimate day and month/day constructs may also be used.

Overall axis position

location     locvalue

May be used to specify the position of the axis if the default is not suitable, or when rendering multiple axes. 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.
Note: when this attribute is specified from within proc areadef, only absolute locations may be used, because the plotting area is not in effect yet at time of code interpretation.

Example: location: 105(s)

The axis line

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. Values are always in scaled (data) units. If only one value is given it is taken to be the minimum.
Example: axislinerange: 5 95

arrow     yes | no

If yes, an arrowhead will be rendered at the axis maxima. Version 2.31+

arrowheadsize     h

Size of the arrowhead in absolute units. Default is 0.15"

The axis label

An axis label is a single text label rendered near the axis, desribing the units used, or other description. The Y axis label is rendered vertically on devices that can do so.

label     text

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

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

Tics

"Tics" are what we call the short line segments that are part of the scale along an axis line.

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

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.

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 lines and shaded blocks

grid     linedetails     | yes | none

If specified, causes background grid lines to be drawn at stub locations (if no stubs are being rendered, the ticincrement attribute can be used to control placement of grid lines, whether or not tics are being generated). Grid lines are never associated with minor tics. The extent of the lines may be controlled using gridlineextent. Shaded blocks rather than lines may be done using gridblocks. Specifying yes gives a grid made up of a default line type. Default is none, for no grid at all.
Example: grid: color=yellow width=1

gridblocks     color1 color2 | none

If specified, causes a background grid made up of shaded zones. Zones are shaded alternately using color1 and color2. Extent of the may be controlled using gridlineextent.
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. Note: if shading obliterates stubs.. a workaround is to first render shading, then render stubs in a separate proc axis invocation.
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.

Clickmaps and mouseover

clickmap     grid | xygrid

If a clickmap is being generated, this attribute allows the plotting area to be mapped as a grid. Specify grid to get a clickmap grid associated with the one axis currently being rendered. Specify xygrid to get a 2-D clickmap grid on both axes together. proc areadef's clickmapurl attribute must also be specified. See also the clickmap page for more details and examples.

Example: clickmap: grid

clickmapextent     minlocval [maxlocval]

If a clickmap is being generated, and the plotting area is being mapped as a grid, normally the regions end at the plotting area boundary. However, this attribute may be used to extend the region, to include stubs, for example.

Example: clickmapextent: min-0.5

clickmapvalformat     stubformat

If a clickmap is being generated, and the plotting area is being mapped as a grid, this attribute allows control over the format of the values to be sustituted into the URL template. Most often useful for special units such as dates. See the clickmap page for more details and examples.

Example: clickmapvalformat: MMMyy

labelurl     url

If generating an HTML clickmap, this specifies a url that will be accessed when the user clicks on the axis label.
Example: labelurl: http://abc.com/docs/explanation.html

labelinfo     info

If generating a client-side clickmap, this specifies text info that will appear as a pop-up when the user moves the mouse over the axis label.

Variables that are set by proc axis

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