{smcl}
{* 16 Jun 2014}{...}
{cmd:help qqplot3}
{hline}

{title:Title}

{p2colset 5 18 18 2}{...}
{p2col :{hi:qqplot3} {hline 2}}plot the unweighted and weighted quantiles of one variable against the corresponding quantiles of another variable (Q-Q plot){p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 17 2}
{cmd:qqplot3} {it:{help varname:varname1} {help varname:varname2}}  {ifin} [{it:{help qqplot3##weight:weight}}] {cmd:,} 
[ {opt g:enerate(newvar1 newvar2)} ]  

{p 8 17 2}
{cmd:qqplot3}  {it:{help varname:varname}}  {ifin} [{it:{help qqplot3##weight:weight}}]  {cmd:,} 
{opt by(groupvar)} [ {opt g:enerate(newvar1 newvar2)} ] 


{synoptset 24 tabbed}{...}
{synopthdr}
{synoptline}
{syntab :Main}
{p2coldent :* {opt by:(groupvar)}}
specifies a group variable to specify precisely two 
groups of {it:{help varname:varname}}. {opt by()} may be only be specified with a single variable name. 
{p_end}

{syntab :Options}
{p2coldent :{opt g:enerate(newvar1 newvar2)}} specifies two new variable names to hold 
the quantiles.{p_end}

{synoptline}
{p2colreset}{...}
{p 4 6 2}* {opt by(groupvar)} must be specified when only one {it:{help varname:varname}} is provided.{p_end}

{marker weight}{...}
{p 4 6 2}
{opt fweight}s, {opt aweight}s, and {opt pweight}s are allowed
(see {manhelp weight U:11.1.6 weight}).
{p_end}


{title:Description}

{pstd}
{cmd:qqplot3} generates a quantile-quantile plot (Q-Q plot), in which the quantiles of one variable are plotted 
against the quantiles of another. {cmd:qqplot3} holds three advantages over {help qqplot}. First and most importantly, 
{cmd:qqplot3} allows the user to specify weights. This enables visual inspection of unadjusted and weighted baseline 
covariates to assess balance, a necessary condition for causal inference. This similarly makes Q-Q plots 
accessible to investigators with complex survey designs using sampling weights. Second, unlike {help qqplot}, {cmd:qqplot3} 
provides a "by" option for a grouping variable (such as treatment assignment) - a convenience factor for the user. 
And third, {cmd:qqplot3} provides the option of saving the quantiles generated by the program, which may be useful for 
conducting additional analyses.       

{pstd}
{cmd:qqplot3} draws heavily on the code used in {help cquantile}, a user-written program by Nicholas J. Cox (downloadable from SSC). 
However, {cmd:qqplot3} relies on {help pctile} for calculating the quantiles, using the default method, which inverts the empirical distribution 
function by using averages, where the function is flat (this is the same method used by {cmd:summarize}; see {manhelp summarize R}). This method differs
somewhat from the interpolation method used in {help cquantile} and {help qqplot} (see {mansection D pctileMethodsandformulas:{it:Methods and formulas}} 
in {bf:[D] pctile}). {cmd:qqplot3} uses the default method because weights cannot be specified in {help pctile} when the interpolation method 
({opt altdef}) is used. That said, the quantiles generated between the two methods are quantitatively similar. 

{pstd}
{help fixsort}, another program written by Nicholas J. Cox (downloadable from SSC), must be installed in order for {cmd:qqplot3} to 
run (an error message will appear, otherwise). 



{marker examples}{...}
{title:Examples}

   {hline}
{pstd}
{opt Testing for covariate balance in reweighted data:}{p_end}

{pstd}Load example data{p_end}
{p 4 8 2}{stata "webuse cattaneo2, clear":. webuse cattaneo2, clear}{p_end}

{pstd}Estimate propensity score for the binary treatment {cmd:mbsmoke} and generate inverse probability of treatment weights (IPTW) {p_end}
{p 4 8 2}{stata "logit mbsmoke mmarried mage c.mage#c.mage fbaby medu":. logit mbsmoke mmarried c.mage##c.mage fbaby medu}{p_end}
{p 4 8 2}{stata "predict pscore, pr":. predict pscore, pr}{p_end}
{p 4 8 2}{stata "gen iptw = cond(mbsmoke, 1/pscore, 1/(1-pscore))":. gen iptw = cond(mbsmoke, 1/pscore, 1/(1-pscore))}{p_end}

{pstd}Inspect balance in the distributions of mother's age ({cmd:mage}) by smoking status ({cmd:mbsmoke}) - before and after IPTW adjustment{p_end}
{p 4 8 2}{stata "qqplot3 mage, by(mbsmoke)":. qqplot3 mage, by(mbsmoke)}{p_end}
{p 4 8 2}{stata "qqplot3 mage [pw=iptw], by(mbsmoke)":. qqplot3 mage [pw=iptw], by(mbsmoke)}{p_end}
 
   {hline}
{pstd}
{opt Survey with sampling weights:}{p_end}
   
{pstd}Load example data{p_end}
{p 4 8 2}{stata "use http://www.stata-press.com/data/r13/nhanes2b.dta, clear":. use http://www.stata-press.com/data/r13/nhanes2b.dta, clear}{p_end}

{pstd}Inspect the distributions of systolic blood pressure ({cmd:bpsystol}) by ({cmd:female}) - without and with sampling weights, and save the quantiles{p_end}
{p 4 8 2}{stata "qqplot3 bpsystol, by(female) gen(bp0 bp1)":. qqplot3 bpsystol, by(female) gen(bp0 bp1)}{p_end}
{p 4 8 2}{stata "qqplot3 bpsystol [pw=finalwgt], by(female) gen(bpw0 bpw1)":. qqplot3 bpsystol [pw=finalwgt], by(female) gen(bpw0 bpw1)}{p_end}

   {hline}

{title:Saved results}

{p 4 8 2}
{cmd:qqplot3} stores the following result in {cmd: r()}:  

{synoptset 10 tabbed}{...}
{p2col 5 15 19 2: Scalar}{p_end}
{synopt:{cmd:r(nq)}}the number of quantiles used to compute percentiles. This value will always be equal to the variable with the smallest N, + 1 {p_end}

{marker citation}{title:Citation of {cmd:mmws}}

{p 4 8 2}{cmd:qqplot3} is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such: {p_end}

{p 4 8 2}
Linden, Ariel. 2014. 
qqplot3: Stata module for plotting unweighted and weighted Q-Q plots. 
{p_end}


{title:Author}

{p 4 4 2}
Ariel Linden{break}
President, Linden Consulting Group, LLC{break}
Ann Arbor, MI, USA{break} 
{browse "mailto:alinden@lindenconsulting.org":alinden@lindenconsulting.org}{break}
{browse "http://www.lindenconsulting.org"}{p_end}


{title:Acknowledgments} 

{p 4 4 2}
I wish to thank Nicholas J. Cox for his support while developing {cmd:qqplot3} and to Kit Baum for suggesting the name {cmd:qqplot3},
and recommending the error capturing code. Finally, I would like to thank Chuck Huber at StataCorp for his insights that led me to 
develop the program.{p_end}


{title:Also see}


{psee}
Online:  {helpb qqplot}, {helpb pctile}, {helpb separate}, {helpb cquantile} (if installed), {helpb fixsort} (if installed)
{p_end}