help for statplotversion 1.3.0

Plots of summary statistics, including plots by category

statplot
varlist
[if exp]
[in range]
[weight]
[, options]

What is plotted
statistic(stat) summary statistic to plot; default is mean

over(over_options) grouping on the axis; may be repeated once

by(by_options) draw separate panels by a further grouping

missing include missing values of over()/by() variables

Confidence intervals
ci add confidence-interval error bars to the bars/dots

level(#) confidence level for ci; default is level(95)

ciopts(rcap_options) look of the CI whiskers

baropts(bar_options) look of the CI bars (bar/hbar)

Percentages and shares
percent scale the statistic to 0-100 (e.g. a mean of a 0/1 indicator)

share express each bar as a percentage share of a total

base(base) denominator for share: total, var, or over

Order of the plotted variables
sort order the plotted variables (or groups) by value

descending with sort, order from high to low

order(varlist) fix the order of the plotted variables

first(varlist) pin these variables first

last(varlist) pin these variables last

Headings and groups (variables, hbar, no over())
headings(spec = "label" ...) insert section-title rows among the bars

groups(spec = "label" ...) bracket spans of bars with a side label

Saving the results set
savedata(filename[, replace]) save the collapsed data that is graphed to a .dta

listdata list the collapsed data that is graphed

frame(name) copy the collapsed data into a frame (Stata 16+)

Presentation
xpose transpose the nesting of the over() groupings

recast(plottype) hbar (default), bar, or dot

wrap(#) wrap axis labels longer than # characters

varnames use variable names, not variable labels, for varlist

varopts(varlist_options) look of the varlist bars or dots

graph_options any options of graph hbar|bar|dot

fweights, aweights, iweights and pweights may be specified;
whichever weights collapse accepts for the chosen statistic() are
allowed. The ci option does not accept pweights.

Description

statplot plots summary statistics for varlist.

Remarks

By default statplot is a wrapper for graph hbar.
Optionally, statplot 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.

Like those commands, statplot calls upon collapse to temporarily
produce a reduced dataset of summary statistics. The difference is that it
organizes that dataset in a different way. The graphs produced, compared with
those of graph hbar|bar|dot, are typically based more on axis labeling
than on the use of legends, and typically are shown in one color rather than
several. Thus, they are likely to be closer to a format acceptable for
journal publication.

Otherwise put, statplot does in one step what would otherwise take a
collapse and some reshaping: it summarizes varlist, lays the
categories out along the axis rather than in a legend, draws them in a single
colour, and makes reordering, relabelling and grouping the categories easy.
When you want the summarized numbers themselves -- for a companion table, a
check, or a different display -- the savedata(), listdata and
frame() options (see below) hand that reduced dataset back to you.

Only one statistic may be plotted at once. The ci, headings() and
groups() options are the one departure from the graph hbar|bar|dot
engine: because those commands cannot draw error bars or place labels at chosen
positions, these options build the graph with twoway instead (see the
respective sections below).

Options

What is plotted

statistic() specifies the summary statistic used to summarize and plot
varlist. The default is mean. See collapse for a full list
of accepted statistics (for example median, sd, sum,
count, p25, p75). Note that only one statistic may be
specified.

over() contains a call to an over() option (and its
suboptions) for graph hbar,
graph bar or graph dot as appropriate for
controlling grouping variables for the varlist on the axis.

No more than two over() options may be specified. If two over()
options are used, the order is important for how these groupings are nested.
The second over() will be labeled on the axis and the first option will
be indicated in a legend. To suppress the legend and place the first
over()'s variable labels closest to the axis, specify either
legend(off) or the xpose option.

missing indicates that observations for missing values in over()
or by() variables should be included on the graph.

Confidence intervals

ci adds confidence-interval error bars to a plot of means. Because
graph hbar|bar|dot cannot draw error bars, ci builds an
equivalent graph with twoway (rbar/bar plus rcap, or
rcap plus scatter under recast(dot)). The intervals are the
ordinary t-based confidence intervals of the mean (the same numbers as
ci means), computed from the mean, its standard error and the group
size returned by collapse.

ci requires statistic(mean) (the default) and does not accept
pweights. It supports no over(), one over() with a single
variable, and one over() with several variables (drawn as small
multiples, one panel per variable). Two over() options, or by(),
are not supported with ci; for those, or for weighted intervals, see
cibar (Staudt) or coefplot (Jann), from SSC.
Use case: a reviewer asks for 95% CIs on a bar chart of group means.

Because the ci graph is built with twoway rather than
graph bar, the xpose and varopts() options have no effect
under ci, and base() is reserved by the share option (so it
cannot be forwarded to twoway bar).

level(#) sets the confidence level; the default is level(95) (or
c(level)).

ciopts() passes options to the rcap whiskers, for
example ciopts(lcolor(gs6)) for grey error bars.

baropts() passes options to the CI bars in recast(hbar) (the
default) and recast(bar) mode, for example baropts(fcolor(gs10)
lcolor(gs6)). It has no effect under recast(dot).

Percentages and shares

percent multiplies the plotted statistic by 100. Its main use is with
0/1 indicator variables, where the mean is a proportion and percent
turns it into a percentage ("share answering yes"). The value-axis title
becomes percent. Use case: plotting the percentage in each group
who agree with a survey item. To print a % sign on each bar, add
blabel() (see Bar value labels below).

percent must be spelled in full. The abbreviations per and
perc, and the full word percentages, are passed through to
graph hbar|bar's own percentages option (which rescales
bars to sum to 100 across the over() categories) rather than to this
percent option.

share rescales the bars to percentage shares of a total. base()
chooses the denominator:

base(total) (the default) each bar as a percent of the grand
total of all bars (all bars sum to 100).

base(var) each bar as a percent of its own variable's total
across groups (each variable sums to 100 across the axis).

base(over) each bar as a percent of its group's total across
variables (each group sums to 100).

share is most natural with statistic(sum) or statistic(count).
Use case: showing how counts are distributed across categories as
percentages, without collapsing and normalizing by hand. For frequencies,
fractions or percents of categorical data, catplot (Cox,
from SSC) is a close relative.

Order of the plotted variables

sort orders the bars or dots by the plotted value. With two or more
variables in varlist it orders the variables by their statistic; with a
single variable and an over() it orders the groups. descending
orders from high to low. Use case: turning an alphabetical bar chart into
a ranking.

order(varlist) fixes the order of the plotted variables to the order
given (any variables not listed follow, in their sorted or original order).
first(varlist) and last(varlist) pin variables to the start or end.
Use case: ranking survey items by value but forcing a residual category
such as "None of these" to appear last: sort descending last(none).

Headings and groups

headings() and groups() label sections of the plotted variables,
after the options of the same names in coefplot (Jann, from
SSC). Each takes one or more spec = "label" entries,
where spec is one or more variable names (with * and ?
wildcards). Bold and other text markup may be used in the labels,
e.g. "Access".

headings() inserts each label as a section-title row immediately before
the first variable its spec matches, shifting the following bars down.
groups() draws each label as a bracket beside the span of variables its
spec matches, without shifting anything. Use case: grouping survey
items under section titles such as "Access" and "Quality".

Because these labels occupy positioned rows, they build the graph with
twoway (as ci does), and are supported only for variables plotted
without over(), in recast(hbar) (the default). They may be combined
with ci.

Saving the results set

savedata(filename[, replace]) saves the collapsed dataset
that underlies the graph -- the exact numbers that are plotted -- to a
.dta file. listdata lists that dataset to the Results window.
frame(name) copies it into a named frame (requires Stata 16
or later). Use case: building a companion table, quality-checking the
bars against the numbers, or reusing the summary without re-running
collapse. The saved numbers reflect any percent/share
rescaling. Under ci, the saved data also carries the interval bounds
(mean, lo, hi, se, N).

Presentation

xpose transposes or switches the grouping labels for over()
options. If no over() options are specified, xpose has no effect.
If one over() option is used, xpose switches the position of the
varlist labels from the outermost nesting to closest to the axis. If two
over() options are used, xpose switches the varlist labels to
the legend (which can be suppressed with legend(off)), moves the first
over() labels closest to the axis, and moves the second over()
labels off the axis.

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

wrap(#) wraps axis labels longer than # characters onto several
lines, breaking at spaces. It applies to the varlist labels and to the
over()/by() category labels, and changes only the label text, never
the plotted values. Use case: long survey-item or policy-category labels
that would otherwise overrun or shrink on the axis.

Wrapped labels need vertical room. With many over() categories the
multi-line labels can crowd; give them space with a larger ysize() and/or
a smaller label size, e.g. varopts(label(labsize(small))).

varnames indicates that variable names should be used instead of variable
labels for varlist.

varopts() specifies options for the display of the varlist bars or
dots. For example, labels could be modified with
varopts(label(labsize(medsmall))).

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

Bar value labels (and a % sign)

Numeric labels on the bars come straight from blabel(),
which statplot passes through untouched, for example
blabel(bar, format(%3.1f)). In Stata 19 and later, blabel() gained
prefix() and suffix() suboptions, so a % sign (or any literal
text) can be appended to each bar:

. statplot union, over(race) percent blabel(bar, format(%2.0f) suffix(%))

There is no numeric format that appends a % on its own, so on Stata 18 and
earlier use the Graph Editor for a per-bar % sign.

Examples

. sysuse citytemp, clear

. statplot heatdd cooldd

. statplot heatdd cooldd, over(region)

. statplot heatdd cooldd, over(region) sort descending

. statplot temp*, over(region, sort(1) descending) s(sd) blabel(bar, format(%2.1f)) ysc(r(. 17.5))

Controlling the order of the bars

. statplot tempjan tempjuly heatdd cooldd, sort // low to high by value

. statplot tempjan tempjuly heatdd cooldd, sort descending // high to low

. statplot tempjan tempjuly heatdd cooldd, order(cooldd heatdd) // fix the first two; the rest follow

. statplot tempjan tempjuly heatdd cooldd, first(cooldd) last(tempjan) // pin one first, one last

. statplot tempjan tempjuly heatdd cooldd, sort descending last(tempjan) // rank by value, but pin one bar last

. statplot heatdd, over(division) sort descending // one variable: sort the over() groups

. sysuse census, clear

. statplot marriage divorce, over(region) s(sum)

. statplot marriage divorce, over(region) s(sum) xpose

. statplot marriage divorce, over(region) s(sum) share base(var)

Percentage of a 0/1 indicator, labeled with a % sign

. sysuse nlsw88, clear

. statplot union, over(race) percent blabel(bar, format(%2.0f) suffix(%))

Means with 95% confidence intervals

. statplot wage, over(race) ci

. statplot wage ttl_exp tenure, over(race) ci recast(bar)

. statplot wage, over(race) ci level(90) baropts(fcolor(navy)) ciopts(lcolor(gs6))

Wrapping long labels

. statplot ttl_exp tenure grade hours, wrap(18)

Section headings and group labels among the bars

. sysuse auto, clear

. statplot price mpg weight length, headings(price = "Cost" weight = "Size")

. statplot price mpg weight length, groups(price mpg = "Performance" weight length = "Size") ci

Keeping the numbers behind the bars

. sysuse nlsw88, clear

. statplot wage ttl_exp, over(race) savedata(wage_by_race, replace)

. statplot wage ttl_exp, over(race) listdata

Using separate with a single variable and one over()

. statplot wage, over(race) over(union)

. separate wage, by(race) veryshortlabel

. statplot wage?, over(union)

Stored results

statplot is rclass and stores the following in r():

Scalars

r(N) number of observations plotted

r(N_vars) number of variables in varlist

r(N_groups) number of over()/by() group combinations

r(level) confidence level (with ci only)

Macros

r(cmd) statplot

r(statistic) the statistic plotted

r(varlist) the variables plotted, in the order plotted

Authors

Eric A. Booth, Texas 2036

eric.a.booth@gmail.com

Nicholas J. Cox, Durham University

n.j.cox@durham.ac.uk

Also see

Built in: graph hbar, graph bar,
graph dot, collapse, blabel()

Community-contributed, from SSC (for example,
ssc install catplot): catplot and tabplot
(Nicholas J. Cox); cibar (Alexander Staudt);
coefplot (Ben Jann)