help for combineplot

Combine similar univariate or bivariate plots for different variables

combineplot
[(]yvarlist[)]
[(][xvarlist][)]
[weight]
[if]
[in]

[
,
allobs
combine(combine_options)
sequence(words_in_sequence)
seqopts(option)
]

: command_pattern
[ , graph_options ]

Weights are supported if and as allowed by the graphics command
requested.

Description

combineplot produces an array of plots for each variable in
yvarlist combined, when specified, with each variable in
xvarlist. A command_pattern must be specified for a graph
command (official or user-written) with rules that the text @y
refers to each y variable and any text @x refers to each
x variable. Reference to @y is compulsory, but reference to
@x is at choice.

Remarks

The most general Stata recipe for combining several plots in one figure
is to produce the individual plots and then combine them using
graph combine. Many commands offer automation in doing something
similar using over() or by() options or specific machinery
(e.g. graph matrix). The aim of combineplot is to give a
convenience command offering modest automation whenever each graph is of
the same kind and different plots are for different variables.

The syntax is based on the following rules:

Rule 1: A variable list without any parentheses is interpreted as
yvarlist.

Rule 2: Otherwise parentheses may indicate groupings into yvarlist
and xvarlist. The first token, a parenthesised variable list or a
single unparenthesised variable name, is treated as yvarlist. Any
remaining variables are treated as xvarlist. Other parentheses may
be used at discretion but are ignored.

Rule 3: The command_pattern must refer to @y as a placeholder
for the y variable name.

Rule 4: The command_pattern may refer to @x as a placeholder
for the x variable name, in which case an xvarlist must be
specified.

Rule 5: When both specified, yvarlist and xvarlist are
combined using all possible pairs with one y and one x, i.e.
as a Cartesian product.

yvarlist and xvarlist may each name a single variable, but if
both are single variable names you might as well produce your graph more
directly. That is to say, this will work:

. combineplot (mpg) (weight): scatter @y @x

However, that is no more than a long-winded way to do

. scatter mpg weight

yvarlist and xvarlist may share variables or even be
identical.

A neat arrangement of the individual graphs is produced if the number of
y variables is equal to the number of x variables, or the
number of y variables is 1, or the number of x variables is 1.
Otherwise, use combine() to tune the number of rows or columns in
the table of graphs. Recall that a total of 4, 9, 16, 25, ... graphs
permits a neat display that is 2 x 2, 3 x 3, 4 x 4, 5 x 5, ....

This is a 2014 generalisation of cpyxplot (SSC), first made public
in 1999.

Tufte (1983, 1990) remains inspirational on the value of "small
multiples". Heiberger and Holland (2004, 2008) contain enthusiastic
advocacy of Cartesian products in statistical graphics.

Options

allobs requests plotting of results on each graph for all possible
observations. The default is to show only observations for which all
y and all x variables are non-missing.

combine() specifies options allowed with graph combine.

sequence() specifies text to appear in sequence to act as captions
for each plot. For example, seq(a b c d) specifies that successive
graphs will be labelled a, b, c and d. The
precise syntax is that successive words of the argument will be
shown using the option
caption("word", pos(11) size(large)). As usual in
Stata, binding in double quotes " " is stronger than separation by
spaces, so syntax such as
seq("first caption" "second caption" "third caption" "fourth caption")
would show text with embedded spaces.

seqopts() specifies modification of the default display for
sequence(). For example, seqopts(caption(, color(red)))
changes the text colour to red. Note that substantial changes are likely
to require use of the Graph Editor or writing your own program.

graph_options are options allowed with whatever graph command is
specified. Options may refer to the current y variable and/or the
current x variable using the text @y and @x
respectively.

Examples

. sysuse auto, clear

. set scheme s1color

. combineplot mpg price weight headroom: graph box @y, over(rep78)

. combineplot mpg price weight headroom: dotplot @y, over(rep78)

. combineplot price mpg headroom-gear, combine(imargin(small)): histogram @y, freq yla(, ang(h))

. combineplot price mpg weight length: qnorm @y

. combineplot price (mpg weight length displacement): scatter @y @x || qfit @y @x, legend(off) ytitle("Price (USD)")

. combineplot (mpg price) (rep78 foreign), sequence(a b c d) seqopts(caption(, color(red))): graph box @y, over(@x)

Author

Nicholas J. Cox, Durham University, U.K.

n.j.cox@durham.ac.uk

Acknowledgments

Comments from Alfonso Sánchez-Peñalver and Dirk Enzmann
stimulated development of the program in 2014.

I salute Burt S. Holland (1946-2010) and James Alexander Green
(1926-2014), from whose excellent little book (Green 1965) I first
learned of Cartesian products and many other such standard beasts.

References

Green, J.A. 1965.
Sets and groups.
London: Routledge and Kegan Paul.

Heiberger, R.M. and Holland, B. 2004.
Statistical analysis and data display: An intermediate course with examples in S-PLUS, R, and SAS.
New York: Springer.

Heiberger, R.M. and Holland, B. 2008.
Structured sets of graphs.
In Chen, C., Härdle, W. and Unwin, A. (Eds)
Handbook of data visualization.
Berlin: Springer, 415-445.

Tufte, E.R. 1983, 2nd edition 2001.
The visual display of quantitative information.
Cheshire, CT: Graphics Press.

Tufte, E.R. 1990.
Envisioning information.
Cheshire, CT: Graphics Press.

Also see

On-line: help for twoway, help for graph matrix,
help for crossplot (if installed from SSC),
help for cpcorr (if installed from SSC),
help for multqplot (if installed from SJ)