{smcl}
{* 27oct2004/26sep2005/22jan2007/7jul2009/24jul2009/25nov2009/30nov2009/10dec2009/14jun2010/14dec2010/1mar2011/11oct2011}{...}
{hline}
help for {hi:tabplot}
{hline}

{title:Two-way table or one-way table shown as table of bars} 

{p 8 17 2} 
{cmd:tabplot}
{it:rowvar}
{it:colvar}
[{cmd:if} {it:exp}] 
[{cmd:in} {it:range}]
[{it:weight}]
[
{cmd:,}
[ 
{cmdab:fr:action} {c |}   
{cmdab:fr:action(}{it:varlist}{cmd:)} {c |}
{cmdab:perc:ent} {c |}
{cmdab:perc:ent(}{it:varlist}{cmd:)} 
] 
{cmdab:miss:ing}
{cmd:yasis xasis}
{cmdab:h:eight(}{it:#}{cmd:)} 
{cmdab:show:val}[{cmd:(}{it:specification}{cmd:)}] 
{cmdab:min:imum(}{it:#}{cmd:)} 
{cmdab:max:imum(}{it:#}{cmd:)} 
{cmdab:sep:arate(}{it:sepspec}{cmd:)} 
{cmd:bar1(}{it:rbar_options}{cmd:)} 
...
{cmd:bar20(}{it:rbar_options}{cmd:)} 
{cmd:barall(}{it:rbar_options}{cmd:)} 
{it:graph_options}
[ {cmd:plot(}{it:plot}{cmd:)} {c |}
{cmd:addplot(}{it:plot}{cmd:)} ]
]

{p 8 17 2} 
{cmd:tabplot}
{it:varname}
[{cmd:if} {it:exp}] 
[{cmd:in} {it:range}]
[{it:weight}]
[
{cmd:,}
[ 
{cmdab:fr:action} {c |}   
{cmdab:fr:action(}{it:varlist}{cmd:)} {c |}
{cmdab:perc:ent} {c |}
{cmdab:perc:ent(}{it:varlist}{cmd:)} 
] 
{cmdab:miss:ing}
{cmd:yasis xasis}
{cmdab:h:eight(}{it:#}{cmd:)} 
{cmdab:show:val}[{cmd:(}{it:specification}{cmd:)}] 
{cmdab:min:imum(}{it:#}{cmd:)} 
{cmdab:max:imum(}{it:#}{cmd:)} 
{cmdab:sep:arate(}{it:sepspec}{cmd:)} 
{cmd:bar1(}{it:rbar_options}{cmd:)} 
...
{cmd:bar20(}{it:rbar_options}{cmd:)} 
{cmd:barall(}{it:rbar_options}{cmd:)} 
{it:graph_options}
[ {cmd:plot(}{it:plot}{cmd:)} {c |}
{cmd:addplot(}{it:plot}{cmd:)} ]
]  

{p 4 4 2}{cmd:fweight}s, {cmd:aweight}s and {cmd:iweights} may be specified. 


{title:Description} 

{p 4 4 2}{cmd:tabplot} plots a table of frequencies, fractions or
percents in graphical form. It is mainly intended for representing a
two-way contingency table of categorical variables. It also has uses
for producing multiple histograms, two-way tables in general and one-way
tables. 

{p 4 4 2}{cmd:tabplot} {it:rowvar} {it:colvar} follows the standard
tabular alignment: the categories of {it:rowvar} define rows from top
(low values) to bottom (high values) and  the categories of {it:colvar}
define columns from left (low values) to right (high values). The
frequency (fraction, percent) of each combination of row and column is
shown as a bar, with default alignment vertical and default width 0.5.
Use the {cmd:barwidth()} option to vary width, but note that all bars
will have the same width.  By default both variables are mapped on the
fly in sort order to successive integers from 1 up, but original values
or value labels are used as value labels: this may be varied by use of
the {cmd:yasis} or {cmd:xasis} options.

{p 4 4 2}Alternatively, {cmd:tabplot} {it:varname} creates a bar chart
which by default displays one set of vertical bars; with the
{cmd:horizontal} option it displays one set of horizontal bars. The
categories of {it:varname} thus define either columns from left (low
values) to right (high values) or rows from top (low values) to bottom
(high values).  The frequency (fraction, percent) of each column or row
is shown as a bar. 


{title:Remarks} 

{p 4 4 2}The display is deliberately minimal. No numeric scales are
shown for reading off numeric values, although optionally numeric values
may be shown below bars by use of the {cmd:showval} option. Above all,
there is no facility for any kind of three-dimensional display or
effect. The maximum value (or more generally biggest value) shown is
indicated by use of {cmd:note()}, unless {cmd:showval} or
{cmd:showval()} is specified. 

{p 4 4 2}In contrast to a table, in which it is easier to compare values
down columns, it is usually easier to compare values across rows
whenever bars are vertical.  A simple alternative is to use the
{cmd:horizontal} option, in which case it is usually easier to compare
down columns.  Some experimentation with both forms and with
{cmd:percent(}{it:rowvar}{cmd:)} or {cmd:percent(}{it:colvar}{cmd:)}
will often be helpful. 

{p 4 4 2}{cmd:tabplot} {it:rowvar colvar}{cmd:, by()} is the way to plot
three-way tables. The variable specified in {cmd:by()} is used to
produce a set of graphs in several panels. Similarly, {cmd:tabplot}
{it:varname}{cmd:, by()} is another way to plot two-way tables. 

{p 4 4 2}{cmd:tabplot} with the {cmd:xasis} option may be useful for
stacking histograms vertically. Less commonly, with the {cmd:yasis} and
{cmd:horizontal} options it may be useful for stacking them
horizontally.  A typical protocol would be, for {cmd:mpg} shown in bins
of width 2.5 mpg, 

{p 8 8 2}
{cmd:. gen midpoint = round(mpg, 2.5)}{break} 
{cmd:. _crcslbl midpoint mpg}{break} 
{cmd:. tabplot foreign midpoint, xasis barw(2.5) bstyle(histogram) percent(foreign)}

{p 4 4 2}In general, specify a variable containing equally-spaced
midpoints and assign to it an appropriate variable label.  {cmd:tabplot}
will do the rest.  Omit the {cmd:percent()} option for display of
frequencies. 

{p 4 4 2}A recipe for subverting {cmd:tabplot} to plot any variable that
takes on a single value for each cross-combination of categories is
illustrated in the examples below. The key is to select precisely one
observation for each cross-combination and to specify that variable as
(most generally) an {cmd:iweight}. 

{p 4 4 2}Furthermore, using an {cmd:iweight} is the only possible method
whenever a variable has at least some negative values. In that case, 

{p 8 8 2}1. Consider changing the maximum height through {cmd:height()}
to avoid overlap of bars variously representing positive and negative
values.  By default {cmd:tabplot} chooses the scale to accommodate the
longest bar to be shown, but it contains no special intelligence
otherwise to avoid overlap of bars in the same column or row. 

{p 8 8 2}2. If also using {cmd:showval} or {cmd:showval()}, consider
changing the {cmd:offset()} and using a transparent {cmd:bfcolor()}. 

{p 4 4 2}
Bar charts presented as one row or one column  of bars go back at least as far 
as Playfair (1786). See (e.g.) Playfair (2005, p.25) or 
Wainer (2005, p.45; 2009, p.174). 

{p 4 4 2} 
Bar charts presented in table form with two or more rows and two or more
columns are less common. 
Brinton (1939), 
Neurath (1939), 
Doran and Hodson (1975), 
Bertin (1983), 
Lebart, Morineau and Warwick (1984), 
Chapman and Wykes (1996), 
de Falguerolles et al. (1997), 
Chauchat and Risson (1998), 
MacKay (2003, 2008),  
Wilkinson (2005), 
Unwin, Theus and Hofmann (2006), 
Hahsler, Hornik and Buchta (2008), 
Hofmann (2008), 
Few (2009) 
and 
Theus and Urbanek (2009) 
give a variety of examples. 


{title:Options} 

{p 4 8 2}{cmd:fraction} indicates that all frequencies should be shown
as fractions (with sum 1) of the total frequency of all values being
represented in the graph.

{p 4 8 2}{cmd:fraction(}{it:varlist}{cmd:)} indicates that all
frequencies should be shown as fractions (with sum 1) of the total
frequency for each distinct category defined by the combinations of
{it:varlist}. Usually, {it:varlist} will be either {it:rowvar} or
{it:colvar}. 

{p 4 8 2}{cmd:percent} indicates that all frequencies should be shown as
percents (with sum 100) of the total frequency of all values being
represented in the graph. 

{p 4 8 2}{cmd:percent(}{it:varlist}{cmd:)} indicates that all
frequencies should be shown as percents (with sum 100) of the total
frequency for each distinct category defined by the combinations of
{it:varlist}.  Usually, {it:varlist} will be either {it:rowvar} or
{it:colvar}. 

{p 4 8 2}Only one of these {cmd:fraction}[{cmd:()}] and
{cmd:percent}[{cmd:()}] options may be specified. 

{p 4 8 2}{cmd:missing} specifies that any missing values of any of the
variables specified should also be included within their own categories.

{p 4 8 2}{cmd:yasis} and {cmd:xasis} specify respectively that the
{it:y} (row) variable and the {it:x} (column) variable are to be treated
literally (that is, numerically). Most commonly, each option will be
specified if the variable in question is a measured scale or a graded
variable with gaps. If values 1 to 5 are labelled A to E, but no value
of 4 (D) is present in the data, {cmd:yasis} or {cmd:xasis} prevents a
mapping to 1 (A) ... 4 (E).

{p 4 8 2}{cmd:height(}{it:#}{cmd:)} controls the amount of graph space
taken up by bars. The default is 0.8.  Note that the height may need to
be much smaller or much larger with {cmd:yasis} or {cmd:xasis}, given
that the latter take values literally.  

{p 4 8 2}{cmd:showval} specifies that numeric values are be shown
beneath (or if {cmd:horizontal} is specified to the left of) bars.

{p 4 8 2} 
{cmd:showval} may also be specified with a variable name and/or options. 
If options alone are specified, no comma should be given. 
In particular, 

{p 8 8 2}{cmd:showval(}{it:varname}{cmd:)} would specify that the values to 
be shown 
are those of {it:varname}. For example, the values of some kind of residuals 
might be shown alongside frequency bars. 

{p 8 8 2}{cmd:showval(offset(}{it:#}{cmd:))} specifies an offset between
the base of the bar and the position of the numeric value.  Default is
0.1 with two variables or 0.02 with one variable.  Tweak this if the
spacing is too large or too small. 

{p 8 8 2}{cmd:showval(format(}{it:format}{cmd:))} specifies a format
with which to show values. Specifying a format will often be
advisable with non-integers. Example: {cmd:showval(format(%2.1f))}
specifies rounding to 1 decimal place. Note that with a specified variable 
the format defaults to the format of that variable; with percent options
the format defaults to %2.1f (1 decimal place); with fraction
options the format defaults to %4.3f (3 decimal places). 

{p 8 8 2}{cmd:showval(}{it:varname}{cmd:, format(%2.1f))} is an example of 
{it:varname} specified with options. 

{p 8 8 2}Otherwise the options of {cmd:showval()} can be options of
{help scatter}, most usually {help marker label options}. 

{p 4 8 2}{cmd:minimum()} suppresses plotting of bars with values less
than the minimum specified, in effect setting them to zero. 

{p 4 8 2}{cmd:maximum()} truncates bars with values more than 
the maximum specified to show that maximum.  

{p 4 8 2}{cmd:separate()} specifies that bars associated with different
{it:sepspec} will be shown differently, most obviously using different
colours. {it:sepspec} is passed as an argument to the {cmd:by()} option
of {help separate}, except that references to {cmd:@} are first translated to
be references to the quantity being plotted. 

{p 8 8 2}A call to {cmd:separate()} may be supplemented with calls to
options {cmd:bar1()} ...  {cmd:bar20} and/or to {cmd:barall()}. The
arguments should be options of {help twoway rbar}. 

{p 8 8 2}Options {cmd:bar1()} to {cmd:bar20()} are provided to allow
overriding the defaults on up to 20 categories, the first, second, etc.,
shown.  The limit of 20 is plucked out of the air as more than any user
should really want. The option {cmd:barall()} is available to override
the defaults for all bars. Any {cmd:bar}?  option always overrides
{cmd:barall()}. Thus if you wanted thicker {cmd:blwidth()} on all bars
you could specify {cmd:barall(blwidth(thick))}. If you wanted to
highlight the first category only you could specify
{cmd:bar1(blwidth(thick))}.

{p 4 8 2}{it:graph_options} refers to options of 
{help twoway_rbar:twoway rbar}.  Among others: 

{p 8 8 2}{cmd:barwidth()} specifies the widths of the bars. The default
is 0.5.  This may need changing, especially with option {cmd:xasis} or
{cmd:yasis}. 

{p 8 8 2}{cmd:by()} specifies another variable used to subdivide the
display into panels. 

{p 8 8 2}{cmd:recast()} recasts the graph as another twoway plottype. In
practice, {cmd:recast(rspike)} is the main alternative. 

{p 4 8 2}{cmd:plot(}{help plot_option:plot}{cmd:)} provides a way to add
other plots to the generated graph.  Allowed in Stata 8 only. 

{p 4 8 2}{cmd:addplot(}{help addplot option:addplot}{cmd:)} provides a
way to add other plots to the generated graph. Allowed in Stata 9
upwards.

{p 8 8 2}With large datasets especially, it is advisable to ensure that
the extra plot(s) do(es) not contain information repeated for every
observation within each combination of {it:rowvar} and {it:colvar}. The
examples show one technique for avoiding this.


{title:Examples}

{p 4 8 2}{cmd:. sysuse auto, clear}

{p 4 8 2}{cmd:. tabplot for rep78}{p_end}
{p 4 8 2}{cmd:. tabplot for rep78, showval}{p_end}
{p 4 8 2}{cmd:. tabplot for rep78, percent(foreign) showval(offset(0.05) format(%2.1f))}{p_end}
{p 4 8 2}{cmd:. tabplot for rep78, percent(foreign) sep(foreign) bar1(bcolor(red*0.5)) bar2(bcolor(blue*0.5)) showval(offset(0.05) format(%2.1f))}

{p 4 8 2}{cmd:. tabplot rep78 mpg, xasis barw(1) bstyle(histogram)}

{p 4 8 2}{cmd:. egen mean = mean(mpg), by(rep78)}{p_end}
{p 4 8 2}{cmd:. gen rep78_2 = 6 - rep78 - 0.05}{p_end}
{p 4 8 2}{cmd:. bysort rep78 : gen byte tag = _n == 1}{p_end}
{p 4 8 2}{cmd:. tabplot rep78 mpg, xasis barw(1) bstyle(histogram) addplot(scatter rep78_2 mean if tag)}

{p 4 8 2}{cmd:. tabplot rep78}{p_end}
{p 4 8 2}{cmd:. tabplot rep78, showval}{p_end}
{p 4 8 2}{cmd:. tabplot rep78, showval horizontal}

{p 4 8 2}{cmd:. egen mean2 = mean(mpg), by(foreign rep78)}{p_end}
{p 4 8 2}{cmd:. egen tag = tag(foreign rep78)}{p_end}
{p 4 8 2}{cmd:. tabplot foreign rep78 if tag [iw=mean2], showval(format(%2.1f)) subtitle(mean miles per gallon)}{p_end}
{p 4 8 2}{cmd:. su mpg}{p_end}
{p 4 8 2}{cmd:. tabplot foreign rep78 if tag [iw=mean2], showval(format(%2.1f)) separate(@ > 21.29) bar1(bcolor(red)) bar2(bcolor(black))}

{p 4 8 2}{cmd:. webuse rate2, clear}{p_end}
{p 4 8 2}{cmd:. tabplot rad?, percent showval}{p_end}
{p 4 8 2}{cmd:. count}{p_end}
{p 4 8 2}{cmd:. bysort rada radb : gen show = string(_N) + "  " + string(_N * 100/85, "%2.1f") + "%"}{p_end}
{p 4 8 2}{cmd:. tabplot rad?, showval(show)}


{title:Author} 

{p 4 4 2}Nicholas J. Cox, Durham University, U.K.{break} 
n.j.cox@durham.ac.uk


{title:Acknowledgments} 

{p 4 4 2}Bob Fitzgerald, Friedrich Huebler and Martyn Sherriff found
typos in this help. Friedrich also pointed to various efficiency issues.
Marcello Pagano provided encouragement. Vince Wiggins suggested how best to 
align x-axis labels when bars are horizontal. 


{title:References} 

{p 4 8 2}Bertin, J. 1983. 
{it:Semiology of graphics: Diagrams, networks, maps.} 
Madison: University of Wisconsin Press. 

{p 4 8 2}Brinton, W.C. 1939. 
{it:Graphic presentation.} 
New York: Brinton Associates. 
{browse "http://www.archive.org/stream/graphicpresentat00brinrich":http://www.archive.org/stream/graphicpresentat00brinrich} 

{p 4 8 2}Chapman, M. and Wykes, C. 1996. 
{it:Plain figures.} 
London: The Stationery Office. 

{p 4 8 2}Chauchat, J.-H. and Risson, A. 1998. 
Bertin's graphics and multidimensional data analysis. 
In Blasius, J. and Greenacre, M. (Eds) 
{it:Visualization of Categorical Data} 
San Diego, CA: Academic Press, 37{c -}45. 

{p 4 8 2}Cox, N.J. 2004. 
Graphing categorical and compositional data.
{it:Stata Journal} 4: 190{c -}215.

{p 4 8 2}Cox, N.J. 2008. 
Spineplots and their kin. 
{it:Stata Journal} 8: 105{c -}121.

{p 4 8 2}de Falguerolles, A.,  Friedrich, F. and Sawitzki, G. 1997. 
A tribute to J. Bertin's graphical data analysis.
In Bandilla, W. and Faulbaum, F. (Eds) 
{it:Advances in Statistical Software 6.}
Stuttgart: Lucius and Lucius, 11{c -}20.
{browse "http://statlab.uni-hd.de/reports/by.series/beitrag.34.pdf":http://statlab.uni-hd.de/reports/by.series/beitrag.34.pdf}

{p 4 8 2}Doran, J.E. and Hodson, F.R. 1975. 
{it:Mathematics and computers in archaeology.} 
Edinburgh: Edinburgh University Press. 
See p.118. 

{p 4 8 2}Few, S. 2009. 
{it:Now you see it: Simple visualization techniques for quantitative analysis.} 
Oakland, CA: Analytics Press. 

{p 4 8 2}Hahsler, M., Hornik, K. and Buchta, C. 2008. 
Getting things in order: an introduction to the R package seriation. 
{it:Journal of Statistical Software} 25(3) 
{browse "http://www.jstatsoft.org/v25/i03":http://www.jstatsoft.org/v25/i03}

{p 4 8 2}Hofmann, H. 2008. 
Mosaic plots and their variants. 
In Chen, C., H{c a:}rdle, W. and Unwin, A. (Eds)
{it:Handbook of data visualization.} 
Berlin: Springer, 617{c -}642. 

{p 4 8 2}Lebart, L., Morineau, A. and Warwick, K.M. 1984.
{it:Multivariate descriptive statistical analysis: Correspondence analysis and related techniques for large matrices.}
New York: John Wiley. See p.50.

{p 4 8 2}MacKay, D.J.C. 2003. 
{it:Information theory, inference, and learning algorithms.} 
Cambridge: Cambridge University Press. 

{p 4 8 2}MacKay, D.J.C. 2008. 
{it:Sustainable energy {c -} without the hot air.}
Cambridge: UIT Cambridge. 

{p 4 8 2}Neurath, O. 1939. 
{it:Modern man in the making.} 
London: Secker and Warburg. See p.74. 

{p 4 8 2}Playfair, W. 1786. 
{it:The commercial and political atlas.} 
London: Debrett; Robinson; and Sewell. 

{p 4 8 2}Playfair, W. 2005. 
{it:The commercial and political atlas and Statistical breviary.} 
(eds. Wainer, H. and Spence, I.) 
Cambridge: Cambridge University Press.  

{p 4 8 2}
Theus, M. and Urbanek, S. 2009. 
{it:Interactive graphics for data analysis: Principles and examples.} 
Boca Raton, FL: CRC Press. 

{p 4 8 2}
Unwin, A., Theus, M. and Hofmann, H. 2006.  
{it:Graphics of large datasets: Visualizing a million.}
New York: Springer. 

{p 4 8 2}Wainer, H. 2005. 
{it:Graphic discovery: A trout in the milk and other visual adventures.} 
Princeton, NJ: Princeton University Press. 

{p 4 8 2}Wainer, H. 2009. 
{it:Picturing the uncertain world: How to understand, communicate, and control uncertainty through graphical display.} 
Princeton, NJ: Princeton University Press. 

{p 4 8 2}
Wilkinson, L. 2005. 
{it:The grammar of graphics.}
New York: Springer. 


{title:Also see} 

{p 4 13 2}
On-line: help for {help twoway_rbar:twoway rbar}, {help histogram}, 
{help catplot} (if installed), {help spineplot} (if installed)  

