help beamplot


beamplot -- Horizontal dotplots using beams


beamplot varlist [if] [in] [, options]

beamplot varname [if] [in] , over(varname) [options]

options Description ------------------------------------------------------------------------- Main plot height() control height of dotplots width() control bin width of dotplots floor bins defined by floors of intervals ceiling bins defined by ceilings of intervals over() separate dotplots, same panel by() separate dotplots, separate panels summary() change summary from mean variablelabels use variable labels on vertical axis twoway_options control other features of graph

Details of dots, beam and fulcrum dots() change details of dots display beam() change details of beam display fulcrum() change details of fulcrum display

Add plot addplot(plot) add other plots to the generated graph



beamplot produces horizontal dotplots using beams. The dots represent individual data points, possibly rounded slightly within bins. The beams extend from minimum to maximum for each group or variable plotted. Each beam rests on a fulcrum, by default at the mean of its data.

Many standard texts explain that the mean is the centre of gravity of a distribution, motivating a display of data with the mean shown as a fulcrum. For examples, see Hays (1963. pp.163-165), Mosteller et al. (1970, p.200), Hays and Winkler (1971, pp.144-146), Helsel and Hirsch (1992, p.5), Freedman, Pisani and Purves (1998, pp.61-66), Wild and Seber (2000, pp.63-64), Dekking et al. (2005, pp.90-91) or Moore and McCabe (2006, pp.68-69). See also Doane and Tracy (2000). The author would be most grateful for other references, especially if older or excellent.


+-----------+ ----+ Main plot +--------------------------------------------------------

height() specifies the height of each dotplot as a fraction of the distance between beams. Default 0.6.

width() specifies the bin width of dotplots. Data are by default rounded to round(data,width) before any calculation or display. That is, the minima, maxima and summaries shown are those of the rounded data, not those of the original data. (Experience indicates that rounding the data, but not the extremes and summaries, is disconcerting rather than helpful.) See also floor and ceiling below.

floor or ceiling in conjunction with width() specifies rounding by width * floor(varname/width) or width * ceil(varname/width) respectively. Only one may be specified. (These options are included to give some users the minute control they may desire, but if either option produces a marked difference in your plot, you may be rounding too much.)

over() produces separate dotplots, in the same graph panel, according to the distinct values of the variable specified. This option is allowed only with a single varname.

by() produces separate dotplots, in different graph panels, according to the distinct values of the variable specified.

summary() changes the summary measure for which a fulcrum is shown for each beam from the default of mean. Any summary for which an egen function exists may be chosen.

variablelabels specifies that variable labels, rather than variable names, should be used on the vertical axis. This may be useful when dotplots for several variables are being shown in a panel.

twoway_options} are options of graph twoway controlling other features of the graph.

+-----------------------------------+ ----+ Details of dots, beam and fulcrum +--------------------------------

dots() is a holder for options of twoway scatter that change the details of the display of dots. The defaults include ms(0) yla(, nogrid notick). For example, dots(msize(small)) produces small markers.

beam() is a holder for options of twoway rspike that change the details of the display of each beam. For example, beam(lcolor(none)) makes the beam invisible.

fulcrum() is a holder for options of twoway pcarrow that change the details of the display of each fulcrum. The defaults include msize(medlarge) barbsize(medlarge). For example, fulcrum(lcolor(none) mcolor(none)) makes the fulcrum invisible.

(If you like beamplot, but prefer to omit beam and fulcrum, you should be using dotplot or stripplot instead.)

+----------+ ----+ Add plot +---------------------------------------------------------

addplot(plot) provides a way to add other plots to the generated graph. See addplot option.


. beamplot mpg . beamplot mpg, over(rep78) . beamplot mpg, by(foreign) . beamplot mpg, by(foreign) over(rep78)

. beamplot length, over(grade) width(25) note(bin width 25 m) height(0.4) xti("Cirque length, m") . beamplot length width wallht, w(25) note(bin width 25 m) height(1.5) yla(1.3 "length" 2.3 "width" 3.3 "wall height") xtitle("cirque dimensions, m") fulcrum(mcolor(red))


Vince Wiggins made encouraging noises. Richard T. Campbell helped considerably in identifying references to Hays' work.


Nicholas J. Cox, Durham University


Dekking, F.M., C. Kraaikamp, H.P. Lopuhaš and L.E. Meester. 2005. A modern introduction to probability and statistics: understanding why and how. London: Springer.

Doane, D.P. and R.L. Tracy. 2000. Using beam and fulcrum displays to explore data. The American Statistician 54: 289-90.

Freedman, D., R. Pisani and R. Purves. 1998. Statistics. New York: W.W. Norton.

Hays, W.L. 1963. Statistics for psychologists. New York: Holt, Rinehart and Winston.

Hays, W.L. and R.L. Winkler. 1971. Statistics: Probability, inference, and decision. New York: Holt, Rinehart and Winston.

Helsel, D.R. and R.M. Hirsch. 1992. Statistical methods in water resources. Amsterdam: Elsevier.

Moore, D.S. and G.P. McCabe. 2006. Introduction to the practice of statistics. New York: W.H. Freeman.

Mosteller, F., R.E.K. Rourke and G.B. Thomas. 1970. Probability with statistical applications. Reading, MA: Addison-Wesley.

Wild, C.J. and G.A.F. Seber. 2000. Chance encounters: a first course in data analysis and inference. New York: John Wiley.

Also see

Manual: [G] twoway, [R] dotplot

Online: twoway, dotplot, stripplot (if installed)