.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: proc axis (xaxis or yaxis)</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>proc axis (xaxis or yaxis)</h2></td>
  <td align=right>
  <small>
  <a href="../doc/Welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_axis_(xaxis_or_yaxis) PL "16-MAY-2003   PL ploticus.sourceforge.net"

.ig >>
<center><img src="../gallery/sa0.gif"></center>
.>>

.SH DESCRIPTION
.LP
\fBproc xaxis \fR generates an X axis.
.br
\fBproc yaxis \fR generates a Y axis.
.LP
Both procs use the same attributes and operate in the same way.
.LP
A typical axis includes a line, some number of regularly placed
short line marks called \fBtics\fR and some 
\fBstubs\fR
(incremental numeric, or text)
which populate the axis.
The axis also can have a descriptive text \fBlabel\fR nearby, often describing the
axis units.  Grid lines or shaded blocks may also be generated.
.LP
\fBproc xaxis\fR and \fBproc yaxis\fR may be invoked directly.
Alternatively, axis attributes may be specified 
within a \fBproc areadef\fR block using \fCxaxis.\fR or \fCyaxis.\fR prefixes 
on the attribute names (allowing the entire areadef with axes specifications to be cloned).

.ig >>
<br><br><br>
.>>

.SH FEATURES
\fBproc xaxis/yaxis\fR 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.
.ig >>
<a href="clickmap.html">
.>>
\0Clickmap and mouseover text labels
.ig >>
</a>
.>>
can also be associated with regions tied to an axis.

.ig >>
<br><br><br>
.>>

.SH EXAMPLES
See the Gallery Scaling and Axes examples
.ig >>
<a href="../gallery/gall.sa.html"><img src="../gallery/btn/here.gif"></a>
.>>

.ig >>
<br><br><br>
.>>

.SH PREREQUISITES
A plotting area must be defined using \fBproc areadef\fR.
If stubs are to be taken from data fields, data must have already
been accessed or defined using \fBproc getdata\fR.

.ig >>
<br><br><br>
.>>

.SH 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.

.ig >>
<br><br><br>
.>>

.SH VARIABLES THAT ARE SET
XINC or YINC will be set to hold the axis increment value.


.ig >>
<br><br><br>
.>>

.SH MANDATORY ATTRIBUTES
None.  Default behavior is automatic incremental stubs 
and small outward tics at every unit.

.ig >>
<br><br><br>
.>>


.SH ATTRIBUTES

.LP
\fBlocation\fR 
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0locvalue
.ig >>
</a>
.>>
.IP \0
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 \fC(s)\fR
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.
.br
\fBNote:\fR 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.
.IP
Example: \fClocation: 105(s)\fR


.ig >>
<br><br><br>
.>>
.SH Specifying content of stubs
Stubs are what we call the incremental numbers or text tags that populate an axis.
The \fBstubs\fR attribute controls the contents of 
the stubs, and there are several mode variants described below:

.LP
\fBstubs  incremental [\fIh\fR] [\fIunits\fR]
.IP \0
Generate incremental stubs for numeric or date or time data
(\fBincremental\fR may be abbreviated as \fBinc\fR).
A stub will be generated and placed at every \fIh\fR units.
\fIh\fR and \fIunits\fR may both be omitted for numeric data in which case a reasonable
default increment will be used (an \fIh\fR value of 0 has the same effect).
.br
Example: \fCstubs: incremental 10\fR  ..would place stubs at
every 10 units.
.br
\fIunits\fR allows flexibility with stub increments.
The following table illustrates some possibilities:
.ig >>
<a name=stubunits></a>
.>>
.nf
.ft C
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
.ft R
.fi
See
.ig >>
<a href="scaleunits.html">
.>>
\0scaleunits
.ig >>
</a>
.>>
for more info on \fIunits\fR.

.LP
\fBstubs  text\fR  
.ig >>
<a href="attributetypes.html#text">
.>>
\0multi-line text
.ig >>
</a>
.>>
.IP \0
Indicates that the following lines of the script contain 
literal stub text, with one line per stub, and 
terminating with a blank line.
.br
Example:
.nf
.ft C
stubs:  text
	New York
	Atlanta
	Detroit
	Baltimore
	
.fi
.ft R

.LP
\fBstubs  list \fR
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
Same as \fCstubs  text\fR except that all stubs are given on one
line, with individual stubs separated by \fC\\n\fR.
.br
Example: \fCstubs: list New York\\nDetroit\\nBaltimore\fR

.LP
\fBstubs  file  \fIfilename\fR 
.IP \0
Same as \fCtext\fR except that content is to be 
taken from \fIfilename\fR.
.br
Example: \fCstubs: /home/myplots/stubs2\fR

.LP
\fBstubs  datafields=\fR
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield1
.ig >>
</a>
.>>

.ig >>
<a href="attributetypes.html#dfield">
.>>
\0[,dfield2]
.ig >>
</a>
.>>
.IP \0
Stub content is to be taken from one or two data fields.
.br
Example: \fCstubs: datafields=1,2\fR  .. would use
the first and second data field for stubs.


.LP
\fBstubs  usecategories\fR 
.IP \0
If the scaletype for this axis is \fCcategories\fR, this
indicates that the defined category names should be
used as the stubs.  Implies self-locating.

.LP
\fBstubs  none\fR
.IP \0
Don't display any stubs.
Example: \fCstubs: none\fR


.LP
\fBselflocatingstubs\fR  (see \fCstubs\fR, above)
.IP \0
This attribute uses the same syntax as \fCstubs\fR (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).
.br
For the \fCtext\fR, \fClist\fR and \fCfile\fR 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.
.br
For the \fCdatafields\fR mode, the first field \fIa\fR is used for placement
and the second field \fIb\fR is used for content.  To display the placement 
value, specify the same field# twice.
.br
Examples of selflocating stubs:
.br
stubs from datafields: 
.ig >>
<a href="../gallery/lineplot3.htm">
.>>
\0lineplot3
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>

.SH Other stub control attributes 

.LP
\fBstubrange\fR \fImin\fR [\fImax\fR]
.IP \0
Range (in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0scaled units
.ig >>
</a>
.>>
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: \fCstubrange: 5 95\fR


.LP
\fBstubformat\fR  \fIformat\fR
.IP \0
Controls the presentation format of numeric, date, time, or datetime stubs.  
.IP \0
For numeric stubs, \fIformat\fR is a 
.ig >>
<a href="attributetypes.html#printfspec">
.>>
\0printf-spec
.ig >>
</a>
.>>
(default is \fC%g\fR) or \fCautoround\fR.
\fCautoround\fR causes values to be rounded with the precision being
determined by the number's magnitude.  You can also use \fCautoround1\fR,
\fCautoround2\fR, etc. to increase the precision.
(To add thousands separators or use European decimal notation, see
.ig >>
<a href="settings.html">
.>>
\0proc settings.)
.ig >>
</a>
.>>
.br
Example 1: \fCstubformat: %5.3f\fR 
.br
This would produce numeric stubs like this 72.350, 72.355, 72.360, etc.
.br
Example 2: \fCstubformat: %7.0f\fR 
.br
This would produce numeric stubs like this 500000, 1000000, 1500000, etc.
.IP \0
For other scale types such as 
.ig >>
<a href="dates.html">
.>>
\0date
.ig >>
</a>
.>>
,
.ig >>
<a href="times.html">
.>>
\0time
.ig >>
</a>
.>>
,
and \fBdatetime\fR, any valid display format may be specified.
If \fCstubformat\fR is
not specified when date/time scaling is being done,
the current notation, or one similar to it, is used.
.br
Example 3 (dates): \fCstubformat: MMMdd\fR
.br
Example 4 (times): \fCstubformat: hhA\fR
.br
Example 5 (datetime): \fCstubformat: MMMdd.hhA\fR

.LP
\fBstubevery\fR  \fIn\fR
.IP \0
When doing stubs from a data field or categories, this will
cause every \fIn\fRth 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.

.LP
\fBstubdetails\fR 
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details pertaining to stub text rendering.
.br
Example: \fCstubdetails: size=7\fR

.LP
\fBstubcull\fR  \fCyes\fR | \fIh\fR
.IP \0
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 \fCyes\fR, a default minimum separation distance (0.1 inches) is used; you can also
specify a minimum separation distance \fIh\fR if desired.  

.LP
\fBstubomit\fR \fIlist\fR
.IP \0
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 \fCstubcull\fR.
\fIlist\fR 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: \fCstubomit: *\fR
.br
Example: \fCstubomit: 0.5 3.5\fR
.br
Another example that uses stubomit: 
.ig >>
<a href="../gallery/lineplot3.htm">
.>>
\0lineplot3
.ig >>
</a>
.>>

.LP
\fBstubreverse\fR \fIyes|no\fR
.IP \0
If \fCyes\fR, 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 \fCno\fR, 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 \fCyes\fR,
otherwise the default is \fCno\fR.
Example: \fCstubreverse: yes\fR

.LP
\fBstubvert\fR \fIyes|no\fR
.IP \0
If \fCyes\fR, renders X axis stubs using vertical text.  This is useful if
X axis stubs are too long to fit horizontally.
Example: \fCstubvert: yes\fR

.LP
\fBstubslide\fR  
.ig >>
<a href="attributetypes.html#lenvalue">
.>>
\0lenvalue
.ig >>
</a>
.>>
.IP \0
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.
.br
Example: \fCstubslide: 0.5\fR
.br
For another example see 
.ig >>
<a href="../gallery/axis9b.htm">
.>>
\0axis9b
.ig >>
</a>
.>>

.LP
\fBsignreverse\fR \fIyes|no\fR
.IP \0
If \fCyes\fR, presents numeric stubs with sign reversed.
May be useful in creating an axis that moves from high values
to low values.  


.LP
\fBstubexp\fR \fCyes|exp-1|no\fR
.IP \0
Default is \fCno\fR.
Displays axis in real space when data are in log-transformed space.
If \fCyes\fR, numeric stubs are rewritten as exp(x). 
If \fCexp-1\fR, numeric stubs are rewritten as exp(x)-1, (inverse of log+1).
.br
Hint: use \fCstubformat: autoround\fR 
.br
Example: \fCstubexp: exp-1\fR

.LP
\fBautoyears\fR  \fCyy\fR  |  \fC'yy\fR  |  \fCyyyy\fR
.IP \0
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.
\fCyy\fR gives a two-digit year such as \fC99\fR;
\fC'yy\fR gives a two-digit year such as \fC'99\fR;
\fCyyyy\fR gives a four-digit year.

.LP
\fBstublen\fR  \fIn\fR
.IP
If specified, stubs will be truncated at \fIn\fR characters.
Truncated stubs will have two trailing dots (\fC..\fR) to indicate
that truncation has taken place.
.br
Example: \fCstublen:  8\fR


.ig >>
<br><br><br>
.>>

.SH Pertaining to the axis line

.LP
\fBaxisline\fR 
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
Details pertaining to the axis line.  
Use \fCnone\fR to completely suppress the axis line.
.br
Example: \fCaxisline: width=1.2 color=green\fR

.LP
\fBaxislinerange\fR \fImin\fR [\fImax\fR]
.IP \0
May be used to control the range of the axis line.
If only one value is given it is taken to be the minimum.
.br
Example: \fCaxislinerange: 5 95\fR


.ig >>
<br><br><br>
.>>
.SH Pertaining to the axis label

.LP
\fBlabel\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
A text label that will be rendered near the axis, used to describe
what is being plotted.  
.br
Example: \fClabel: Yearly Income\fR


.LP
\fBlabeldetails\fR 
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details for rendering the label. Example: \fClabeldetails: size=13 style=I\fR

.LP
\fBlabeldistance\fR \fIn\fR
.IP \0
Distance of the label below / left of the axis line.
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0Absolute units.
.ig >>
</a>
.>>
This could also be done via \fClabeldetails: adjust=\fR.
.br
Example: \fClabeldistance: 0.6\fR

.ig >>
<br><br><br>
.>>
.SH Pertaining to tics
.LP
"Tics" are what we call the short line segments that are part of the
scale along an axis line.

.LP
\fBtics\fR  \fCyes\fR | \fCnone\fR | 
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
If anything other than \fCnone\fR 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 \fCstubs: none\fR;
they can be controlled using \fCticincrement\fR.
.br
Example: \fCtics: yes\fR

.LP
\fBticslide\fR  
.ig >>
<a href="attributetypes.html#lenvalue">
.>>
\0lenvalue
.ig >>
</a>
.>>
.IP \0
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.

.LP
\fBticlen\fR \fIlen1\fR [\fIlen2\fR]
.IP \0
Length of tics in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units.
.ig >>
</a>
.>>
\fIlen1\fR is the distance that
tics will be drawn from the axis line leftward / downward
and \fIlen2\fR (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: \fCticlen: 0.1 0.05\fR
.br
Example: \fCticlen: 0 0.05\fR

.LP
\fBticincrement\fR \fIn\fR [\fIunits\fR]
.IP \0
When no stubs are being rendered, this attribute may be used to
control tic placement.  Tics will be placed at every \fIn\fR units.
The \fIunits\fR modifier may be used when working with date or
time scaling; it may be \fCdays\fR, \fChours\fR, etc. 
(see
.ig >>
<a href="scaleunits.html">
.>>
\0scaleunits).
.ig >>
</a>
.>>

.LP
\fBminortics\fR 
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
Details pertaining to the minor tic marks.
Default is \fCnone\fR which suppresses minor tic marks.
Use \fCyes\fR to activate minor tics using the default detail
specifications.

.LP
\fBminorticinc\fR \fIn\fR [\fIunits\fR]
.IP \0
Minor tics to be drawn every \fIn\fR scaled units along the axis line.
The \fIunits\fR modifier may be used when working in date or time units;
it may be \fCdays\fR, \fChours\fR, etc.
(see
.ig >>
<a href="scaleunits.html">
.>>
\0scaleunits).
.ig >>
</a>
.>>

.LP
\fBminorticlen\fR \fIlen1\fR [\fIlen2\fR]
.IP \0
Length of tics in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units.
.ig >>
</a>
.>>
\fIlen1\fR is the distance that
minor tics will be drawn from the axis line leftward/downward,
and \fIlen2\fR (optional) is the distance that
tics will be drawn from the axis line rightward/upward.

.ig >>
<br><br><br>
.>>
.SH Grid lines and shaded blocks
.LP
\fBgrid\fR 
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
| none
.IP \0
If specified, causes background grid lines to be drawn at stub or tic locations.
If no stubs or tics are being rendered, the \fCticincrement\fR attribute
may still be used to control placement of grid lines.
Extent of the lines may be controlled using \fCgridlineextent\fR.
Shaded blocks rather than lines may be done using \fCgridblocks\fR.
Default is "none".
.br
Example: \fCgrid: color=yellow width=1\fR

.LP
\fBgridblocks\fR
.ig >>
<a href="color.html">
.>>
\0color1  color2
.ig >>
</a>
.>>
 | none
.IP \0
If specified, causes a background grid made up of shaded blocks.
Blocks are shaded alternately using \fIcolor1\fR and \fIcolor2\fR.
Extent of the blocks may be controlled using \fCgridlineextent\fR.
.br
Example: \fCgridblocks:  gray(0.9) white

.LP
\fBgridlineextent\fR 
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0minlocval  [maxlocval]
.ig >>
</a>
.>>
.IP \0
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.
.br
Example: \fCgridlineextent: min-1.5  max\fR

.LP
\fBgridskip\fR  \fCmin\fR | \fCmax\fR | \fCminmax\fR
.IP \0
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.

.ig >>
<br><br><br>
.>>
.SH Pertaining to clickable image maps

.LP
\fBclickmap\fR  \fCgrid | xygrid\fR
.IP \0
If a
.ig >>
<a href="clickmap.html">
.>>
\0clickmap
.ig >>
</a>
.>>
is being generated, 
this attribute allows the plotting area to be mapped as a grid.
Specify \fCgrid\fR for a 1-D grid, or \fCxygrid\fR for a 2-D grid.  
.ig >>
<a href="areadef.html">
.>>
\0proc areadef
.ig >>
</a>
.>>
\fCclickmapurl\fR attribute must also be specified.
See the 
.ig >>
<a href="clickmap.html">
.>>
\0clickmap page
.ig >>
</a>
.>>
for more details and examples.
.IP \0
Example: \fCclickmap: grid\fR

.LP
\fBclickmapextent\fR 
.IP \0
If a
.ig >>
<a href="clickmap.html">
.>>
\0clickmap
.ig >>
</a>
.>>
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.
.IP \0
Example: \fCclickmapextent: min-0.5 \fR

.LP
\fBclickmapvalformat\fR  \fIstubformat\fR
.IP \0
If a
.ig >>
<a href="clickmap.html">
.>>
\0clickmap
.ig >>
</a>
.>>
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 
.ig >>
<a href="clickmap.html">
.>>
\0clickmap page
.ig >>
</a>
.>>
for more details and examples.
.IP \0
Example: \fCclickmapvalformat: MMMyy\fR


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/Welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
.>>
