|
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 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.
Alternatively, axis attributes may be specified
within a proc areadef block using xaxis. or yaxis. prefixes
on the attribute names (allowing the entire areadef with axes specifications to be cloned).
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.
Clickmap and mouseover text labels
can also be associated with regions tied to an axis.
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
location
locvalue
-
-
This attribute may be used to control the position of the axis, for when the default location
is not suitable.
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.
Note: when this attribute is used 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)
Specifying content of 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:
stubs incremental [h] [units]
-
-
Generate incremental stubs for numeric or date or time data
(incremental may be abbreviated as inc).
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
datetime 1 hour one stub per hour
datetime 10 minutes one stub every 10 minutes
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)
-
-
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
Other stub control attributes
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 format
-
-
Controls the presentation format of numeric, date, time, or datetime stubs.
-
-
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.)
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.
If stubformat is
not specified when date/time scaling is being done,
the current notation, or one similar to it, is used.
Example 3 (dates): stubformat: MMMdd
Example 4 (times): stubformat: hhA
Example 5 (datetime): stubformat: MMMdd.hhA
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.
stubdetails
textdetails
-
-
Details pertaining to stub text rendering.
Example: stubdetails: size=7
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.
stubomit list
-
-
Used to supress certain indiviual stubs, or all 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).
To suppress all stubs use this: stubomit: *
Example: stubomit: 0.5 3.5
Another example that uses stubomit:
lineplot3
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
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
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.
stubexp yes|exp-1|no
-
-
Default is no.
Displays axis 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).
Hint: use stubformat: autoround
Example: stubexp: exp-1
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.
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
Pertaining to 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.
If only one value is given it is taken to be the minimum.
Example: axislinerange: 5 95
Pertaining to the axis label
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
Pertaining to 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
| 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.
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.
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.
Pertaining to clickable image maps
clickmap grid | xygrid
-
-
If a
clickmap
is being generated,
this attribute allows the plotting area to be mapped as a grid.
Specify grid for a 1-D grid, or xygrid for a 2-D grid.
proc areadef
clickmapurl attribute must also be specified.
See the
clickmap page
for more details and examples.
-
-
Example: clickmap: grid
clickmapextent
-
-
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
|
 data display engine
Copyright Steve Grubb
|