.TH AREADEF PL "Ploticus data display engine"
 
.ig >>
<center>
<b>Ploticus data display engine</b> <small><a href="Copyright.html">Copyright Steve Grubb</a><br></small><br>
<a href="../doc/Welcome.html"><img src="../gallery/btn/welcome.gif"></a>
<a href="../gallery/index.html"><img src="../gallery/btn/gallery.gif"></a>
<a href="../doc/Contents.html"><img src="../gallery/btn/handbook.gif"></a>
<h1><br><br>Proc Areadef</h1>
</center>
.>>

.SH NAME
proc areadef
.LP
.ig >>
<center>
<a href="../gallery/sa2a.htm">sa2a<br><img src="../gallery/sa2a.gif"></a>
</center>
<p>
.>>
.PSPIC ../gallery/sa2a.eps

.SH DESCRIPTION
\fBproc areadef\fR is used to define the size, location, and scaling in X and Y
of the rectangle within which a subsequent plot will be rendered.
This rectangle is referred to as the plotting area.
\fBproc areadef\fR may be used any number of times within the same script
to do multiple plots per page, to produce multiple page results, or to 
overlay different scales or units on the same plot.

.SH FEATURES
Various scaling types, including linear, log, date, and time are available
for X and Y.
Automatic scaling based on data content may be done using
\fCxautorange\fR and \fCyautorange\fR.
Axes may be specified within \fBproc areadef\fR
or individually later using \fBproc xaxis\fR or \fBproc yaxis\fR.  
If specified here, the various \fBproc axis\fR attributes should be
prefixed with \fCxaxis.\fR or \fCyaxis.\fR.

.SH EXAMPLES
.ig >>
<a href="../gallery/sa1.htm">sa1.p<br><img src="../gallery/sa1.gif"></a>
.>>
.br
Almost all of the examples in the gallery use 
proc areadef in various ways.

.SH PREREQUISITES
None.

.SH MODES
The size and location of the plotting area
on a page (the plotting area) may be specified in one 
of these three ways: 
.IP 1.
by name using the \fCareaname\fR attribute;
.IP 2.
by specifying a rectangle (two points) using the \fCrectangle\fR attribute;
.IP 3.
by specifying plotting area size using
the \fCbox\fR attribute and the location using the \fClocation\fR attribute.

.SH VARIABLES THAT ARE SET
Areadef will set the variables \fBAREALEFT\fR, \fBAREARIGHT\fR, 
\fBAREABOTTOM\fR, and \fBAREATOP\fR
to hold the locations of the plot area edges in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
absolute units
.ig >>
</a>
.>>
 . 

.SH MANDATORY ATTRIBUTES
The range in X and Y must be specified, either using
\fCxrange\fR / \fCyrange\fR, or
\fCxautorange\fR / \fCyautorange\fR.
Exception: when categories are being used for an axis, range does not 
need to be specified.
.LP
If nothing else is specified,
default behaviour is for the \fCstandard\fR
plotting area to be used, with linear scaling in x and y.


.SH ATTRIBUTES

.LP
\fBareaname\fR  \fIname\fR 
.IP
Allows a plotting area to be defined by selecting a 
predefined rectangle by name. 
These are most useful when generating plots on standard paper.
Example: \fCareaname: 2hi\fR
.br
Available names include:
.IP
.ta 1.5i
.nf
.ft C
Name    	Description
--------	------------------------------
standard	the default
square		a square area
whole   	as much of the page as possible
2hi, 2lo	for two plots on a page, one above the other
2left, 2right	for two plots on a page, side by side
3hi, 3mid, 3lo	for three plots on a page
4ne, 4nw, 4se, 4sw	for four plots on a page (ne = northeast)
slide   	works well with slides generation
map     	works well with maps
lifetab  	works well for life tables
.fi
.ft R

.LP
\fBrectangle\fR  \fIx1 y1 x2 y2\fR
.IP
Allows a plotting area to be defined by giving two points:
(x1,y1) is the lower left corner 
and (x2,y2) is the upper right corner 
(both are in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
absolute units
.ig >>
</a>
.>>
 . 
.br
Example: \fCrectangle: 1.4 4 7.4 8\fR

.LP
\fBbox\fR  \fIwidth height\fR 
.IP
Allows a plotting area to be defined by giving width and height in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
absolute units
.ig >>
</a>
.>>
 . 
A \fBlocation\fR attribute should also be given to
specify where to place the box.
Example: \fCbox: 1.4 4 6 4\fR

.LP
\fBlocation\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
Used with the \fBbox\fR attribute.  
Defines the location of the lower-left corner of the plotting area.


.LP
\fBxrange\fR  \fImin max\fR
.IP
Defines the plottable range in x.  \fImin\fR and \fImax\fR must both be given,
and must both be plottable values for the scaletype to be used.
(To set the range automatically based on a data field, use \fCxautorange\fR;
not used when \fCxscaletype\fR is \fCcategories\fR.)
If \fBlog\fR scaling is being used, 0.0 may not given as the minima
(but a very small value like 0.01 is ok).
.br
Example: if your data ranges in x between
1.5 and 23.5 you might use: \fCxrange: 0 24\fR

.LP
\fBxautorange\fR \fCdatafield=\fIdfield\fR [\fCnearest=\fIs\fR] [\fCmargin=\fIm\fR] [\fClowfix=\fIlowval\fR] [\fChifix=\fIhival\fR]
.IP
Scan the datafield \fIdfield\fR to automatically find minima and maxima.
(To set the range explicitly, use \fCxrange\fR.)
.IP
If \fCnearest=\fIs\fR is specified (and it almost always should be), 
range at both ends will be extended to the given boundary.  
\fIs\fR may be any numeric value, or one of these
words: \fCmonth quarter year hour\fR.
For example if \fIs\fR is \fC100\fR, and the data range
from 23 to 1162, the plot's range will be 0 to 1200.
If \fCnearest=\fIs\fR is not specified, the range will be the 
exact minima to the exact maxima (usually not what you want).
The following illustrates other available values for \fIs\fR:
.br
.nf
.ft C
 \fIs\fC       range min and max will be set to:
-------   ---------------------------------
10        the nearest multiple of 10
0.1       the nearest multiple of 0.1
month     the nearest month boundary (scaletype must be date)
quarter   the nearest quarter-year boundary (scaletype must be date)
year      the nearest year boundary (scaletype must be date)
hour      the nearest hour boundary (scaletype must be time)
.fi
.ft R
.IP
If \fCmargin=\fIm\fR is specified, \fIm\fR units will be added to the
maxima and also subtracted from the minima, before considering \fCnearest\fR.  
This may be used to guarantee margins at each end of the range.
.IP
If \fClowfix=\fIlowval\fR is specified, the minima will always be \fIlowval\fR.
This is useful when you want only the maxima to be automatically set based on data.
(Introduced in version 1.3)
.IP
Similarly, if \fChifix=\fIhival\fR is specified, the maxima will always be \fIhival\fR.
This is useful when you want only the minima to be automatically set based on data.
(Introduced in version 1.3)
.IP
Example: \fCxautorange: datafield=2 nearest=month margin=31\fR
.br
Gallery examples where \fCxautorange\fR is used:
.ig >>
<a href="../gallery/qual.htm">
.>>
qual
.ig >>
</a>
.>>
and
.ig >>
<a href="../gallery/hitcount.htm">
.>>
hitcount
.ig >>
</a>
.>>


.LP
\fByrange\fR  \fImin max\fR
.IP
Defines the plottable range in y.   Same as \fCxrange\fR above.
.br
Example: if your data ranges in y between
4 and 78.3 you might use: \fCyrange: 0 100\fR

.LP
\fByautorange\fR \fCdatafield=\fIdfield\fR [\fCnearest=\fIs\fR]
.IP
Same as \fCxautorange\fR (above) but for Y.

.LP
\fBxscaletype\fR  \fItype\fR [ \fIformat\fR ]
.IP
Defines the type of scaling for the X axis.  Default is \fClinear\fR.
Other possible \fItype\fRs include: \fClinear\fR, \fClog\fR, \fCcategories\fR, 
\fCdate\fR, \fCtime\fR.  The \fIformat\fR parameter may be given when
xscaletype is \fCdate\fR or \fCtime\fR to set the default notation.
.br
If \fCcategories\fR is used, the \fCxcategories\fR attribute must also be specified.
.br
Scale types are not remembered from any previous \fBproc defineunits\fR or 
\fBproc autoscale\fR invocations; they must be repeated here.
.br
See 
.ig >>
<a href="scaleunits.html">
.>>
scaleunits
.ig >>
</a>
.>>
for descriptions of the various scale types and units, and
.ig >>
<a href="../gallery/gall.sa.html">
.>>
the gallery
.ig >>
</a>
.>>
for examples.
.br
Example: \fCxscaletype: date yymm\fR
.br
Example: \fCxscaletype: categories\fR


.LP
\fByscaletype\fR  \fItype\fR  [ \fIformat\fR ]
.IP
Defines the type of scaling for the Y axis.  
Same syntax as \fCxscaletype\fR above.
Default is \fClinear\fR.


.LP
\fBareaname\fR  \fIname\fR 
.IP
Allows a plotting area to be defined by selecting a 
predefined rectangle by name. 
These are most useful when generating plots on standard paper.
Example: \fCareaname: 2hi\fR
.br
Available names include:
.IP
.ta 1.5i
.nf
.ft C
Name    	Description
--------	------------------------------
standard	the default
square		a square area
whole   	as much of the page as possible
2hi, 2lo	for two plots on a page, one above the other
2left, 2right	for two plots on a page, side by side
3hi, 3mid, 3lo	for three plots on a page
4ne, 4nw, 4se, 4sw	for four plots on a page (ne = northeast)
slide   	works well with slides generation
map     	works well with maps
lifetab  	works well for life tables
.fi
.ft R

.LP
\fBrectangle\fR  \fIx1 y1 x2 y2\fR
.IP
Allows a plotting area to be defined by giving two points:
(x1,y1) is the lower left corner 
and (x2,y2) is the upper right corner 
(both are in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
absolute units
.ig >>
</a>
.>>
 . 
.br
Example: \fCrectangle: 1.4 4 7.4 8\fR

.LP
\fBbox\fR  \fIwidth height\fR 
.IP
Allows a plotting area to be defined by giving width and height in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
absolute units
.ig >>
</a>
.>>
 . 
A \fBlocation\fR attribute should also be given to
specify where to place the box.
Example: \fCbox: 1.4 4 6 4\fR

.LP
\fBlocation\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
Used with the \fBbox\fR attribute.  
Defines the location of the lower-left corner of the plotting area.


.LP
\fBareacolor\fR 
.ig >>
<a href="color.html">
.>>
\fIcolor\fR
.ig >>
</a>
.>>
.IP
Causes the area background to be filled with \fIcolor\fR.
Example: \fCareacolor: yellow\fR

.LP
\fBframe\fR 
.ig >>
<a href="linedetails.html">
.>>
\fIlinedetails\fR
.ig >>
</a>
.>>
\fC | no | yes | bevel\fR
.IP
Specifies a box or frame around the plotting area.  
Options are: \fCno\fR (no frame), \fCyes\fR (do
a default line frame), \fCbevel\fR for a beveled gray frame,
or a line detail specification, 
which results in a frame made of lines with the given characteristics
(A \fCbevel\fR frame will probably clash with tics and stubs
unless these are positioned inward.)
.br
Example 1: \fCframe: none\fR
.br
Example 2: \fCframe: color=red width=4.0\fR
.br
Example 3: \fCframe: bevel\fR

.LP
\fBlinebottom\fR 
.ig >>
<a href="linedetails.html">
.>>
\fIlinedetails\fR
.ig >>
</a>
.>>
.IP
Specifies a line to be drawn along the bottom edge of the plotting
area.  This is just a line, not an X axis.
.br
Example: \fClinebottom: yes\fR
.br
Example: \fClinebottom: none\fR
.br
Example: \fClinebottom: width=0.5 color=green\fR

.LP
\fBlineside\fR 
.ig >>
<a href="linedetails.html">
.>>
\fIlinedetails\fR
.ig >>
</a>
.>>
.IP
Same as \fClinebottom\fR but specifies a line to be drawn along
the left side.  This is just a line, not a Y axis.

.LP
\fBtitle\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
Specifies a plot title (not a page title).  
Plot title will appear above the upper left corner
of the plotting area by default.
.br
Example: \fCtitle: Subgroup 24-C\fR

.LP
\fBtitledetails\fR 
.ig >>
<a href="textdetails.html">
.>>
\fItextdetails\fR
.ig >>
</a>
.>>
.IP
Text details for the plot title.
.br
Example: \fCtitledetails: align=R size=9 style=I\fR

.LP
\fBtitle2\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
Allows a second title to be specified.  May be useful to create
a plot header on both left and right.

.LP
\fBtitle2details\fR 
.ig >>
<a href="textdetails.html">
.>>
\fItextdetails\fR
.ig >>
</a>
.>>
.IP
Text details for the second plot title.


.LP
\fBxcategories\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI multi-line text\fR
.ig >>
</a>
.>>
 | \fCdatafield=\fIdfield \fR
.IP
A list of categories for use in X, one per line, terminating with 
a blank line.
Or, to take categories from a data field, use
.br
\fCxcategories: datafield=\fR\fIdfield\fR 
.br
where \fIdfield\fR references a data field.
.br
See also 
.ig >>
<a href="scaleunits.html">
.>>
scaleunits
.ig >>
</a>
.>>
for a description of how \fCcategories\fR scaling works.
.br
Example 1:
.nf
.ft C
xcategories:	Red
		Blue
		Green

.fi
.ft R
Example 2: 
\fCxcategories: datafield=1\fR

.LP
\fBycategories\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI multi-line text\fR
.ig >>
</a>
.>>
| \fCdatafield=\fIdfield \fR
.IP
A list of categories for use in Y, one per line.
Same syntax as \fCxcategories\fR.
Categories will be displayed from near the top of
the Y axis downward since this is usually desired, 
rather than from the origin upward as with Y axis labels.
See also 
.ig >>
<a href="scaleunits.html">
.>>
\fIscaleunits\fR
.ig >>
</a>
.>>
for a description of how \fCcategories\fR scaling works.

.LP
\fBxaxis.*\fR
.IP
\fBproc axis\fR attributes for the x axis.  Any \fBproc xaxis\fR attributes may be used
from within \fBproc areadef\fR as a convenience, by prefixing the name with \fCxaxis.\fR.
See 
.ig >>
<a href="axis.html">
.>>
proc axis
.ig >>
</a>
.>>

.LP
\fByaxis.*\fR
.IP
\fBproc yaxis\fR options for the y axis.  Any \fBproc yaxis\fR options may be used
from within Proc Areadef as a convenience, by prefixing the name with \fCyaxis.\fR.
See
.ig >>
<a href="axis.html">
.>>
proc axis
.ig >>
</a>
.>>

.LP
\fBaxisline\fR, \fBtic*\fR, \fBminortic*\fR
.IP
These \fBproc xaxis/yaxis\fR attributes may be defined within
\fBproc areadef\fR to control \fBboth\fR axes.  
.ig >>
<a href="axis.html">
.>>
proc axis
.ig >>
</a>
.>>

