<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:12. -->
<!-- Do not edit! -->
<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 bars</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 bars</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.41 Mar2009
</small><br><a href="../doc/scripthome.html">Scripts</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for proc_bars(PL)</title>
</head>
<body>
<center>
<img src="../gallery/errbar0.gif">
<img src="../gallery/hbars0.gif">
<img src="../gallery/timeline0.gif">
</center>
<p>
<b>proc bars</b> draws bargraphs, histograms, error bars, or segment bars using the
<a href="dataformat.html#currentds">
current data set,
</a>
in the
<a href="areadef.html">
current plotting area.<tt> </tt>
</a>
Bars can be vertical or horizontal, and can be stacked and/or clustered.<tt> </tt>
Clickmaps and mouseover text labels are supported.<tt> </tt>
See also the gallery examples for
<a href="../gallery/gall.bars.html">
vertical bars,
</a>
<a href="../gallery/gall.hbars.html">
horizontal bars,
</a>
and
<a href="../gallery/gall.errbar.html">
error bars.<tt> </tt>
</a>
<p>
Please note: Everywhere in this page, descriptions are written with vertical bars in mind..<tt> </tt>
remember to reverse sense of X and Y in these descriptions if doing horizontal bars.<tt> </tt>
<br><br><br>
<h2>Attributes</h2>
The <tt>lenfield</tt> attribute <b>must</b> always be specified.<tt> </tt>
The <tt>locfield</tt> attribute is usually given.<tt> </tt>
<br><br>
<h2>Bar location and lengths</h2>
<p>
<b>lenfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
The contents of this data field will be used to control bar length.<tt> </tt>
These should be plottable values in Y.
Example: <tt>lenfield: 2</tt>
<br><br>
</dl>
<p>
<b>locfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
The contents of this data field will be used to control bar location in X.<tt> </tt>
These should be plottable values in X.
If <tt>locfield</tt> is not specified, bars will be located at consecutive
unit locations in X.<tt> </tt>
Example: <tt>locfield: 1</tt>
<br><br><br>
</dl>
<h2>Vertical or horizontal</h2>
<p>
<b>horizontalbars</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If yes, bars will be horizontal.<tt> </tt>
Otherwise, bars will be vertical.<tt> </tt>
Example: <tt>horizontalbars: yes</tt>
<dt><dd><p>
An older attribute called <tt>axis</tt> also exists to do this... <tt>axis: x</tt> would produce horizontal bars.<tt> </tt>
<br><br><br>
</dl>
<h2>Basic bar appearance details</h2>
<p>
<b>barwidth</b>
<i>n</i>
<dl>
<dt> <dd>
Width of bars in
<a href="attributetypes.html#positionunits">
absolute units.<tt> </tt>
</a>
If not specified width will be determined based on scaling,
but this may not always be satisfactory. For very thin bars
use <tt>thinbarline</tt> (see below).<tt> </tt>
<br><br>
</dl>
<p>
<b>color</b>
<a href="color.html">
color
</a>
<dl>
<dt> <dd>
If specified, all bars will be rendered in this color. Example: <tt>color: green</tt>
If bars are very thin, or error bars are being done, the
color is specified via the <tt>thinbarline</tt> attribute.<tt> </tt>
The <tt>hatch</tt> color values may be useful when working
in Postscript monochrome. See also the <tt>colorlist</tt>
and <tt>colorfield</tt> attributes.<tt> </tt>
<br><br>
</dl>
<p>
<b>outline</b>
<a href="linedetails.html">
linedetails
</a>
<dl>
<dt> <dd>
If <tt>yes</tt> or a linedetails specification, causes bars to be outlined
with a line. If <tt>no</tt> or <tt>none</tt>, no outline is produced.<tt> </tt>
Default is <tt>yes</tt>, which gives a thin black outline.<tt> </tt>
<br>
Example: <tt>outline: color=blue</tt>
<br>
Example: <tt>outline: no</tt>
<br><br>
</dl>
<p>
<b>thinbarline</b>
<a href="linedetails.html">
linedetails
</a>
| <tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If specified, bars will be rendered as lines with the given properties.<tt> </tt>
<tt>yes</tt> gives a default thin black line. This should be used when bars are
to be very thin; otherwise, they may not be visible depending on your display
resolution. This attribute also controls the style, color, etc. of error bars.<tt> </tt>
<br><br>
</dl>
<p>
<b>truncate</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, bars and labels will be truncated to the plotting area.
Default is <tt>no</tt>.<tt> </tt>
<br><br>
</dl>
<p>
<b>crossover</b>
<a href="attributetypes.html#plotvalue">
plotvalue
</a>
<dl>
<dt> <dd>
If specified, causes plottable values less than this to be shown
using bars extending in the opposite direction.
Typically used for values less than zero.
Default is no crossover.<tt> </tt>
Example: <tt>crossover: 0</tt>
<br><br><br>
</dl>
<h2>Omitting certain bars</h2>
<p>
<b>select</b>
<a href="select.html">
select expression
</a>
<dl>
<dt> <dd>
Allows data rows to be selected for inclusion
using a selection expression.
<br>
Example: <tt>select: @@3 = B</tt>
<br><br>
</dl>
<p>
<b>barsrange</b>
<i>min</i>
[<i>max</i>]
<dl>
<dt> <dd>
If specified, and if <tt>locfield</tt> is used to position bars,
bars will only appear if the value in <tt>locfield</tt> is within
this range. If only one value is given it is taken as the <b>minima</b>.<tt> </tt>
</dl>
<p>
<b>hidezerobars</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, bars that are zero-length will not be drawn at all.<tt> </tt>
Default is <tt>no</tt> (zero length bars may be visible as a thin line).<tt> </tt>
<br><br><br>
</dl>
<h2>Stacked bars</h2>
<p>
<b>stackfields</b>
<tt>*</tt>
<br>
<i>or</i>
<br>
<b>stackfields</b>
<a href="attributetypes.html#dfield">
dfield1
</a>
..
<a href="attributetypes.html#dfield">
dfieldn
</a>
<dl>
<dt> <dd>
If specified, causes current set of bars to be placed on top
of earlier sets.
If <tt>*</tt> is given, it is taken to mean "stack this set of bars on top of
all previously plotted bars" (same area, same cluster member).<tt> </tt>
Fields may be specified explicitly (see the examples).<tt> </tt>
Max number of stackable fields is 40.
<b>Note:</b> stacked bar graphs require that the data be organized such that all components
of a bar be located on the same data row (ie. different <tt>select</tt>s cannot be
used for the different layers of bars).<tt> </tt>
<br>
Example: <tt>stackfields: *</tt>
<br>
Example: <tt>stackfields: 3 4 5</tt>
<br><br><br>
</dl>
<h2>Clusters of bars</h2>
<p>
<b>cluster</b>
<i>position</i> <tt>/</tt> <i>nmembers</i>
<dl>
<dt> <dd>
If specified, causes the current set of bars to be rendered as a
member of a cluster. <i>position</i> indicates which member of the
cluster is being done (1 = leftmost). <i>nmembers</i>
indicates how many bars are in each cluster.<tt> </tt>
<br>
Example: <tt>cluster: 1 / 4</tt> would be used to render the
first set of bars where clusters of 4 are being done.<tt> </tt>
<dt> <dd>
You can also say <tt>cluster: 1 of 4</tt> if you prefer.<tt> </tt>
</dl>
<p>
<b>clustersep</b> <i>n</i>
<dl>
<dt> <dd>
If specified when doing clustered bars, members of each cluster
are separated from each other by <i>n</i>
<a href="attributetypes.html#positionunits">
absolute units
</a>
Default is 0.0 (bars butted up against one another).<tt> </tt>
<br><br><br>
</dl>
<h2>Floating segment bars</h2>
<p>
<b>segmentfields</b>
[ <i>start-dfield</i> ]
<a href="attributetypes.html#dfield">
stop-dfield
</a>
<dl>
<dt> <dd>
If specified, causes floating segment bars to be rendered rather than
length-based bars. These are typically used to display ranges
(but should not be confused with <b>proc rangebar</b> which computes
and displays percentiles).<tt> </tt>
Each bar will be drawn from the data value in <i>start-dfield</i>
to the data value in the <i>stop-dfield</i>.<tt> </tt>
It's possible to render error bars with this attribute by using the <tt>thinbarline</tt> and <tt>tails</tt> attributes as well.<tt> </tt>
<br>
Example: <tt>segmentfields: 1 3</tt>
<br><br><br>
</dl>
<h2>Error bars</h2>
<p>
<b>errbarfields</b>
<a href="attributetypes.html#dfield">
errlowfield
</a>
[
<a href="attributetypes.html#dfield">
errhifield
</a>
]
<dl>
<dt> <dd>
If specified, causes error bars to be rendered rather than
length based bars. <tt>lenfield</tt> must also be specified.<tt> </tt>
Spacing between error bars is controlled by <tt>barwidth</tt> (as if there were ordinary bars accompanying the error bars).<tt> </tt>
A thin error bar with tails is drawn from the value in <tt>lenfield</tt>,
downward for the distance located in <i>errlowfield</i>, and then
upward for the distance located in <i>errhifield</i>.<tt> </tt>
If <i>errhifield</i> is not given, the error bar is assumed to
be symmetrical.<tt> </tt>
You can do one-way error bars by giving an <tt>errlowfield</tt> of <tt>0</tt> and
specifying <tt>errhifield</tt>.<tt> </tt>
See also <tt>segmentfields</tt>, which you can use to draw error bars based on actual
rather than relative values.<tt> </tt>
See also <tt>errbarmult</tt>.<tt> </tt>
<br><br>
</dl>
<p>
<b>errbarmult</b>
<i>n</i>
<dl>
<dt> <dd>
If specified, error bars will be drawn to <i>n</i> times the distance
given in the data. Useful for drawing error bars showing 2 x standard error.<tt> </tt>
<br><br>
</dl>
<p>
<b>tails</b>
<i>n</i>
<dl>
<dt> <dd>
If specified, tails of length <i>n</i> (in
<a href="attributetypes.html#positionunits">
absolute units
</a>
) are
rendered at the top and bottom of each bar. Typcially used
with error bars. Tails of a default length are automatically
rendered if <tt>errbarfields</tt> is used.<tt> </tt>
Example: <tt>tails: 0.2</tt>
<br><br><br>
</dl>
<h2>High - low - close bars</h2>
<p>
<b>leftticfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<p>
<b>midticfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<p>
<b>rightticfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<p>
<b>ticlen</b>
<i>h</i>
<dl>
<dt> <dd>
If specified, a left-pointing, centered, or right-pointing tic mark
will be displayed at the value in <i>dfield</i>. The tics are drawn
on top of the bars using the current line (outline or thinbarline), beginning
in the center of the bar.<tt> </tt>
Length is set by attribute <tt>ticlen</tt>, which sets the tick length
to <i>h</i>
<a href="attributetypes.html#positionunits">
absolute units.<tt> </tt>
</a>
<br><br><br>
</dl>
<h2>Data-driven bar color</h2>
<p>
<b>colorfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the color of each individual bar is controlled by this data field,
using
<a href="legendentry.html#legenddriven">
legend-driven technique
</a>
(the legend serves as a table mapping data values to colors).<tt> </tt>
An example:
<a href="../gallery/colorfld.htm">
colorfld
</a>
</dl>
<p>
<b>exactcolorfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the color of each individual bar is controlled by this data field directly.<tt> </tt>
The data field should hold recognized
<a href="color.html">
color names.<tt> </tt>
</a>
<br><br><br>
</dl>
<h2>Data-driven bar width</h2>
<p>
<b>barwidthfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, bar widths will be controlled by the contents of this field.<tt> </tt>
These values should be in scaled basic units for the axis that the bars are perpendicular to.<tt> </tt>
<br><br><br>
</dl>
<h2>Legends</h2>
<b>legendlabel</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
A label to be associated with the current set of bars in the legend.<tt> </tt>
<b>proc legend</b> must be executed later in order to
render the legend.
The <tt>\n</tt> construct can be used to force a line break,
or the label can be wordwrapped using proc legend wraplen attribute (2.32+).<tt> </tt>
If
<a href="getdata.html">
proc getdata field names
</a>
are being used,
the special symbol <tt>#usefname</tt> causes the field name of <tt>lenfield</tt>
to be automatically used as the legend label (2.04+).<tt> </tt>
<br>
Example: <tt>legendlabel: Northeast region</tt>
<br>
Example: <tt>legendlabel: #usefname</tt>
<br><br><br>
</dl>
<h2>Bar labels</h2>
Proc bars can label each bar. By default, labels will be rendered near the ends of bars.<tt> </tt>
You can make the label appear centered within the bar by specifying <tt>longwayslabel: yes</tt>
<br><br>
<p>
<b>showvalues</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, the plottable Y value will be displayed near the
end of each bar. Default is <tt>no</tt>. Text details may be
controlled using the <tt>labeldetails</tt> attribute (the <tt>adjust</tt>
subattribute may be used to control the location of the labels).<tt> </tt>
Numeric decimal format may be controlled by the <tt>numbersformat</tt>
attribute.<tt> </tt>
Example: <tt>showvalues: yes</tt>
</dl>
<p>
<b>numbersformat</b>
<a href="attributetypes.html#printfspec">
printfspec
</a>
<dl>
<dt> <dd>
Allows control over number decimal format presentation in bar labels.<tt> </tt>
Default is <tt>%g</tt>.<tt> </tt>
<br>
Example: <tt>numbersformat: %8.0f</tt>
</dl>
<p>
<b>labelzerovalue</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
Used with <tt>showvalues</tt>.<tt> </tt>
If <tt>yes</tt>, zero length bars will have a value label displayed.<tt> </tt>
Default is <tt>no</tt>, to not display any value for zero length bars.<tt> </tt>
</dl>
<p>
<b>labeldetails</b>
<a href="textdetails.html">
textdetails
</a>
<dl>
<dt> <dd>
Details concerning the appearance of the labelling (both end-of-bar
labels and longways labels).<tt> </tt>
Example: <tt>labeldetails: adjust=0,-0.3 size=6</tt>
</dl>
<p>
<b>labelword</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
Allows the <tt>showvalues</tt> label to be formatted.<tt> </tt>
The symbol <tt>@@N</tt> will be evaluated to value being plotted (the bar length).<tt> </tt>
May also be used to label bars with a constant.<tt> </tt>
Example: <tt>labelword: N=@@N</tt>
</dl>
<p>
<b>labelfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the contents of the data field <i>dfield</i> will be used as the label.<tt> </tt>
The text may include embedded <tt>@@N</tt> (see above) and
<tt>\n</tt> to symbolize newlines if longways labels are being done.<tt> </tt>
</dl>
<p>
<b>labelpos</b>
<a href="attributetypes.html#locvalue">
locvalue
</a>
<dl>
<dt> <dd>
If specified, controls the positioning of the labels.<tt> </tt>
For example, if doing vertical bars, this attribute would
control the vertical placement of bar labels.<tt> </tt>
<br>
Example: <tt>labelpos: min-0.2</tt>
</dl>
<p>
<b>backbox</b>
<a href="color.html">
color
</a>
<dl>
<dt> <dd>
If specified, a backing box of the given <i>color</i> will be
rendered behind each end-of-bar label (not done for longways labels).
This may be useful if the labels are hard to see because of bar color.<tt> </tt>
</dl>
<p>
<b>minlabel</b>
<a href="attributetypes.html#plotvalue">
plotvalue
</a>
<dl>
<dt> <dd>
If specified, labels are suppressed for bars of lesser magnitude than this.<tt> </tt>
Does not work with floating segment bars or bars in negative space.<tt> </tt>
</dl>
<p>
<b>labelrot</b>
degrees
<dl>
<dt> <dd>
Rotate bar labels by the given number of degrees.
This is subject to the text rotation ability of the current output device
<a href="fonts.html">
(see fonts)
</a>
</dl>
<p>
<b>labelmaxlen</b>
n
<dl>
<dt> <dd>
If specified, all bar labels are truncated to this length.
Two dots are appended to indicate truncation.
Multiline labels are considered one continuous string for this operation.<tt> </tt>
New in 2.33
</dl>
<p>
<b>labelselect</b>
<a href="select.html">
select expression
</a>
<dl>
<dt> <dd>
If specified, only labels for which the select expression is true will be rendered.<tt> </tt>
New in 2.33
</dl>
<p>
<b>longwayslabel</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, the label will be shown longways along the length of bars,
rather than near the ends of bars. This is the default for floating segment
bars, and may be useful in other types of bar graphs for showing long labels.<tt> </tt>
Label text may include embedded newlines symbolized by <tt>\n</tt>.<tt> </tt>
</dl>
<p>
<b>labelmustfit</b>
<tt>omit</tt> | <tt>truncate</tt> | <tt>no</tt>
<dl>
<dt> <dd>
Used only with longwayslabels (see above).<tt> </tt>
If <tt>omit</tt>, individual labels are omitted when label is too long to
fit within the bar, to allow larger segments
to be labelled, but not smaller segments (where labels would collide).
If <tt>truncate</tt>, labels are truncated to fit within the bar
(two dots are appended to indicate truncation)
Note, <tt>truncate</tt> does not apply to multi-line labels.. they will be omitted if too large.<tt> </tt>
New in 2.33
<br><br><br>
</dl>
<h2>Clickmaps and mouseover</h2>
<p>
<b>clickmapurl</b> <i>url template</i>
<dl>
<dt> <dd>
If generating a
<a href="clickmap.html">
clickmap,
</a>
this specifies a url template and causes the bar rectangles to be mapped.<tt> </tt>
This attribute usually contains one or more embedded
<a href="attributetypes.html#dfield">
data field references
</a>
preceded by double at-sign (@@). See
<a href="clickmap.html">
the clickmap manual page
</a>
for more details and examples.<tt> </tt>
<br>
Example: <tt>clickmapurl: http://abc.com/mycgi?category=@@3</tt>
<br><br>
</dl>
<p>
<b>clickmaplabel</b> <i>label template</i>
<dl>
<dt><dd><p>
If generating a
<a href="clickmap.html">
client-side clickmap,
</a>
this specifies a template for building mouseover text labels.<tt> </tt>
<br>
Example: <tt>clickmaplabel: @@3 (@@4)</tt>
</dl>
<p>
<b>clickmaplabeltext</b>
<a href="attributetypes.html#text">
multiline text
</a>
<dl>
<dt> <dd>
Same as <tt>clickmaplabel</tt> but multiline text. Must be terminated with a blank line.<tt> </tt>
<br><br><br>
</dl>
<h2>Specialized</h2>
<p>
<b>constantlen</b>
<i>h</i>
<dl>
<dt><dd><p>
Draw all bars to a constant length <i>h</i>, in scaled units.<tt> </tt>
<br><br>
</dl>
<p>
<b>constantloc</b>
<i>h</i>
<dl>
<dt><dd><p>
Place all bars at location <i>h</i>, in scaled units (may be useful for segments).<tt> </tt>
<br><br>
</dl>
<p>
<b>reverseorder</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, and bars are being located in consecutive unit locations
(i.e. no <tt>locfield</tt> specified), bars will be placed in reverse order.<tt> </tt>
<br><br>
</dl>
<p>
<b>colorlist</b>
<i>list</i>
<dl>
<dt> <dd>
Allows bars to be rendered in multiple colors, or make selected bars a different
color than the rest.<tt> </tt>
It can operate in one of two ways.<tt> </tt>
<dt> <dd>
1) if <i>list</i> is a space-separated list of
<a href="color.html">
color names
</a>
then the individual bars will be rendered using these colors.<tt> </tt>
<br>
Example: <tt>colorlist: red yellow blue green</tt>
<br>
The leftmost bar will be red, the second yellow, and so on.<tt> </tt>
If there are more bars then given colors,
the remaining bars will be rendered using the default color, e.g.<tt> </tt>
the value given in the <tt>color</tt> attribute.
A gallery example where this was done is
<a href="../gallery/timeline1a.htm">
timeline1a
</a>
<dt> <dd>
2) <i>list</i> may be some number of pairs having the form
<i>n</i>
<a href="color.html">
color
</a>
where <i>n</i> is an integer.
<br>
Example: <tt>colorlist: 4 yellow 8 pink</tt>
<br>
The fourth bar from the left will be yellow; the eighth pink.<tt> </tt>
All other bars will be rendered using the default color, e.g.<tt> </tt>
the value given in the <tt>color</tt> attribute.
A gallery example where this was done is
<a href="../gallery/hbars1.htm">
timeline1a
</a>
<dt> <dd>
Any legend entries for the various colors must be
done explicitly using proc legendentry.<tt> </tt>
<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 <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12"
width="120" height="30" border="0"
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>
</center>
</dl>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
19
