help for catplot

Title

Plots of frequencies, fractions or percents of categorical data

catplot
[weight]
[if exp]
[in range]
,
over(firstvar, over_options)

[
over(secondvar, over_options)
by(thirdvar, by_options)

{fraction|fraction(varlist)|percent|percent(varlist)}

recast(plottype)
graph_options
]

Description

catplot shows frequencies (or optionally fractions or percents)
of the categories of one, two or three categorical variables. The
first-named variable firstvar, specified with an over()
option, is innermost on the display; that is,
its categories vary fastest. Often, but not necessarily, it will be the
substantive response or outcome of interest. One or two other variables,
perhaps with predictor roles, may be specified using a second over()
option and/or a by() option.

By default catplot is a wrapper for graph hbar.
Optionally catplot may be recast as a wrapper for
graph bar or graph dot. The choice is a
matter of personal taste, although in general horizontal displays make
it easier to identify names or labels of categories.

fweights, aweights and iweights may be specified. This
opens a door to use of catplot for plotting any set of values
for each of several different categories.

Quick start

Read in data

. sysuse auto, clear

Horizontal bar chart showing category frequencies

. catplot, over(rep78)

Horizontal bar chart showing category percents

. catplot, over(rep78) percent

Given foreign or domestic, what is percent breakdown of repair record?

. catplot, over(rep78) over(foreign) percent(foreign)

Given repair record, what is percent breakdown of foreign or domestic?

. catplot, over(foreign) over(rep78) percent(rep78)

And show the percents as numeric text? (You may need to add some space)

. catplot, over(foreign) over(rep78) percent(rep78) blabel(bar, format(%02.0f)) ysc(r(0 105))

Show that as a side-by-side display - and add an axis title too

. catplot, by(foreign, l1title(Repair record 1978)) over(rep78) percent(rep78) blabel(bar, format(%02.0f)) ysc(r(0 105))

Options

over() and by() options are intended to work as in
graph bar. Note however that by(, total) is not
smart enough to work with fraction or percent options.

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.

fraction(varlist) 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 its varlist. For
example, given a variable male with two categories male and female,
the fractions shown for male would have sum 1 and those for female would
have sum 1.

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.

percent(varlist) 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 its varlist. For
example, given a variable male with two categories male and female,
the percents shown for male would have sum 100 and those for female
would have sum 100.

Only one of these fraction[()] and
percent[()] options may be specified.

recast() recasts the graph to another plottype, one
of hbar, bar, dot.

Note for users of Stata 10 up: using the Graph Editor is another
way to produce these and many other changes.

Note for experienced users: although the name is suggested by another
recast() option, this is not a back door to recasting
to a twoway plot.

graph_options refers to other options of
graph bar, graph hbar or
graph dot as appropriate.

Note: you may find it helpful to display information on variables using
l1title() with hbar or dot; or b1title() with
bar or dot with the (undocumented) vertical option; or
with subtitle() in general. See also Remarks below on axis titles.

Remarks

Why and how this command was written

This version of catplot is a moderate rewriting of the previous
version of catplot from SSC, now there renamed catplot2010.
The rewriting reflects personal experience and judgement. The
revised syntax is offered as less awkward. The command is also perhaps
now better explained and exemplified.

The original posting about catplot on Statalist (Cox 2003)
explained the main idea. I wanted a one-line command to plot counts, or
fractions, or percents of observations of one or more categorical
variables. graph hbar and its kin, as released in Stata 8, would
do this if you first fed one of those commands a variable to be summed
over observations. Suppose you have 10 observations and you can see
from listings that you have 7 frogs and 3 toads. Stata will come to the
same conclusion once you create a variable that is identically 1 in each
observation and then ask for sums. Evidently 1 + 1 + 1 + 1 + 1 + 1 + 1 =
7 and 1 + 1 + 1 = 3 are the counts you need. So counting is just
summation. So also is working out fractions and percents. For those you
feed Stata, in this example, a variable with observations each
containing 1/10 and 100 (1/10) respectively. More complicated set-ups,
such as wanting percent breakdowns of the categories of categorical
variable C given cross-combinations of categorical variables A
and B, are just trivial extensions of the main idea - once you
have worked out the details.

The easy part is thus writing a wrapper for graph hbar and its kin
in which such a variable is created on the fly before calling up the
main command. The more challenging part is combining that code with the
official graph code that does the hard work, principally through
over() and by() options as well as other graph
options. Indeed, the user needs to be able to choose between hbar,
bar and dot as the engine. The original version (Cox 2003)
did that one way and the second version (Cox 2010) did it another way. The
first version was discussed in Cox (2004), while the second version has
been discussed mainly on Statalist. Now this catplot is a new version
that is closer to the official Stata implementation of newer
commands graph hbar (count) and graph hbar (percent), first
released on 9 October 2014 within the life of Stata 13 (see
whatsnew13).

catplot principles and practice

The default display of catplot using graph hbar or
graph bar is graphically conservative, reflecting the view that
height or length of bars and text indicating categories are good ways of
conveying information. If you wish also to have bars in different
colours, specify the option asyvars, which differentiates the
categories of the first-named variable. If you wish also to stack bars
of different colours, specify the further option stack.

The default display of catplot using graph dot is
similarly conservative. If you wish to have point symbols in different
colours, specify the option asyvars, which differentiates the
categories of the first-named variable. If you wish also to use
different point symbols, use the further option marker().

Such choices may or may not improve the graph. Personal suggestions:
legends are to be avoided if possible; multiple colours can confuse as
much as they clarify; stacking may make it harder to compare categories
with rare or zero frequencies or to show annotation visibly.

There is much scope for personal judgment over what is presented as
firstvar, secondvar and thirdvar. Indeed, in the Titanic
example below, the mean survival proportion presented as weights is the
outcome of interest. A simple comparison such as

. sysuse auto, clear

. catplot, percent(foreign) over(rep78) over(foreign) name(G1)

. catplot, percent(foreign) over(foreign) over(rep78) name(G2)

highlights the possibilities for displaying the same results
differently. Note the moral that the order of over() options
does matter.

As usual, running the examples should impart a good sense of what the
command can do. Some examples using collgrad (college graduate?)
from the nlsw88 data are redundant in the sense that
collgrad is a (0, 1) indicator variable, so that it would be
simpler to plot means, so avoiding the redundancy of plotting two
complementary fractions or percents, but they may help to underline how
the command works.

All that said, a personal suggestion is that many one-, two- or
three-way breakdowns of categorical data are better served by
tabplot. See Cox (2016) and search tabplot, sj for updates.

Axis titles

It is clearly documented that

the axis of graph bar, graph hbar and graph dot
showing magnitudes is always regarded as the y axis, even if it is
horizontal, while

the other axis in those commands is always regarded as a categorical
axis, and not as the x axis, regardless of whether it is
horizontal or vertical.

For any programmer coding with these commands, and any user working with
them directly or indirectly, these choices become hard rules. In
catplot the ytitle() defaults to simple text such as
"frequency", "fraction" or "percent" (unless you are using weights), but
you are encouraged to over-write that default with any text closer to
your purpose. That title is displayed horizontally if you are using
graph hbar or graph dot and vertically if you are using
graph bar or graph dot, vertical.

While attempts to set an xtitle() will fail, a rich variety of
other title options are available. The examples show some of the
possibilities.

Homespun and other wisdom

Note some simple principles in this territory:

It is difficult to create a great graph, but easy to improve a bad one.

Comparisons should be easy. That could mean in one dimension, across a
row or down a column, or it could mean using a table structure.

Ordering by magnitude may be even more useful than ordering by category.

Bars are better than pie slices as length is easier to judge than angle.
Dots on a scale are a good way to include magnitudes.

Text is better read as horizontal than as vertical.

Showing numbers as text as well by graphical elements can be helpful.

Lose the legend if you can. A great advantage of
graph hbar | bar | dot is strong support for category
labels, which can be nested too.

The sum of one value is just that value, so weights allow showing any
values, not just frequencies or percents.

by() allows table structures to be shown with
graph hbar | bar | dot.

by() can look like another over().

Examples

Choose a different scheme according to taste or if using Stata 17 or earlier.

. set scheme stcolor

(Stata's auto data)

. sysuse auto, clear

. catplot, over(rep78) l1title(Repair record 1978) name(CAT1, replace)

. catplot, over(rep78, sort(1)) l1title(Repair record 1978) name(CAT2, replace)

. catplot, over(rep78, sort(1) descending) l1title(Repair record 1978) name(CAT3, replace)

. catplot, over(rep78) l1title(Repair record 1978) blabel(bar, pos(base) size(4)) bar(1, bfcolor(none)) ysc(off) name(CAT4, replace)

. catplot, over(rep78) over(foreign) subtitle(Car origin and Repair record 1978) name(CAT5, replace)

. catplot, over(rep78) over(foreign) subtitle(Car origin and Repair record 1978) nofill name(CAT6, replace)

. catplot, over(rep78) by(foreign, note("") l1title(Repair record 1978)) percent(foreign) name(CAT7, replace)

. catplot, over(rep78) by(foreign, note("")) b2title(Repair record 1978) percent(foreign) recast(bar) name(CAT8, replace)

. catplot, over(rep78) by(foreign, note("") l1title(Repair record 1978)) percent(foreign) blabel(bar, position(outside) format(%3.1f)) ylabel(none) yscale(r(0,60)) name(CAT9, replace)

(Stata's nlsw88 data)

. sysuse nlsw88, clear

. catplot, over(collgrad) over(race) by(married, note("")) name(CAT10, replace)

. catplot, over(collgrad) over(race) by(married, note("")) recast(dot) name(CAT11, replace)

. local opts percent(race married) blabel(bar, format(%02.1f))

. catplot, over(collgrad) over(race) by(married, note("")) `opts' name(CAT12, replace)

. local trick subtitle(, pos(9) ring(1) bcolor(none) nobexpand place(e))

. local opts `opts' `trick'

. catplot, over(married) over(race) by(collgrad, col(1) note("")) `opts' name(CAT13, replace)

. catplot, over(married) over(race) by(collgrad, col(1) note("")) recast(bar) `opts' name(CAT14, replace)

. catplot, over(married) over(race) by(collgrad, col(1) note("")) recast(dot) `opts' name(CAT15, replace)

(Titanic data: Dawson 1995)

. clear

. input byte(class adult male) float survived

1 0 0 1

2 0 0 1

3 0 0 .4516129

1 0 1 1

2 0 1 1

3 0 1 .27083334

1 1 0 .9722222

2 1 0 .8602151

3 1 0 .4606061

4 1 0 .8695652

1 1 1 .3257143

2 1 1 .08333334

3 1 1 .16233766

4 1 1 .2227378

end

. label values class class

. label def class 1 "first" 2 "second" 3 "third" 4 "crew"

. label values adult adult

. label def adult 0 "child" 1 "adult"

. label values male male

. label def male 0 "female" 1 "male"

. catplot [aw=100*survived], over(adult, gap(*0.3) axis(noline)) over(male, gap(*0.8)) outergap(*.2) ///

by(class, compact note("") col(1) subtitle(% survived from Titanic)) ///

bar(1, blcolor(gs8) bfcolor(pink*.1)) blabel(bar, format(%4.1f) pos(base)) `trick' ///

ysize(7) yla(none) ytitle("") ysc(noline) name(CAT16, replace)

Author

Nicholas J. Cox, Durham University

n.j.cox@durham.ac.uk

Acknowledgments

The first version of catplot was written and revised in
2003 and 2004. At that time, Vince Wiggins provided very helpful
comments, Fred Wolfe asked for sorting and David Schwappach provided
feedback on limitations. During revision in 2010, Vince Wiggins and
Ronán Conroy made encouraging noises.

References

Cox, N.J. 2003.
st: -catplot- available for download from SSC.
Statalist post 21 February.
https://www.stata.com/statalist/archive/2003-02/msg00608.html

Cox, N.J. 2004.
Speaking Stata: Graphing categorical and compositional data.
Stata Journal 4: 190-215.
https://journals.sagepub.com/doi/pdf/10.1177/1536867X0400400209

Cox, N.J. 2010.
st: -catplot- revised on SSC.
Statalist post 8 June.
https://www.stata.com/statalist/archive/2010-06/msg00431.html

Cox, N.J. 2016.
Multiple bar charts in table form.
Stata Journal 16: 491-510.
https://journals.sagepub.com/doi/pdf/10.1177/1536867X1601600214

Dawson, R.J.MacG. 1995.
The "unusual episode" data revisited.
Journal of Statistics Education 3(3).
[Titanic data]
https://jse.amstat.org/v3n3/datasets.dawson.html

Also see

On-line: help for graph hbar;
graph bar; graph dot; histogram;
tabplot (if installed)