Horizontal bar charts ---------------------
^hbar^ varlist [^if^ exp] [^in^ range] [ ^,^
^a^xtol^(^#^) b^arfrac^(^#^) c^start^(^#^) gapm^ag^(^#^) gap^s^(^string^)^ ^o^penbar^(^string^) sh^ading^(^string^) so^rt^(^string^)^
^bo^rder ^f^ormat^(^format^) lap nox^axis ^noy^axis ^tti^ck ^vallbl(^varnam > e^)^ ^xla^bel^(^string^) xli^ne^(^string^) xsc^ale^(^string^) xti^ck^(^string^)^
^bl^ank ^gl^egend^(^string^) gllj glp^os^(^#^) l^egend^(^legendvar^)^ ^rl^egend^(^rlegendvar^) rllj rlp^os^(^#^)^
^flipt nit2 t1m(^#^) t1^title^(^string^) t2m(^#^)^ ^t2^title^(^string^) tim(^#^) ti^tle^(^string^)^
^vap v^at^(^string^) vatp^os^(^#^) vatf^mt^(^format^)^
^fontr(^#^) fontc(^#^) fontrb(^#^) fontcb(^#^)^ ^pe^n^(^string^) pent^ext^(^#^) sa^ving^(^graph_filename^)^ ]
Description -----------
^hbar^ produces a horizontal bar chart for varlist. Bars for different variables are stacked with base at 0, depending on whether values are positive or negative. Optionally, bars may be horizontal lines with or without vertical lines at either or both ends.
If the data allow it, a different base may be forced using the ^xscale^ option.
A legend on the left of the data region can be from a specified variable. If that variable is not specified, the order in the data will be used; or, if that is not desired, the legend can be blank. The legend is right-justified. The legend should look readable up to about 30 observations.
Bars of length 0 are not plotted.
For understanding placement of material on the plot, it helps to know that @gph@ draws in a space defined by 23063 rows and 32000 columns with origin at top left. See help for @gph@.
Options --------
Options controlling size, layout and bar characteristics: ---------------------------------------------------------
^axtol(^#^)^ controls the space between the x axis or the position of the top border and the nearest data line. Default 600.
^barfrac(^#^)^ is the fraction of vertical space within the data region taken up by bars. The default is 0.6. A value of 1 produces touching bars, so that (e.g.) population pyramids may be produced or groups of bars produced with the use of ^gaps^.
^cstart(^#^)^ controls the column (horizontal position) of the start of the bars.
^gapmag(^#^)^ controls the magnitude of any gaps relative to the spacing between bars. Default 1.
^gaps(^string^)^ places gaps after bars. ^gaps(3,6)^ places gaps after the 3rd and 6th bars as they appear on the graph, counting down from the top. ^0^ means a gap before the first bar.
^openbar(^string^)^ is an option that is relevant if any of the bars is shaded ^.^ (that is, empty). Bars next to the y axis (or its position) may be drawn open on the axis side (left for positive values, right for negative), allowing some special effects. In particular, a bar straddling the y axis (or its position) may be produced by dividing the variable into a negative and a positive part and leaving both bars open, so that they combine to form a single bar. ^y^ specifies an open bar and any other character (say ^n^) specifies the default. For example,
. ^hbar pos neg, sh(..) o(yy) noy^ . ^hbar verysat satis neutpos neutneg diss verydiss, sh(31..13)^ ^o(nnyynn) noy^
^shading(^#^)^ controls bar shading. The list is the standard list for @gph@, with the addition of ^.^, ^n^, ^l^, ^L^, ^r^, ^R^, ^b^ and ^B^.
^n^ no bar ^.^ no shading (empty bar) ^0^ lightest ... ^4^ darkest
horizontal lines instead of bars:
^-^ no vertical lines at end ^l^ small vertical line at left (half bar height) ^L^ longer vertical line at left (bar height) ^r^ small vertical line at right (half bar height) ^R^ longer vertical line at right (bar height) ^b^ small vertical lines at both ends (half bar height) ^B^ longer vertical lines at both ends (half bar height)
If you use ^sh(n)^ and ^pen( )^ and/or ^openbar( )^, specify some choice for ^pen( )^ and/or ^openbar( )^, even though it will be ignored. For example, ^hbar y foo x, sh(0n4) pe(345)^ specifies that two variables ^x^ and ^y^ are plotted at shading 0 and 4 and at pens 3 and 5. The space between their bars is given by ^foo^, but the pen choice of 4 is just a dummy, because no bar will be drawn.
^sort(^string^)^ means that observations are to be plotted in the vertical order determined by application of @gsort@. For example, ^sort(^sortvar^)^ indicates sort in ascending order of sortvar (highest values on bottom) and ^sort(- ^sortvar^)^ indicates descending order (highest values on top).
Options controlling axes, lines, labels, ticks, border: -------------------------------------------------------
^border^ adds a border.
^format(^format^)^ controls the format with which ^xlabel^s are shown. Default %1.0f.
^lap^ (^l^abels ^a^ll ^p^ositive) makes the labels as shown all positive. ^xla(-40,-20,0,20,40) lap^ will place the labels 40, 20, 0, 20, 40 at the axis positions for -40, -20, 0, 20, 40.
^noxaxis^ suppresses the x axis.
^noyaxis^ suppresses the y axis.
^ttick^ produces short unlabelled ticks on the border above the x axis that echo the labelled and unlabelled ticks on the x axis. Note that (unlike the option in @graph@) ^ttick^ with a string is illegal, and that ^ttick^ necessarily implies ^border^, but not conversely.
^vallbl(^varname^)^ specifies that the value labels associated with varname should be used in labelling the x axis.
^xlabel(^string^)^ controls the labelled ticks on the x axis. Note that (unlike the option in @graph@) ^xlabel^ without a string is illegal. numlists may be used, such as ^1/5^ for ^1,2,3,4,5^ and ^0(10)50^ for ^0,10,20,30,40,50^.
^xline(^string^)^ specifies lines drawn for constant values of x. Note that (unlike the option in @graph@) ^xline^ without a string is illegal. numlists may be used, such as ^1/5^ for ^1,2,3,4,5^ and ^0(10)50^ for ^0,10,20,30,40,50^.
^xscale(^string^)^ controls the scale of the graph, except that (like the option in @graph@) it will not cause values to be omitted (for which purpose use ^if^). ^xscale(^min, max^)^ will force bars to begin at min so long as 0 <= min <= minimum positive total, or at max so long as maximum negative total <= max <= 0.
^xtick(^string^)^ controls the unlabelled ticks on the x axis. Note that (unlike the option in @graph@) ^xtick^ without a string is illegal. numlists may be used, such as ^1/5^ for ^1,2,3,4,5^ and ^0(10)50^ for ^0,10,20,30,40,50^.
Options controlling legends to left, right and between gaps: ------------------------------------------------------------
^blank^ blanks out any legend on the left of the data region.
^glegend(^string^)^ places right-justified legend in the gaps between bars. ^gaps(0,4) glegend(Males!Females)^ places ^Males^ in the gap before bar 1 and ^Females^ in the gap after bar 4. Note that ^!^ must be used to separate legends, which thus enables the use of commas within the legend, but has the side-effect of disallowing the use of exclamation marks. ^.^ has the special meaning of blank.
^gllj^ makes ^glegend^ left-justified.
^glpos(^#^)^ controls the horizontal position of ^glegend^ and defaults to an alignment with the main legend.
^legend(^legendvar^)^ specifies a variable to be used for the legend. If legendvar is a numeric variable with labels, the labels will be used in the legend.
^rlegend(^rlegendvar^)^ specifies a variable to be used for the right legend. If rlegendvar is a numeric variable with labels, the labels will be used in the legend. `Right' here is indicative, not definitive, and refers to the default position, which may be altered by ^rlpos(^#^)^. By default, the right legend is right-justified.
^rllj^ makes ^rlegend^ left-justified.
^rlpos(^#^)^ controls the horizontal position of the right legend. Default ^rlpos(31500)^.
Options controlling titles (^t1title^, ^t2title^, ^title^): -----------------------------------------------------
^flipt^ flips titles: ^title^ will be shown at its (default larger) font size and left-justified at the top of the graph, and ^t1title^ will be shown at default font size and centred below the axis at the bottom of the graph (but closer to the axis than the default).
^nit2^: see ^t2title^ below.
^t1title(^string^)^ controls the ^t1title^, shown at default font size and left-justified at the top of the graph. But see ^flipt^ above.
^t2m(^#^)^ moves the ^t2title^ bodily # to the right. The default is to start hard left to allow plenty of space for several variable labels or names in a key, but that default may seem too far left.
^t2title(^string^)^ controls the ^t2title^, shown at default font size and left-justified at the top of the graph. This defaults to a key of shadings if the number of variables is more than 2: the key, however, is likely to be a mess if the number is more than 5. The key uses variable labels, or variable names if either they do not exist or the further option ^nit2^ is invoked. As with @graph@, ^" "^ blanks out the title.
^tim(^#^)^ moves the ^title^ bodily # to the right. The default is to centre at whatever column would bisect the x axis.
^title(^string^)^ controls the ^title^, shown at its (default larger) font size and centred below the axis at the bottom of the graph. But see ^flipt^ above. As with @graph@, ^" "^ blanks out the title.
Options controlling values shown as text: -----------------------------------------
^vap^ (^v^alues ^a^s ^p^ositive) makes the values as shown all positive.
^vat(^string^)^ specifies that numeric values are shown as text with format ^vatfmt^. This reinforces the role of the plot as a graphical table allowing look-up of individual values when desired.
The string may contain
^L^ left of bar and outside it ^l^ left of bar and inside it ^R^ right of bar and outside it ^r^ right of bar and inside it ^N^ at bar-end nearer to y axis and outside it ^n^ at bar-end nearer to y axis and inside it ^F^ at bar-end further from y axis and outside it ^f^ at bar-end further from y axis and inside it ^m^ middle of bar ^e^ elsewhere (precisely, at ^vatpos^) ^.^ do not show values
The default is ^.^ for all variables.
^vatpos(^#^)^ controls the horizontal position at which values given as text under ^vat(e)^ are shown. The default of 31500 places values at the far right of the display. Note that ^xscale^ can be used to clear enough space.
^vatfmt(^format^)^ controls the format with which values given as text are shown. Default %1.0f.
Other graph options: --------------------
^fontr(^#^)^ and ^fontc(^#^)^ control the font used for all but the main title and default to 570 and 290 (which is the default of @gph@). Font sizes should be changed circumspectly.
^fontrb(^#^)^ and ^fontcb(^#^)^ control the font used for the main title and default to 923 and 444.
^pen(^string^)^ controls the pens used for data.
^pentext(^#^)^ controls the pen used for text and other non-data elements.
^saving(^graph_filename^)^ saves the graph in a .gph file.
Examples --------
. ^hbar reserves, l(area) xla(0(5)30)^ ^t1(percent of total) ti(Oil reserves 1994) flipt border^
. ^hbar area, l(name) xsc(0,6.2) xla(0/6) t1(million square^ ^km) ti(Areas of major drainage basins) flipt fontr(500)^ ^fontc(250) border xti(0.5(1)5.5) so(-area)^
Remarks -------
In addition to the options above, many choices are coded into ^hbar^ as parameter values. Users may want to copy ^hbar^ and then edit these permanently or temporarily according to taste.
Author ------ Nicholas J. Cox, University of Durham, U.K. n.j.cox@@durham.ac.uk
Acknowledgments ---------------
Arne Kolstad and Fred Wolfe made very helpful comments.
Also see --------
On-line: help for @graph@, @gph@, @format@, @gsort@, @tabhbar@ (if installed), @hplot@ (if installed), @numlist@