ploticus: proc bars

## proc bars | Welcome Gallery Handbook |
| Manual page for proc_bars(PL)

## DESCRIPTION

proc bars uses data to draw bargraphs, histograms, error bars, or segment bars, in the vertical or horizontal directions.``

## VERTICAL or 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.``

## FEATURES

Stacked bars, clusters of bars, various labeling options, and variable bar width.``

HTML clickmap support for the bars.``

## EXAMPLES

See the Gallery Bars examples and

## UNPLOTTABLE DATA

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

## PREREQUISITES

A plotting area must be set up using proc areadef and proc getdata must be executed to access or define some data.``

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

The `lenfield` attribute MUST be specified.``

## 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 `hatch`N 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`.``
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 10, 2002.