Search


Ploticus > Scripts >

proc bars

proc bars draws bargraphs, histograms, error bars, or segment bars using the current data set, in the current plotting area. Bars can be vertical or horizontal, and can be stacked and/or clustered. Clickmaps and mouseover text labels are supported. See also the gallery examples for vertical bars, horizontal bars, and error bars.

Please note: Everywhere in this page, descriptions are written with vertical bars in mind.. remember to reverse sense of X and Y in these descriptions if doing horizontal bars.

Attributes

The lenfield attribute must always be specified. The locfield attribute is usually given.

Bar location and lengths

lenfield     dfield

The contents of this data field will be used to control bar length. These should be plottable values in Y. Example: lenfield: 2

locfield     dfield

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

Vertical or horizontal

horizontalbars     yes | no

If yes, bars will be horizontal. Otherwise, bars will be vertical. Example: horizontalbars: yes

An older attribute called axis also exists to do this... axis: x would produce horizontal bars.

Basic bar appearance details

barwidth     n

Width of bars in absolute units. 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).

color     color

If specified, all bars will be rendered in this color. Example: color: green If bars are very thin, or error bars are being done, the color is specified via the thinbarline attribute. The hatch color values may be useful when working in Postscript monochrome. See also the colorlist and colorfield attributes.

outline     linedetails

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

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

truncate     yes | no

If yes, bars and labels will be truncated to the plotting area. Default is no.

crossover     plotvalue

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

Omitting certain bars

select     select expression

Allows data rows to be selected for inclusion using a selection expression.
Example: select: @@3 = B

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.

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

Stacked bars

stackfields     *
or
stackfields     dfield1 dfieldn

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. Note: 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 selects cannot be used for the different layers of bars).
Example: stackfields: *
Example: stackfields: 3 4 5

Clusters of bars

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.

clustersep n

If specified when doing clustered bars, members of each cluster are separated from each other by n absolute units Default is 0.0 (bars butted up against one another).

Floating segment bars

segmentfields     [ start-dfield ]     stop-dfield

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 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. It's possible to render error bars with this attribute by using the thinbarline and tails attributes as well.
Example: segmentfields: 1 3

Error bars

Note, the color, thickness, dash pattern (etc) of error bars is controlled using the thinbarline attribute.

errbarfields     errlowfield     [ errhifield ]

If specified, causes error bars to be rendered rather than length based bars. lenfield must also be specified. Spacing between error bars is controlled by barwidth (as if there were ordinary bars accompanying the error bars). 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 be symmetrical. You can do one-way error bars by giving an errlowfield of 0 and specifying errhifield. See also segmentfields, which you can use to draw error bars based on actual rather than relative values. See also errbarmult.

errbarmult     n

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.

tails     n

If specified, tails of length n (in absolute units ) are 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

High - low - close bars

leftticfield     dfield

midticfield     dfield

rightticfield     dfield

ticlen     h

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 to h absolute units.

Data-driven bar color

colorfield     dfield

If specified, the color of each individual bar is controlled by this data field, using legend-driven technique (the legend serves as a table mapping data values to colors). An example: colorfld

exactcolorfield     dfield

If specified, the color of each individual bar is controlled by this data field directly. The data field should hold recognized color names.

Data-driven bar width

barwidthfield     dfield

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.

Legends

legendlabel     text

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. The \\n construct can be used to force a line break, or the label can be wordwrapped using proc legend wraplen attribute (2.32+). If proc getdata field names are being used, the special symbol #usefname causes the field name of lenfield to be automatically used as the legend label (2.04+).
Example: legendlabel: Northeast region
Example: legendlabel: #usefname

Bar labels

Proc bars can label each bar. By default, labels will be rendered near the ends of bars. You can make the label appear centered within the bar by specifying longwayslabel: yes

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 attribute. Example: showvalues: yes

numbersformat     printfspec

Allows control over number decimal format presentation in bar labels. Default is %g.
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.

labeldetails     textdetails

Details concerning the appearance of the labelling (both end-of-bar labels and longways labels). Example: labeldetails: adjust=0,-0.3 size=6

labelword     text

Allows the showvalues label to be formatted. The symbol @@N will be evaluated to value being plotted (the bar length). May also be used to label bars with a constant. Example: labelword: N=@@N

labelfield     dfield

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.

labelpos     locvalue

If specified, controls the positioning of the labels. For example, if doing vertical bars, this attribute would control the vertical placement of bar labels.
Example: labelpos: min-0.2

backbox     color

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.

minlabel     plotvalue

If specified, labels are suppressed for bars of lesser magnitude than this. Does not work with floating segment bars or bars in negative space.

labelrot     degrees

Rotate bar labels by the given number of degrees. This is subject to the text rotation ability of the current output device (see fonts)

labelmaxlen     n

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. New in 2.33

labelselect     select expression

If specified, only labels for which the select expression is true will be rendered. New in 2.33

longwayslabel     yes | no

If yes, 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. Label text may include embedded newlines symbolized by \\n.

labelmustfit     omit | truncate | no

Used only with longwayslabels (see above). If omit, 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 truncate, labels are truncated to fit within the bar (two dots are appended to indicate truncation) Note, truncate does not apply to multi-line labels.. they will be omitted if too large. New in 2.33

Clickmaps and mouseover

clickmapurl url template

If generating a clickmap, this specifies a url template and causes the bar rectangles to be mapped. This attribute usually contains one or more embedded data field references preceded by double at-sign (@@). See the clickmap manual page for more details and examples.
Example: clickmapurl: http://abc.com/mycgi?category=@@3

clickmaplabel label template

If generating a client-side clickmap, this specifies a template for building mouseover text labels.
Example: clickmaplabel: @@3 (@@4)

clickmaplabeltext     multiline text

Same as clickmaplabel but multiline text. Must be terminated with a blank line.

Specialized

constantlen     h

Draw all bars to a constant length h, in scaled units.

constantloc     h

Place all bars at location h, in scaled units (may be useful for segments).

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.

colorlist     list

Allows bars to be rendered in multiple colors, or make selected bars a different color than the rest. It can operate in one of two ways.

1) if list is a space-separated list of color names 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 timeline1a

2) list may be some number of pairs having the form n color 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 timeline1a

Any legend entries for the various colors must be done explicitly using proc legendentry.