Manual page for proc_bars(PL)
proc bars uses data to draw bargraphs, histograms, error bars,
or segment bars, in
the vertical or horizontal directions.
VERTICAL vs. HORIZONTAL BARS
Bars can be vertical or horizontal.
This is controlled by the horizontalbars or axis attributes.
For the purposes of the descriptions herein, we will
assume vertical bars. Everything works essentially
the same way for horizontal bars, except that
X and Y should be read as reversed in the descriptions.
Stacked bars, clusters of bars, various labeling options, and variable bar width.
See the Gallery Bars examples
Invalid data points are omitted.
If truncate is set to yes, then
bars extending beyond the plotting area are truncated to the
limit of the plotting area;
if both the minima and the maxima of a bar segment or error bar
lie outside of the plotting area, the bar is omitted with a warning.
A plotting area must be set up using proc areadef
and proc getdata must be executed to
access or define some data.
Bars can be generated from data using one of several modes
(remember to reverse X and Y in these descriptions if doing
Bars "where they fall":
By specifying lenfield but not locfield, bars
are graphed at consecutive unit locations in X.
The length of bars is controlled by the plottable values found
Bars at specified locations:
By specifying both lenfield and locfield,
bars are produced at the X locations found in locfield
and the length of bars is controlled by the plottable values found
Bar segments (to show ranges):
By specifying segmentfields, bars will be drawn
as segments between two plottable values, to show ranges.
This mode may be used with or without locfield,
and lenfield is not applicable.
By specifying lenfield and errbarfields
error bars centered on the Y values in lenfield
This mode may be used with or without locfield.
The length of the error bars is
controlled by the values in the errbarfields
(which have presumably been precomputed; use proc rangebar
to caluclate mean/standard deviation and draw bars).
The color & style of the error bar line can be
controlled using the thinbarline attribute.
Stacked and/or clustered bars:
proc bars draws one set of bars per invocation.
Stacked and clustered bars may be done using multiple invocations.
To do the upper portions of a stacked bargraph, the stackfields
attribute controls what data the bars are to be placed above.
To do clustered bars, the cluster attribute is used.
Very thin bars / histograms:
The thinbarline attribute should be used when very thin line bars
are desired and to specify style for error bar lines.
The lenfield attribute MUST be specified.
(Remember to reverse X and Y in these descriptions if
horizontal bars are being generated.)
The contents of this data field will be used to control bar length.
These should be plottable values in Y.
Example: lenfield: 2
The contents of this data field will be used to control bar location in X.
These should be plottable values in X.
If locfield is not specified, bars will be located at consecutive
unit locations in X.
Example: locfield: 1
horizontalbars yes | no
If yes, bars will be horizontal.
Otherwise, bars will be vertical.
Example: horizontalbars: yes
axis x | y
Has the same effect as the horizontalbars attribute.
Specifies the axis that the bar lengths will be plotted against.
Use y to produce vertical bars (the default),
or x to produce horizontal bars.
Example: axis: x
Color of the bars. Example: color: green
If bars are very thin, or error bars are being done, the
color is specified via the thinbarline attribute.
The hatchN color values may be useful when working
in Postscript monochrome. See also the colorlist
and colorfield attributes.
A label to be associated with the current set of bars in the legend.
proc legend must be executed later in order to
render the legend.
If yes or a linedetails specification, causes bars to be outlined
with a line. If no or none, no outline is produced.
Default is yes, which gives a thin black outline.
Example: outline: color=blue
Example: outline: no
Width of bars in
. If not specified width will be determined based on scaling,
but this may not always be satisfactory. For very thin bars
use thinbarline (see below).
| yes | no
If specified, bars will be rendered as lines with the given properties.
yes 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.
barsrange min [max]
If specified, and if locfield is used to position bars,
bars will only appear if the value in locfield is within
this range. If only one value is given it is taken as the minima.
If specified, causes current set of bars to be placed on top
of earlier sets.
If * is given, it is taken to mean "stack this set of bars on top of
all previously plotted bars" (same area, same cluster member).
Fields may be specified explicitly (see the examples).
Max number of stackable fields is 40. * is new in version 1.34.
Example: stackfields: *
Example: stackfields: 3 4 5
cluster position / nmembers
If specified, causes the current set of bars to be rendered as a
member of a cluster. position indicates which member of the
cluster is being done (1 = leftmost). nmembers
indicates how many bars are in each cluster.
Example: cluster: 1 / 4 would be used to render the
first set of bars where clusters of 4 are being done.
You can also say cluster: 1 of 4 if you prefer.
If specified when doing clustered bars, members of each cluster
are separated from each other by n
Default is 0.0 (bars butted up against one another).
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.
Example: crossover: 0
truncate yes | no
If yes, bars and labels will be truncated to the plotting area.
Default is no.
[ start-dfield ]
If specified, causes segment bars to be rendered rather than
length-based bars. These are typically used to display ranges
(but should not be confused with proc rangebar which computes
and displays percentiles).
Each bar will be drawn from the data value in start-dfield
to the data value in the stop-dfield.
Example: segmentfields: 1 3
[ errhifield ]
If specified, causes error bars to be rendered rather than
length based bars. lenfield must also be specified.
A thin error bar with tails is drawn from the value in lenfield,
downward for the distance located in errlowfield, and then
upward for the distance located in errhifield.
If errhifield is not given, the error bar is assumed to
See also errbarmult.
Example: errbarfields: 3
If specified, error bars will be drawn to n times the distance
given in the data. Useful for drawing error bars showing 2 x standard error.
If specified, tails of length n (in
rendered at the top and bottom of each bar. Typcially used
with error bars. Tails of a default length are automatically
rendered if errbarfields is used.
Example: tails: 0.2
If specified, a left-pointing, centered, or right-pointing tic mark
will be displayed at the value in dfield. The tics are drawn
on top of the bars using the current line (outline or thinbarline), beginning
in the center of the bar.
Length is set by attribute ticlen, which sets the tick length
Allows data rows to be selected for inclusion
using a selection expression.
reverseorder yes | no
If yes, and bars are being located in consecutive unit locations
(i.e. no locfield specified), bars will be placed in reverse order.
Allows bars to be rendered in multiple colors, the color being determined by data.
This attribute specifies a field in the data that will control the color
of the bar being drawn. Beforehand,
must be invoked to set up one or more legend entries.
A tag must be supplied with each. These tags correspond to the
contents of the color lookup field. See this example:
Allows bars to be rendered in multiple colors.
It can operate in one of two ways.
1) if list is a space-separated
then the individual bars will be rendered using these colors.
Example: colorlist: red yellow blue green
The leftmost bar will be red, the second yellow, and so on.
If there are more bars then given colors,
the remaining bars will be rendered using the default color, e.g.
the value given in the color attribute.
A gallery example where this was done is
2) list may be some number of pairs having the form
where n is an integer.
Example: colorlist: 4 yellow 8 pink
The fourth bar from the left will be yellow; the eighth pink.
All other bars will be rendered using the default color, e.g.
the value given in the color attribute.
A gallery example where this was done is
Any legend entries for the various colors must be
done explicitly using proc legendentry.
(This attribute is new with version 1.32)
If specified, bar widths will be controlled by the contents of this field.
These values should be in scaled basic units for the axis that the bars are perpendicular to.
hidezerobars yes | no
If yes, bars that are zero-length will not be drawn at all.
Default is no (zero length bars may be visible as a thin line).
New in version 1.40.
BAR LABELING OPTIONS
One label may be rendered per bar. It may be a value label
(showvalues), or label taken from a data field.
showvalues yes | no
If yes, the plottable Y value will be displayed near the
end of each bar. Default is no. Text details may be
controlled using the labeldetails attribute (the adjust
subattribute may be used to control the location of the labels).
Numeric decimal format may be controlled by the numbersformat
Example: showvalues: yes
Allows control over number decimal format presentation in bar labels.
Default is %g. (New in 1.36)
Example: numbersformat: %8.0f
labelzerovalue yes | no
Used with showvalues.
If yes, zero length bars will have a value label displayed.
Default is no, to not display any value for zero length bars.
Details concerning the appearance of the labelling (both end-of-bar
labels and longways labels).
Example: textdetails: adjust=0,-0.3 size=6
Allows the showvalues label to be formatted.
The symbol @@N will be evaluated to the plottable value.
May also be used to label bars with a constant.
Example: labelword: N=@@N
If specified, the contents of the data field dfield will be used as the label.
The text may include embedded @@N (see above) and
\n to symbolize newlines if longways labels are being done.
If specified, controls the positioning of the labels.
For example, if doing vertical bars, this attribute would
control the vertical placement of bar labels.
(This attribute is new with version 1.33).
Example: labelpos: min-0.2
If specified, a backing box of the given color 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.
longwayslabel yes | no
If yes, the label will be shown longways along the length of bars,
rather than near the tops. This may be useful for showing longer labels.
Label text may include embedded newlines symbolized by \n.
data display engine
Copyright Steve Grubb