## proc bars

Version 2.32
Scripts

Manual page for proc_bars(PL)

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

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`

## 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` N 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 `select`s 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

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, and bar labeling

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`

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

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

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

Markup created by unroff 1.0, `` `` August 23, 2005.