{smcl}
{* 28apr2014}{...}
{hline}
help for {hi:combineplot}
{hline}

{title:Combine similar univariate or bivariate plots for different variables} 

{p 8 17 2} 
{cmd:combineplot}
[{cmd:(}]{it:yvarlist}[{cmd:)}] 
[{cmd:(}][{it:xvarlist}][{cmd:)}] 
[{it:weight}] 
[{help if}] 
[{help in}]
{p_end}
{p 17 17 2} 
[
{cmd:,}
{cmd:allobs} 
{cmd:combine(}{it:combine_options}{cmd:)} 
{cmdab:seq:uence(}{it:words_in_sequence}{cmd:)} 
{cmd:seqopts(}{it:option}{cmd:)} 
]
{p_end}
{p 17 17 2} 
{cmd::} {it:command_pattern}
[ , {it:graph_options} ]


{p 8 17 2}
Weights are supported if and as allowed by the graphics command
requested. 


{title:Description} 

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


{title:Remarks} 

{p 4 4 2} 
The most general Stata recipe for combining several plots in one figure
is to produce the individual plots and then combine them using
{cmd:graph combine}. Many commands offer automation in  doing something
similar using {cmd:over()} or {cmd:by()} options or specific machinery
(e.g. {cmd:graph matrix}). The aim of {cmd: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. 

{p 4 4 2}
The syntax is based on the following rules: 

{p 4 4 2}
Rule 1: A variable list without any parentheses is interpreted as
{it:yvarlist}.

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

{p 4 4 2}
Rule 3: The {it:command_pattern} must refer to {cmd:@y} as a placeholder
for the {it:y} variable name. 

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

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

{p 4 4 2} 
{it:yvarlist} and {it: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:

{p 8 8 2}{cmd:. combineplot (mpg) (weight): scatter @y @x} 

{p 4 4 2}
However, that is no more than a long-winded way to do 

{p 8 8 2}{cmd:. scatter mpg weight} 

{p 4 4 2}
{it:yvarlist} and {it:xvarlist} may share variables or even be
identical. 

{p 4 4 2} 
A neat arrangement of the individual graphs is produced if the number of
{it:y} variables is equal to the number of {it:x} variables, or the
number of {it:y} variables is 1, or the number of {it:x} variables is 1.
Otherwise, use {cmd: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, .... 

{p 4 4 2}
This is a 2014 generalisation of {cmd:cpyxplot} (SSC), first made public
in 1999. 

{p 4 4 2}
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. 


{title:Options}

{p 4 8 2}
{cmd:allobs} requests plotting of results on each graph for all possible
observations. The default is to show only observations for which all
{it:y} and all {it:x} variables are non-missing. 

{p 4 8 2}
{cmd:combine()} specifies options allowed with {help graph combine}. 

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

{p 4 8 2} 
{cmd:seqopts()} specifies modification of the default display for
{cmd:sequence()}. For example, {cmd: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. 

{p 4 8 2}
{it:graph_options} are options allowed with whatever graph command is
specified. Options may refer to the current {it:y} variable and/or the
current {it:x} variable using the text {cmd:@y} and {cmd:@x}
respectively. 


{title:Examples} 

{p 4 8 2}{cmd:. sysuse auto, clear}{p_end}
{p 4 8 2}{cmd:. set scheme s1color}{p_end}

{p 4 8 2}{cmd:. combineplot mpg price weight headroom: graph box @y, over(rep78)}{p_end}
{p 4 8 2}{cmd:. combineplot mpg price weight headroom: dotplot @y, over(rep78)}{p_end}
{p 4 8 2}{cmd:. combineplot price mpg headroom-gear, combine(imargin(small)): histogram @y, freq yla(, ang(h))}{p_end}
{p 4 8 2}{cmd:. combineplot price mpg weight length: qnorm @y}{p_end}
{p 4 8 2}{cmd:. combineplot price (mpg weight length displacement): scatter @y @x || qfit @y @x, legend(off) ytitle("Price (USD)")}{p_end}
{p 4 8 2}{cmd:. combineplot (mpg price) (rep78 foreign), sequence(a b c d) seqopts(caption(, color(red))): graph box @y, over(@x)}{p_end}


{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}
Comments from Alfonso S{c a'}nchez-Pe{c n~}alver and Dirk Enzmann
stimulated development of the program in 2014. 

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


{title:References} 

{p 4 8 2}
Green, J.A. 1965. 
{it:Sets and groups.} 
London: Routledge and Kegan Paul. 

{p 4 8 2}
Heiberger, R.M. and Holland, B. 2004. 
{it:Statistical analysis and data display: An intermediate course with examples in S-PLUS, R, and SAS.} 
New York: Springer. 

{p 4 8 2}
Heiberger, R.M. and Holland, B. 2008. 
Structured sets of graphs. 
In Chen, C., H{c a:}rdle, W. and Unwin, A. (Eds) 
{it:Handbook of data visualization.} 
Berlin: Springer, 415{c -}445. 

{p 4 8 2}
Tufte, E.R. 1983, 2nd edition 2001. 
{it:The visual display of quantitative information.} 
Cheshire, CT: Graphics Press. 

{p 4 8 2}
Tufte, E.R. 1990. 
{it:Envisioning information.} 
Cheshire, CT: Graphics Press. 


{title:Also see}

{p 4 13 2}
On-line: help for {help twoway}, help for {help graph matrix}, 
help for {help crossplot} (if installed from SSC),   
help for {help cpcorr} (if installed from SSC), 
help for {help multqplot} (if installed from SJ)