.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 rangebar</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 rangebar</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_rangebar PL "02-JUN-2006   PL ploticus.sourceforge.net"
 
.ig >>
<center><table><tr><td>
<img src="../gallery/rangebar0.gif">
</td><td>
<img src="../gallery/thumbnails/errbar4.png">
</td></tr></table></center>
.>>

\fBproc rangebar\fR draws one boxplot (also known as box-and-whisker plot)
using the
.ig >>
<a href="dataformat.html#currentds">
.>>
\0current data set,
.ig >>
</a>
.>>
in the
.ig >>
<a href="areadef.html">
.>>
\0current plotting area.
.ig >>
</a>
.>>
Rangebars express the range and distribution of one data variable.  \fBproc rangebar\fR
examines the chosen data field and computes some statistics (usually the median, inter-quartile range,
and the 5th and 95th percentiles, and then renders the rangebar.
Alternatively, rangebars can be used to show means and standard deviations.
.LP
Rangebars may be vertical or horizontal.  \fBN\fR will be automatically displayed;
there are also options for reporting of outliers and missing observations.
See also the 
.ig >>
<a href="../gallery/gall.rangebar.html">
.>>
\0gallery rangebar examples.
.ig >>
</a>
.>>

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

.SH Attributes
The \fCdatafield\fR attribute is required.
Default behavior is for statistics to be calculated from the contents of
\fCdatafield\fR to produce a vertical rangebar at X location 1.0 
and for an \fCN=\fR label to be placed just above the X axis.

.ig >>
&nbsp; &nbsp;
.>>

.LP
\fBdatafield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
Specifies the data field on which to compute descriptive statistics.
Example: \fCdatafield: 2\fR

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

.LP
\fBaxis\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCx\fR | \fCy\fR
.IP \0
Determines which axis to plot against.
\fCx\fR results in horizontal rangebars, while
\fCy\fR results in vertical ones.  Default is \fCy\fR.
Example: \fCaxis: x\fR

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

.LP
\fBbarloc\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\0plotvalue
.ig >>
</a>
.>>
.IP \0
Location where the rangebar is to be rendered.
For vertical boxplots this is a plottable value in X;
for horizontal boxplots this is a plottable value in Y.
.br
Example: \fCbarloc: 3\fR

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


.SH Bar appearance details

.LP
\fBbarwidth\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
The width of the box portion of the rangebar in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units.
.ig >>
</a>
.>>
Default is 0.2 inches.
.br
Example: \fCbarwidth: 0.1\fR

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

.LP
\fBcolor\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="color.html">
.>>
\0color
.ig >>
</a>
.>>
.IP \0
Specifies the color of the box area.
Example: \fCcolor: yellow\fR

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

.LP
\fBmediansym\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
\fC | dot | line \fR
.IP \0
Specifies the symbol that will be displayed to show the median.
May be a symbol specification (to get dots, etc.) or \fCline\fR which
is the default.  \fCdot\fR or \fCyes\fR gives a small black dot.
This also controls the mean symbol with \fCmeanmode: yes\fR.
Example: \fCmediansym: shape=diamond\fR

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

.LP
\fBoutline\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, box is outlined with a line.

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

.LP
\fBtaildetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
Controls color, width, etc. of tail lines.
.br
Example: \fCtaildetails: color=blue width=1.8\fR


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

.LP
\fBtailmode\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fC5/95 | minmax | 1.5iqr\fR
.IP \0
Specifies whether the rangebar tails are to extend to the 5th and 95th percentile,
to the min and max, or using 1.5 x IQR.
Only relevant when statistics are computed internally.
Default is \fC5/95\fR.
.br
Note: 1.5irq mode causes the tails to be rendered using the IQR, which is the
interquartile range (the difference between 75th and 25th percentiles).  
This follows the formal Tukey specification, in that the
lower tail will extend from the bottom of the box downward to the nearest data 
point on or above (25th - (1.5 x IQR)).  Similar for upper tail.
.br
Example: \fCtailmode: minmax\fR

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

.LP
\fB95tics\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCtailmode\fR is \fCminmax\fR, allows display of 5th and 95th percentile
by adding tics.
Example: \fC95tics: yes\fR

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



.LP
\fBoutlinedetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
Controls color, width, etc. of box outline.

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


.LP
\fBtruncate\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, bars are truncated to plotting area.
Default is \fCyes\fR.

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

.LP
\fBticlen\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Length, in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units
.ig >>
</a>
.>>
, of the tics which appear at the end of the tails.
Default is 70% of the width of the bar.

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

.LP
\fBmeansym\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | dot | \fR
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
.IP \0
When a median-based rangebar is being rendered, this attribute may be used to
indicate that a second symbol be placed at the mean.  
The result will be two symbols, a symbol at the median, and a second symbol at the mean.
If \fCyes\fR or \fCdot\fR, a default symbol (a small black dot) will be placed at the mean.
Other symbols may be rendered by giving
other symboldetails specifications.  If \fCno\fR, a mean symbol will not
be rendered.  Default is \fCno\fR.
.br
Example: \fCmeansym: shape=circle style=filled fillcolor=black radius=0.04\fR)


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

.SH Selecting data rows

.LP
\fBselect\fR 
.ig >>
<a href="select.html">
.>>
\0select expresion
.ig >>
</a>
.>>
.IP \0
Allows cases to be selected for inclusion using a selection expression.
.br
Example: \fCselect: @2 = B\fR

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

.SH Mean & standard deviation mode
You can create rangebars that display means and standard deviations if you wish,
instead of medians and IQR.

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

.LP
\fBmeanmode\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If yes, mean and standard deviation are computed and drawn as
an error bar, instead of a boxplot of median/quartiles, etc.
Mean is shown as a point (style can be controlled using \fCmediansym\fR).
Number of standard deviations may be controlled using \fCnstddevs\fR.
Cannot be used with \fCvalues\fR; use \fBproc bars\fR instead.
Appearance of the lines may be controlled using \fCtaildetails\fR.

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

.LP
\fBlogmean\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If yes, mean and standard deviation are computed in log space.
Useful with data having log characteristics; when plotted in
log space the standard deviations will appear equidistant from the mean.
If log+1 scaling is in effect for the plot, then this feature 
will operate in log+1 space (allowing 0.0 values).

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

.LP
\fBnstddevs\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Used with \fCmeanmode\fR.  Specifies the number of standard deviations
to use in each direction when drawing the error bar.  Default is 1.

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

.LP
\fBskipmed\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes  |  no\fR
.IP \0
When using \fCmeanmode\fR, this attribute may be specified as \fCyes\fR to speed things
up a bit by avoiding computation of medians and percentiles.
Default is always \fCno\fR.

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

.SH Displaying outliers

.LP
\fBshowoutliers\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes  |  no\fR
.IP \0
If \fCyes\fR, outliers will be displayed and/or reported upon.
An outlier is any point that is beyond the end of either of the rangebar's tails.
The default way of displaying outliers is circles for the near outliers
and asterisks for the far outliers.  The default boundary between near
and far is 3 times the interquartile range.

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

.LP
\fBoutlierprint\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, a report on each outlier will be printed to standard error.

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

.LP
\fBoutliernearsym\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
\fC | none\fR
.IP \0
Specifies the symbol for displaying near outliers.
Default is a small circle: \fCshape=circle style=outline radius=0.05\fR.
Use \fCnone\fR if you are displaying outliers as lines or labels
and don't want any geometric symbol.

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

.LP
\fBoutlierfarsym\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
\fC | none\fR
.IP \0
Specifies the symbol for displaying far outliers.
Default is an asterisk: \fCshape=circle style=spokes radius=0.05\fR
Use \fCnone\fR if you are displaying outliers as lines or labels
and don't want any geometric symbol.

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

.LP
\fBoutliernearfarcutoff\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
The boundary between near outliers and far outliers will be \fIn\fR times
the interquartile range.  Default is 3.0.

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

.LP
\fBoutlierlinelen\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Display outliers as line segments.
If specified, all outliers (near and far) 
are displayed as short line segments rather than symbols.
\fIn\fR will be the length of these segments, in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute space.
.ig >>
</a>
.>>
The color and width of these line segments may be controlled using
\fCoutlierlinedetails\fR.
.br
Example: \fCoutlierlinelen: 0.1\fR

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

.LP
\fBoutlierlabelfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, the contents of this field will appear as a text label for each outlier.
For vertical rangebars the label will appear a bit to the right 
of the point.
For horizontal rangebars the label will appear in rotated text, a bit above
the point.
The size, style, and location may be adjusted if desired using the \fCoutlierlabeldetails\fR
attribute.

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

.LP
\fBoutlierlabeldetails\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details related to the outlier labels.  

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

.LP
\fBoutlierlinedetails\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
When outliers are being rendered as line segments, specifies
color, line width, etc. of these line segments.

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

.SH Labels
.LP
\fBprintn\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, a label showing N (the number of observations) is produced.
Default is \fCyes\fR.
Example: \fCprintn: no\fR

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

.LP
\fBnlocation\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0locvalue
.ig >>
</a>
.>>
.IP \0
Where to position the N label.  The label will be aligned with the rangebar.
For vertical rangebars \fClocation\fR indicates where to place the label
in Y; for horizontal, X.
Example: \fCnlocation: -4\fR

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

.LP
\fBnword\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#string>">
.>>
\0string
.ig >>
</a>
.>>
.IP \0
A template that determines the format of the N label.
Default is \fCN=@@N\fR.
The N value is substituted for the \fC@@N\fR symbol.
Example: \fC(N = @@N)\fR


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

.LP
\fBprintmissing\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, a label showing the number of non-plottable (missing) values is produced.
Only relevant if statistics are calculated internally.
Example: \fCprintmissing: yes\fR

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

.LP
\fBmlocation\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0locvalue
.ig >>
</a>
.>>
.IP \0
Where to position the missing values label.  
The label will be aligned with the rangebar.
For vertical rangebars \fClocation\fR indicates where to place the label
in Y; for horizontal, X.

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

.LP
\fBmword\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#string">
.>>
\0string
.ig >>
</a>
.>>
.IP \0
A template that determines the format of the label showing number of
missing values.
Default is \fCM=@M\fR.
The N value is substituted for the \fC@M\fR symbol.
Example: \fC(@M missing)\fR

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

.LP
\fBntextdetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Set the size, color, font or fine-tune the position of the N labels.
Alternate name for backward compatibility: \fCtextdetails\fR.
.br
Example: \fCntextdetails: size=8 style=I\fR

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

.LP
\fBmtextdetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Set the size, color, font or fine-tune the position of the missing labels.
.br
Example: \fCmtextdetails: size=8 adjust=0,0.05\fR

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

.LP
\fBmwhenexists\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fC yes|no\fR
.IP \0
If \fCyes\fR, the missing label will be displayed only if the number of
missing observations is greater than 0.  Default is \fCno\fR.

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

.SH Accessing the generated statistics

.LP
\fBstatsonly\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If yes, statistics will be computed and internal @variables set, but no rangebar rendered.
I've used this to compute with \fCmeanmode: yes\fR to compute the overall mean and standard
deviation for a set of data points, then render them using lines (via @RANGEBARMEAN, @RANGEBARMIN,
and @RANGEBARMAX).

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

.LP
\fBshowstats\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes \fR| \fCno\fR | \fConly\fR
.IP \0
If \fCyes\fR or \fConly\fR, all the computed descriptive statistics 
will be written to the showstatsfile.
If \fConly\fR, the statistics will be printed but no bars will be drawn.

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

.LP
\fBshowbriefstats\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no | only\fR
.IP \0
If yes, and if N > 0, the most important computed descriptive statistics 
will be written to the showstatsfile.  All fields are on one line, TAB-delimited,
for convenient use by other programs.
The fields are in this order: 
.IP \0
tag, datafield, N, mean, standard deviation, median, min, max, #missing.
.IP \0
The tag contents may be set using the \fCbriefstatstag\fR attribute; if this attribute is not
set then the first result field will be datafield. 

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

.LP
\fBbriefstatstag\fR 
.ig >>
&nbsp; &nbsp;
.>>
text
.IP \0
Set the contents of the tag that will be written at the beginning of each 'briefstats' record.
This may be useful in identifying cases and groups in the 'brief stats' output.

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

.LP
\fBshowstatsfile\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIfilename\fR
.IP \0
If specified, statistics will be written to this file.
If not specified, statistics will be written to the diagnostic stream,
usually stderr.
File will be opened in \fBappend\fR mode, so the caller may want 
to remove previous contents of the file before invoking ploticus.

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

.SH Supplying pre-computed statistics
If you have already computed the summary stats, you can supply them using these attributes,
and ploticus will render a rangebar to suit.

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

.LP
\fBvalues\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fI5thpercentile 25th median 75th 95th [N]\fR
.IP \0
Specify pre-computed descriptive statistics that should just
be plotted.  5 plottable values should be given.  If a 6th value
is given it is taken to be N, and \fCprintn\fR is implied.
Min/max may be substituted for the 5th and 95th percentiles
if desired.
.br
Example: \fCvalues: 0.3 3.0 5.3 6.2 9.4 236\fR

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

.LP
\fBplotfields\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fI5thpercentile 25th median 75th 95th [N]\fR
.br
or with \fCmeanmode\fR: \fBplotfields\fR \fImean stddev [N]\fR  
.IP \0
Similar to \fCvalues\fR but rather than literal values, a set of 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
s are given.  The data will be accessed from one row, which may be
specified using \fCplotrecord\fR.  (If \fCplotrecord\fR not specified,
data will be taken from the first row by default.  Proc processdata
action: select may be used to isolate one row of data.) Example: 
.nf
  plotfields: 1 2 3 4 5
  plotrecord: 1
.fi

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

.LP
\fBplotrecord\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Used with \fCplotfields\fR; indicates which data row to get the values from.
First row is \fC1\fR.  Example: see \fCplotfields\fR above.
If not specified, first row is assumed.





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

.SH VARIABLES THAT ARE SET
\fBNVALUES\fR is set to N.  If nothing was plotted, this will be equal to 0.
.LP
The following variables are set as soon as statistics are computed, whether or
not a plot is actually drawn.
.LP
\fBRANGEBARMEDIAN\fR is set to hold the median value.
This might be useful in drawing a line for comparing medians.
Not set when using \fCmeanmode\fR.
.LP
\fBRANGEBARMEAN\fR is set to hold the mean value.
This might be useful in drawing a line for comparing means.
Set only when using \fCmeanmode\fR.
.LP
\fBRANGEBARIQRMIN\fR and \fBRANGEBARIQRMAX\fR are set to hold the
values of the bottom and top of the box.  Not set when using \fCmeanmode\fR.
.LP
\fBRANGEBARMIN\fR and \fBRANGEBARMAX\fR are set to hold the
values at the ends of the tails.  Normally this will be the 5th and 95th percentile;
with \fCmeanmode: yes\fR it will be +/- one standard deviation.


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