.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 areadef</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 areadef</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.33 Jun'06
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_areadef PL "02-JUN-2006   PL ploticus.sourceforge.net"

\fBproc areadef\fR defines a rectangular area where subsequent scaled plotting will take place.
The size, location of the rectangle are specified, and the
scaling method and range of both X and Y are defined here.
\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, but only one plotting
area and scale system is in effect at any one time (referred to as the "current plotting area").
.LP
Various scaling types, including linear, log, date, time and category are available for X and Y.  
The
.ig >>
<a href="autorange.html">
.>>
\0xautorange and yautorange attributes
.ig >>
</a>
.>>
can be used to perform automatic axis scaling based on the data.
.ig >>
<a href="clickmap.html">
.>>
\0Clickmap and mouseover support
.ig >>
</a>
.>>
is available for the plotting area grid or as a whole.


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

.SH Attributes
The range in X and Y \fBmust\fR be specified, either using
\fCxrange\fR / \fCyrange\fR, or
\fCxautorange\fR / \fCyautorange\fR.
If nothing else is specified,
default behaviour is for the \fCstandard\fR
plotting area to be used, with linear scaling in x and y.

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

.SH Location & size of the plotting rectangle
The size and location of the plotting area
on a page (the plotting area) may be specified in one 
of these three ways: 
.IP \0 
- by specifying a rectangle (two points) using the \fCrectangle\fR attribute;
.IP \0
- by specifying plotting area size using
the \fCbox\fR attribute and the location using the \fClocation\fR attribute.
.IP \0
- by name using the \fCareaname\fR attribute;
.LP
You can also make the plot area size vary automatically based on how much data you are plotting
(\fCautowidth\fR and \fCautoheight\fR).

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

.LP
\fBrectangle\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIx1 y1 x2 y2\fR
.IP \0
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">
.>>
\0absolute units).
.ig >>
</a>
.>>
.br
Example: \fCrectangle: 1.4 4 7.4 8\fR

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

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

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

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

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

.LP
\fBareaname\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIname\fR 
.IP \0
Allows a plotting area to be defined by selecting a 
predefined rectangle by 
.ig >>
<a href="#areanames">
.>>
\0name.
.ig >>
</a>
.>>
These are most useful when generating plots on standard paper.
.br
Example: \fCareaname: 2hi\fR

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

.LP
\fBautowidth\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIf\fR  
.ig >>
&nbsp; &nbsp;
.>>
[\fIminallowablesize  maxallowablesize\fR]
.IP \0
If sepcified, the width of the plotting area will be influenced by the data range in X.
For example, you would probably want to display 8 categories using a smaller plot
area than 48 categories.
\fCautowidth\fR allows this to be done automatically, driven by the data.
You must fully specify the plotting area using \fCrectangle\fR or some other attribute(s),
and specify the scaling in X.
This attribute then revises the width of the plotting area by setting it
to \fIf\fR times the number of basic units in the range of X, in absolute units.
You can optionally set a \fIminallowablesize\fR and a \fImaxallowablesize\fR (both in absolute units)
that the plot will never be smaller than, or larger than, respectively.
For example:
.nf
\0  #proc areadef
\0     rectangle: 1 1 6 3
\0     xcategories: datafield=2
\0     autowidth: 0.3  3.0  8.0
.fi
For example, if there are 12 categories represented in your data, 12 x 0.3 = 3.6, so the resulting
plotting area would be 3.6 inches wide.
If there are 20 categories, 20 x 0.3 = 6.0, and the resulting
plotting area would be 6.0 inches wide.
If there are only six categories, the resulting plot would have been 1.8 inches wide,
however a minimum allowable size of 3.0 inches was specified, so the plot will be 3 inches wide.
If there are 40 categories, the resulting plot would have been 12 inches wide,
however a maximum allowable size of 8.0 inches was specified, so the plot will be 8 inches wide.
.IP \0
Remember that with date and datetime scaling the basic unit is the day, and with time
scaling the basic unit is the minute.

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

.LP
\fBautoheight\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIf\fR
.IP \0
Allows the height of the plotting area to be determined by the data range in Y.
See \fCautowidth\fR.


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

.SH Scaling method & range in X and Y

.LP
\fBxscaletype\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fItype\fR 
.ig >>
&nbsp; &nbsp;
.>>
[\fIformat\fR]
.IP \0
Defines the type of scaling that will be in effect for the X axis.  
Supported \fItypes\fR include:
.br
.nf
scaletype      description
----------     ------------------------------------------
linear         the default; continuous linear
log log+1      logarithmic scaling
date           scaling based on date values, usually in X
time           scaling based on time values, usually in X
datetime       for plotting time values over several days
categories     bins for categorical data.  
.fi
.IP
The \fIformat\fR parameter may be given with
\fCdate\fR, \fCtime\fR, or \fCdatetime\fR, to set the default date/time notation.  See 
.ig >>
<a href="scaleunits.html">
.>>
\0scaleunits
.ig >>
</a>
.>>
for discussion of the various scale types and units, and the
.ig >>
<a href="../gallery/gall.sa.html">
.>>
\0gallery scale & axis examples.
.ig >>
</a>
.>>
.IP
\fCxrange\fR or \fCxautorange\fR will also need to be specified.
For \fCcategories\fR, a set of categories must be already defined using
.ig >>
<a href="categories.html">
.>>
\0proc categories
.ig >>
</a>
.>>
or using the equivalent 
.ig >>
<a href="#categories">
.>>
\0proc areadef categories attributes.
.ig >>
</a>
.>>
.IP
Example: \fCxscaletype: date yymm\fR
.br
Example: \fCxscaletype: datetime mm/dd/yyyy.hh:mm\fR
.br
Example: \fCxscaletype: categories\fR

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

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

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

.LP
\fBxrange\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fImin max\fR | \fCcategories\fR
.IP \0
Defines the plottable range in x.  \fImin\fR and \fImax\fR must both be given,
and must both be plottable values with respect to \fCxscaletype\fR.
(To set a continuous range automatically using a data field, use \fCxautorange\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).
If date, time, log, categories, or other special type of scaling is to be done, 
\fCxscaletype\fR must be set appropriately.
If you want, you can specify \fCcategories\fR, but this just has the same effect as 
setting the scaletype to \fCcategories\fR.
.br
Example: if your data ranges in x between
1.5 and 23.5 you might use: \fCxrange: 0 24\fR
.br
Example: \fCxrange: categories\fR
.br
Example: \fCxrange: 01FEB2002 28FEB2002\fR
.br
Example: \fCxrange: 01FEB2002.00:00 04FEB2002.24:00\fR

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

.LP
\fBxautorange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCdatafield=\fIdfields\fR .. other subattributes..
.IP \0
This may be used as an alternative to \fCxrange\fR, in order to automatically
find an appropriate range based on the data.  \fIdfields\fR are the data field(s) to be scanned.
This attribute has its own 
.ig >>
<a href="autorange.html">
.>>
\0manual page.
.ig >>
</a>
.>>

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

.LP
\fByrange\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fImin max\fR
.IP \0
Defines the plottable range in y.   See \fCxrange\fR above.

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

.LP
\fByautorange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCdatafield=\fIdfield\fR .. other subattributes..
.IP \0
This may be used as an alternative to \fCyrange\fR, in order to automatically
find an appropriate range based on the data.  Similar to \fCxautorange\fR.
This attribute has its own 
.ig >>
<a href="autorange.html">
.>>
\0manual page.
.ig >>
</a>
.>>



.ig >>
<a name=categories></a>
.>>

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

.SH Categories 
As of version 2.11 categories can be defined beforehand using a new proc called
.ig >>
<a href="categories.html">
.>>
\0proc categories.
.ig >>
</a>
.>>
Previously, categories were defined within proc areadef using the attributes listed
below, and this syntax will continue to be supported.  However, additional capabilities
and higher capacities are available via 
.ig >>
<a href="categories.html">
.>>
\0proc categories.
.ig >>
</a>
.>>
See the
.ig >>
<a href="categories.html#oldway">
.>>
\0proc categories man page
.ig >>
</a>
.>>
for fuller descriptions.

.LP
\fBxcategories\fR ..define a set of categories to be used in X.  

.LP
\fBycategories\fR ..define a set of categories to be used in Y.  

.LP
\fBxextracategory\fR ..allows an extra X axis category to be added explicitly

.LP
\fByextracategory\fR ..allows an extra Y axis category to be added explicitly

.LP
\fBcatcompmethod\fR ..control the details of how category comparisons are done.



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

.SH Axis generation
X and Y axes are generated by 
.ig >>
<a href="axis.html">
.>>
\0proc axis
.ig >>
</a>
.>>
; however, axis attributes may be specified from within \fBproc areadef\fR 
as a convenience.  This usually involves adding a \fCxaxis.\fR or \fCyaxis.\fR prefix 
to the attribute name.  If axes are defined this way then the plotting area and axes can all be 
.ig >>
<a href="scriptsyntax.html">
.>>
\0#clone'd
.ig >>
</a>
.>>
as a unit.

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

.LP
\fBxaxis.*\fR
.IP \0
\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">
.>>
\0proc axis
.ig >>
</a>
.>>

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

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

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

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

.ig >>
<br><br>
.>>
.LP
Example:
.nf
  #proc areadef
    xscaletype: date dd-Mmm-yyyy
    xrange: 01-Jun-2003 15-Jun-2003
    yrange: 0 100
    xaxis.label: Date
    xaxis.stubs: inc 3 day
    xaxis.stubformat: mm/dd
    yaxis.label: Percent occupied
    yaxis.stubs: inc
.fi
    


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

.SH Other attributes of the plotting area

.LP
\fBtitle\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
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

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

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

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

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

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

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

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

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

.LP
\fBframe\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
\fC | no | yes | bevel\fR
.IP \0
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

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

.LP
\fBlinebottom\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
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

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

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

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

.SH Clickmaps and mouseover

.LP
\fBclickmapurl\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIurl template\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 must be specified to supply a URL template, into which
@@XVAL and/or @@YVAL will be substituted.  See the
.ig >>
<a href="clickmap.html">
.>>
\0clickmap page
.ig >>
</a>
.>>
for more details and examples.
.br
Example: \fCclickmapurl: http://abc.com/cgi-bin/details?x=@@XVAL&y=@@YVAL\fR
.IP
This attribute can also be used to make the entire plotting area one clickable region.
This will be done if niether @@XVAL nor @@YVAL are found in the template.

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

.LP
\fBclickmaplabel\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIlabel\fR
.IP
If generating a
.ig >>
<a href="clickmap.html">
.>>
\0client-side clickmap,
.ig >>
</a>
.>>
region encompassing the entire plotting area,
this specifies a mouseover text label.
.br
Example: \fCclickmaplabel: Animals tested without drug effect\fR

.LP
\fBclickmaplabeltext\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0multiline text
.ig >>
</a>
.>>
.IP \0
Same as \fCclickmaplabel\fR but multiline text.  Must be terminated with a blank line.




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

.SH Variables set by proc areadef
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>
.>>
 . 
Also, \fBXMIN\fR, \fBXMAX\fR, \fBYMIN\fR, and \fBYMAX\fR are set to the
scaled space boundaries.


.ig >>
<a name=areanames></a>
.>>
.ig >>
<br><br><br>
.>>

.SH Pre-defined plotting area names
Pre-defined plotting area names, used with the \fCareaname:\fR attribute, are:
.IP \0
.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
lifetab  	works well for life tables
.fi
.ft R
.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>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>
