.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: xautorange and yautorange attributes</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>xautorange and yautorange attributes</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.30
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH xautorange_and_yautorange_attributes PL "26-AUG-2004   PL ploticus.sourceforge.net"

.SH Usage
\fCxautorange:  datafield=\fIdfields\fC  \fIother settings..\fR
.br
or..
.br
\fCyautorange:  datafield=\fIdfields\fC  \fIother settings..\fR

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

.SH Automatic axis range determination
\fBxautorange\fR and \fByautorange\fR are attributes of
.ig >>
<a href="areadef.html">
.>>
\0proc areadef
.ig >>
</a>
.>>
that allow axis range to be automatically determined based on the range of the data.
.LP
Default autorange behavior is as follows:
For numeric data the range is set to the nearest whole high and low scale increments 
that encompass the min and max of the data.
For date and time data the range is set to the exact min and max of the data.
See also gallery examples 
.ig >>
<a href="../gallery/scatterplot10.htm">
.>>
\0scatterplot10,
.ig >>
</a>
.>>
.ig >>
<a href="../gallery/stockday.htm">
.>>
\0stockday,
.ig >>
</a>
.>>
and 
.ig >>
<a href="../gallery/mouse.htm">
.>>
\0mouse.
.ig >>
</a>
.>>

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

.SH Settings
The \fCdatafield\fR setting \fBmust\fR be specified, and it must be leftmost.

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

.LP
\fCdatafield=\fIdfields\fR
.IP \0
This setting must be given first (to the left of any other).
It specifies one or more data fields that will be scanned to 
automatically find minima and maxima.
\fIdfields\fR may be a single 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
or a comma-delimited list of several dfields with no embedded space.
Unless a \fCcombomode=\fR setting is used, all fields will be treated independently
when searching for a minima and maxima.
Invalid or non-existant dfields will be silently ignored, but there must be at least one valid dfield.  
Support for multiple fields contributed by Paul Totten.
.br
Example: \fCyautorange  datafield=2\fR
.br
Example: \fCyautorange  datafield=2,4,5\fR

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

.LP
\fCcombomode=stack | combomode=hilo\fR
.IP \0
If specified, an alternate method of min/max determination is used with multiple \fCdatafield\fRs.
.br
\fCstack\fR = sum the data field contents (useful when generating stacked bar graphs).
.br
\fChilo\fR = take the sum and difference of data field contents; useful when 
ranging on two fields, and one data field will be driving error bars.

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

.LP
The following settings allow autorange behavior to be controlled explicitly:

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

.LP
\fCincmult=\fIh\fR 
.IP \0
controls the amount of margin at high and low end when 
working with numeric data in default mode as described above.  
The default \fIh\fR is 1.0.
The scale increment will be multiplied by \fIh\fR before determining the range.
The low end of the range will not dip below zero if data are all positive.  
.br
Example: \fCyautorange  datafield=2  incmult=2.0\fR

.ig >>
<br><br>
.>>
.LP
.ig >>
<a name=nearest></a>
.>>
\fCnearest=\fIs\fR
.IP \0
may be used to explicitly define the extent of the range, 
to a boundary corresponding to a round value of your choice.  
If you do not specify a \fCnearest=\fR value autorange
will guess based on the magnitude of the data.
If \fCnearest=exact\fR is specified, the range will be the 
exact minima to the exact maxima.
See the table below for some possible values for \fIs\fR.
An example: if \fIs\fR is \fC100\fR, and the data range
from 23 to 1162, the plot's range will be 0 to 1200.
The following illustrates some possible values for \fCnearest=\fIs\fR:
.br
.nf
.ft C
s         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 (date or datetime scaletypes only)
quarter   the nearest quarter-year boundary (date or datetime only)
year      the nearest year boundary (date or datetime only)
hour      the nearest hour boundary (time or datetime only)
day       the nearest day boundary (datetime only)
exact     the exact minima and maxima
(none)    a reasonable default (numeric data only)
.fi
.ft R

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

.LP
\fCmargin=\fIm\fR 
.IP \0
If specified, \fIm\fR basic 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.
(Basic units are days for \fCdate\fR and \fCdatetime\fR scaletypes; and 
minutes for \fCtime\fR.)

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

.LP
\fClowfix=\fIlowval\fR 
.IP \0
If specified, the minima will always be \fIlowval\fR.
This is useful when you want only the maxima to be automatically set based on data.
.br
Example: \fCyautorange:  datafield=2  lowfix=0\fR

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

.LP
\fChifix=\fIhival\fR 
.IP \0
If specified, the maxima will always be \fIhival\fR.
This is useful when you want only the minima to be automatically set based on data.

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

.LP
\fCmininit=\fIlowval\fR
.IP \0
Like \fClowfix\fR but is overridden by encountered data values less than \fIlowval\fR.
Useful for example if you want your axis min to be zero except when there is an occasional
negative data value. (2.30+)
.ig >>
<br><br>
.>>


.LP
\fCmaxinit=\fIhival\fR
.IP \0
Like \fChifix\fR but is overridden by encountered data values greater than \fIhival\fR. (2.30+)
.ig >>
<br><br>
.>>

.LP
\fCmininit=\fIlowval\fR
.IP \0
Like \fClowfix\fR but is overridden by encountered data values lower than \fIlowval\fR.

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

.LP
\fCnumformat=\fIprintfspec\fR 
.IP \0
This allows user control over the internal string-based representation of minima and maxima for numerics.  
Default is \fC%g\fR.  Try \fC%f\fR if you're encountering problems involving very large or very small
numeric quanitities.

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

.LP
\fCselectrows=\fIconditional expression\fR
.IP \0
This allows a
.ig >>
<a href="select.html">
.>>
\0select expression
.ig >>
</a>
.>>
to be applied in order to select data rows to be tested when
scanning for minima and maxima.
If specified, this setting must be the last (rightmost) on the line, and 
will have embedded spaces, unlike the other settings.  See example below.

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

.SH Variables that are set by autorange
.LP
\fBDATAXMIN\fR, \fBDATAXMAX\fR
.IP \0
The actual minima and maxima of the data field when ranging in X.  
Different from XMIN and XMAX in that these do not include any margin.
.LP
\fBDATAYMIN\fR, \fBDATAYMAX\fR
.IP \0
The actual minima and maxima of the data field when ranging in Y.  
Different from YMIN and YMAX in that these do not include any margin.

.ig >>
<br><br><br>
.>>
.SH Examples
Example: \fCxautorange: datafield=2 nearest=month margin=31\fR
.LP
Example: \fCyautorange: datafield=3,4,5,6,7  selectrows=@@sex = f\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>
.>>
