DESCRIPTION

VERTICAL or HORIZONTAL BARS

FEATURES

HTML clickmap support for the bars.

EXAMPLES

UNPLOTTABLE DATA

PREREQUISITES

MODES

Bars can be generated from data using one of several modes (remember to reverse X and Y in these descriptions if doing horizontal bars):

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

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

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.

Error bars:

By specifying lenfield and errbarfields error bars centered on the Y values in lenfield are produced. 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 (stacked bar graphs require that the data be organized such that all components of a bar be located on the same data row). 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.

MANDATORY ATTRIBUTE

ATTRIBUTES

(Remember to reverse X and Y in these descriptions if horizontal bars are being generated.)

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

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 color

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.

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. 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 (new in 2.04).
Example: legendlabel: Northeast region
Example: legendlabel: #usefname

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

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

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.

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.

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. Stacked bar graphs require that the data be organized such that all components of a bar be located on the same data row.
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.

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

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

truncate yes | no

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

segmentfields [ start-dfield ] stop-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

errbarfields errlowfield [ 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 be symmetrical. See also errbarmult.
Example: errbarfields: 3

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

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 .

select conditional-expression

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.

colorfield dfield

If specified, the color of each individual bar to be controlled by this data field, using legend-driven technique . An example: colorfld

colorlist list

Allows bars to be rendered in multiple colors. It can operate in one of two ways.

1) if list is a space-separated list of colors 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 hbars1

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

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.

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

clickmapurl url template

If generating an HTML 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 HTML clickmap for more details and examples.
Example: clickmapurl: http://abc.com/mycgi?category=@@3

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

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.