{smcl}
{* *! version 1.2.1  18Feb2017}{...}
{cmd:help mmws}
{hline}

{title:Title}

{p2colset 5 13 20 2}{...}
{p2col :{hi:mmws} {hline 2}}Marginal mean weighting through stratification{p_end}
{p2colreset}{...}

{title:Syntax}

{p 8 17 2}
		{cmd:mmws} {it:{help varname:treat}} {ifin} 
		{cmd:,}
		{opt ps:core}({it:{help varlist:varlist}})
		[ {opt str:ata}({it:{help varlist:varlist}})
		{opt nstr:ata}({it:{help numlist:numlist}})
		{opt ord:inal}
		{opt tlev:el}({it:#})
		{opt nom:inal}
		{opt att:}
		{opt iptw:}
		{opt comm:on}
		{opt fig:ure}
		{opt repl:ace} 
		{opt pre:fix}({it:string})
		]


{p 4 4 2}
{it:{help varname: treat}} must contain integer values representing the treatment levels
		
		
{p 4 6 2}

{title:Description}

{pstd}
{opt mmws} implements a method, originally proposed by Huang et al (2005),  extended by Hong (2010, 2012), and further described by 
Linden (2014) that combines elements of two propensity score-based techniques, stratification and weighting. 
{opt mmws} is a data pre-processing procedure that reweights a dataset to balance the observed pretreatment characteristics 
across all treatment groups. Under the ignorability assumption, the weighted data should approximate a randomized experiment. The weights 
generated by {opt mmws} can then be passed to the appropriate outcome model for use in subsequent analyses. 

{pstd}
Before using {opt mmws}, the propensity score for a given treatment must be estimated. A logit or probit regression model can be used for estimating the propensity score 
for a binary treatment; an ordinal logit or probit regression model can be used to estimate the propensity score for a treatment with ordered levels 
(e.g. varying doses of a drug); and a multinomial logistic or probit regression can be used for estimating propensity scores for nominal (independent) treatments.  {p_end}

		
{title:Options}

{phang}
{opth pscore(varlist)} {cmd:required.} For binary or ordinal level treatments, one propensity score must 
be provided. For multiple nominal level treatments, one propensity score must be provided for {it:each} treatment level and they must be 
ordered correspondingly (e.g. ps1 ps2 ps3 correspond to treatment levels 0 1 2, respectively).{p_end}

{phang}
{opth strata(varlist)} is a variable containing quantile categories of the propensity score. There should be one variable provided for 
each corresponding propensity score. Thus, for binary or ordinal level treatments, there should be only one {cmd:strata} variable provided. In the 
case of multiple nominal level treatments, there must be a {cmd:strata} variable provided that corresponds to each propensity score 
(e.g. strata1 strata1 strata3 correspond to ps1 ps2 ps3, respectively). The user should consider implementing {helpb pstrata} as a means of generating optimal
strata for each propensity score. {helpb pstrata} can be downloaded from {help ssc:SSC}.{p_end}

{phang}
{opth nstrata(numlist)} when {cmd:strata} is not provided by the user, {cmd:mmws} will generate a strata variable containing a specified number 
of quantile categories of the propensity score. There should be one value specified for each corresponding propensity score
(e.g. 5 3 10 are three quantile categories corresponding to ps1 ps2 ps3, respectively); default is 5 quantiles for each stratum. 
{cmd:nstrata} cannot be combined with {cmd:strata}.{p_end}

{phang}
{opt ordinal} specifies that the treatment variable contains more than two ordered levels (i.e. increasing doses of a drug).{p_end}

{phang}
{opt tlevel(#)} used only in conjunction with {cmd:ordinal} and {cmd:common}. It specifies which treatment level defines common support. Typically this would
coincide with the treatment level for which the propensity score was estimated in the ologit model (e.g. predict pscore, pr outcome(3) indicates that the propensity
score is estimated based on treatment level coded as 3). When {cmd:tlevel} is not specified, the ordinal treatment coded with the lowest value is used for common support. {p_end}

{phang}
{opt nominal} specifies that the treatment variable contains more than two nominal levels (i.e. treatment A, treatment B and treatment C).{p_end}

{phang}
{opt att} specifies that the weights generated by {cmd:mmws} are for estimating the average treatment effect on the treated (ATT); available only for binary treatments.{p_end}

{phang}
{opt iptw} generates inverse probability of treatment weights (IPTW) in addition to the mmws weights. When {cmd:iptw} is specified in conjunction 
with {cmd:att}, the weight is computed as an ATT weight (this option is available only for binary treatments), otherwise {cmd:iptw} is computed to estimate
the average treatment effect (ATE). The point estimates derived from an outcome model using the {cmd:iptw} as a {cmd:pweight} will be identical to those derived
using {help teffects ipw} (however the standard errors will likely differ because {help teffects ipw} estimates standard errors via GMM). {p_end}

{phang}
{opt common} generates weights for those observations within the region of common support, and gives a weight of zero to observations not on common support.
An indicator or dummy variable named _support is added to the dataset to identify the observations on common support. {cmd:Note:} If the 
option {cmd:common} is chosen together with {cmd:nstrata()}, {cmd:mmws} will first establish which units are on common support, and then generate the 
strata variable based on this subset of the sample. However, If the option {cmd:common} is chosen together with a user supplied strata variable via {cmd:strata()}, 
then common support will be based on the user supplied strata variable. Thus, the two approaches may result in different samples and 
weights being generated. Hong (2012), espouses the first approach, that is, first establish the region of common support, and then generate the quantiles
for the sample on common support (implemented in {cmd:mmws} by specifying {cmd:nstrata()} and {cmd:common} together).{p_end}

{phang}
{opt figure} a histogram of the propensity score is generated (with a kernel density overlay) to illustrate the overlap of each level of treatment. For nominal treatments, 
a histogram is generated for each propensity score. The minimum and maximum values of common support are presented as vertical lines. When {cmd:common} is specified, only
values of the propensity scores within common support are presented, otherwise all values are presented.{p_end}

{phang} 
{opt replace} replaces variables created by {cmd:mmws} if they already exist. If {cmd:prefix()} is specified, only variables created by {cmd:mmws} with
the same prefix will be replaced.{p_end}

{phang}
{opt prefix(string)} adds a prefix to the names of variables created by {cmd:mmws}. Short prefixes are recommended.{p_end}


{title:Variables added to the dataset}

{pstd} {cmd:mmws} generates several variables for the convenience of the user. If the user specifies a {cmd:prefix()}, it will naturally be applied:{p_end}


{p 5 15 15}{cmd:_strata:} if the {cmd:strata()} option is used, then _strata will be a clone of the variable specified in {cmd:strata()}. For nominal treatments, 
there will necessarily be multiple _strata generated, each with a suffix indicating which propensity score it is associated with (as will the variable label). 
If the {cmd:nstrata()} option is selected, then _strata will be the result of that chosen option{p_end}

{p 5 17 15}{cmd:_support:} an indicator or dummy variable indicating whether an observation is on common support{p_end}

{p 5 17 15}{cmd:_mmws:} the weight generated by {cmd:mmws}. The variable label will provide a brief description{p_end}

{p 5 17 15}{cmd:_iptw:} the inverse probability of treatment weight generated, when the {cmd:iptw} option is specified{p_end}


{title:Examples}

{pstd}
There are at least three general scenarios in which {cmd:mmws} can be
implemented: (1) a binary treatment in which one treatment group is compared to one control group;
(2) an ordinal (or continuous) level treatment in which groups receiving the various levels of the intervention are compared;
and (3) a multiple nominal level treatment in which groups receiving different interventions are compared. The examples 
below are described accordingly: {p_end}

{pstd}
{opt (1) Binary treatment:}{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 create a strata variable with 6 quantiles{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 "xtile strata1 = pscore, nq(6)":. xtile strata1 = pscore, nq(6)}{p_end}

{pstd}Alternately, an optimized strata variable can be generated using {helpb pstrata}{p_end}
{p 4 8 2}{stata "pstrata mbsmoke, ps(pscore)":. pstrata mbsmoke, ps(pscore)}{p_end}

{pstd}Generate weights using the strata variable created in the previous step{p_end}
{p 4 8 2}{stata "mmws mbsmoke, pscore(pscore) strata(strata1)":. mmws mbsmoke, pscore(pscore) strata(strata1)}{p_end}

{pstd}Examine covariate balance of the variable {cmd:mage} using {helpb qqplot3} using the weights generated in the previous run {p_end}
{p 4 8 2}{stata "qqplot3 mage [pw=_mmws], by(mbsmoke)":. qqplot3 mage [pw=_mmws], by(mbsmoke)}{p_end}

{pstd}Generate weights using nstrata to create the strata variable with 5 quantiles, and plot a histogram to examine the overlap 
between treatment and control groups on the propensity score {p_end}
{p 4 8 2}{stata "mmws mbsmoke, pscore(pscore) nstrata(5) replace fig":. mmws mbsmoke, pscore(pscore) nstrata(5) replace fig}{p_end}

{pstd}Generate ATT weights with common support{p_end}
{p 4 8 2}{stata "mmws mbsmoke, pscore(pscore) nstrata(5) att common replace":. mmws mbsmoke, pscore(pscore) nstrata(5) att common replace}{p_end}

{pstd}Generate both MMWS and IPTW weights fo ATT estimator with common support{p_end}
{p 4 8 2}{stata "mmws mbsmoke, pscore(pscore) nstrata(5) att iptw common replace":. mmws mbsmoke, pscore(pscore) nstrata(5) att iptw common replace}{p_end}

{pstd}Estimate average treatment effect on the treated (ATT) of {cmd:mbsmoke} on {cmd:bweight} using MMWS weights generated in the previous run {p_end}
{p 4 8 2}{stata "regress bweight mbsmoke [pw=_mmws], robust":. regress bweight mbsmoke [pw=_mmws], robust}{p_end}

{pstd}Estimate average treatment effect on the treated (ATT) of {cmd:mbsmoke} on {cmd:bweight} using IPTW weights generated in the previous run {p_end}
{p 4 8 2}{stata "regress bweight mbsmoke [pw=_iptw], robust":. regress bweight mbsmoke [pw=_iptw], robust}{p_end}

{pstd}Examine covariate balance of the variable {cmd:mage} using a box-plot using the weights generated in the previous run {p_end}
{p 4 8 2}{stata "graph box mage [pw=_mmws], over(mbsmoke)":. graph box mage [pw=_mmws], over(mbsmoke)}{p_end}


{pstd}
{opt (2) Ordinal level treatments:}{p_end}

{pstd}Load example data{p_end}
{p 4 8 2}{stata "use http://www.stata-press.com/data/r13/bdsianesi5.dta, clear":. use http://www.stata-press.com/data/r13/bdsianesi5.dta, clear}{p_end}

{pstd}Estimate propensity score for the ordinal treatment {cmd:ed} based on the lowest treatment level (0) and create a strata variable with 10 quantiles{p_end}
{p 4 8 2}{stata "ologit ed london eastern paed math7":. ologit ed london eastern paed math7}{p_end}
{p 4 8 2}{stata "predict pscore, pr outcome(0)":. predict pscore, pr outcome(0)}{p_end}
{p 4 8 2}{stata "xtile strata = pscore, nq(10)":. xtile strata = pscore, nq(10)}{p_end}

{pstd}Generate weights for an ordinal treatment using the strata variable created in the previous step {p_end}
{p 4 8 2}{stata "mmws ed, pscore(pscore) ordinal strata(strata)":. mmws ed, pscore(pscore) ordinal strata(strata)}{p_end}

{pstd}Generate weights using nstrata to create the strata variable with 5 quantiles, and plot 
a histogram to examine the overlap amongst levels of treatment on the propensity score{p_end}
{p 4 8 2}{stata "mmws ed, pscore(pscore) ordinal nstrata(5) replace fig":. mmws ed, pscore(pscore) ordinal nstrata(5) replace fig}{p_end}

{pstd}Generate weights for an ordinal treatment using nstrata and specify that common support should be defined by treatment level 0{p_end}
{p 4 8 2}{stata "mmws ed, pscore(pscore) ordinal tlevel(0) common nstrata(5) replace fig":. mmws ed, pscore(pscore) ordinal tlevel(0) common nstrata(5) replace fig}{p_end}

{pstd}Examine covariate balance of the variable {cmd:paed} using a box-plot with the weights generated in the previous run {p_end}
{p 4 8 2}{stata "graph box paed [pw=_mmws], over(ed)":. graph box paed [pw=_mmws], over(ed)}{p_end}

{pstd}Estimate average treatment effect of levels of {cmd:ed} on {cmd:wage} using weights generated in the previous run {p_end}
{p 4 8 2}{stata "regress wage i.ed [pw=_mmws], robust":. regress wage i.ed [pw=_mmws], robust}{p_end}

{pstd}Run margins to get reweighted mean {cmd:wage} for each level of {cmd:ed}{p_end}
{p 4 8 2}{stata "margins ed":. margins ed}{p_end}

{pstd}Run marginsplot to visually display reweighted mean {cmd:wage} for each level of {cmd:ed}{p_end}
{p 4 8 2} {stata "marginsplot,  plotopts(connect(i))": . marginsplot,  plotopts(connect(i))}{p_end}

{pstd}Run margins to get contrasts between each level of {cmd:ed} and the base level (0){p_end}
{p 4 8 2}{stata "margins r.ed":. margins r.ed}{p_end}


{pstd}
{opt (3) Multiple nominal treatments:}{p_end}

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

{pstd}Estimate propensity scores for the four treatment levels of {cmd:msmoke} and generate four strata variables corresponding to each treatment, respectively {p_end}
{p 4 8 2}{stata "mlogit msmoke i.(mmarried fbaby) mage c.mage#c.mage medu c.medu#c.medu c.mage#c.medu, base(0)":. mlogit msmoke i.(mmarried fbaby) mage c.mage#c.mage medu c.medu#c.medu c.mage#c.medu, base(0)}{p_end}
{p 4 8 2}{stata "predict double (ps1 ps2 ps3 ps4), pr":. predict double (ps1 ps2 ps3 ps4), pr}{p_end}

{pstd}Generate weights for nominal treatments using the nstrata option and common support. Show overlap graph. {p_end}
{p 4 8 2}{stata "mmws msmoke, pscore(ps1 ps2 ps3 ps4) nominal nstrata(5 6 7 8) common replace fig":. mmws msmoke, pscore(ps1 ps2 ps3 ps4) nominal nstrata(5 6 7 8) common replace fig}{p_end}

{pstd}Estimate average treatment effect of each level of {cmd:msmoke} on {cmd:bweight} using MMWS weights generated in the previous run {p_end}
{p 4 8 2}{stata "regress bweight i.msmoke [pw=_mmws], robust":. regress bweight i.msmoke [pw=_mmws], robust}{p_end}

{pstd}Run margins to get reweighted mean {cmd:bweight} for each level of {cmd:msmoke}{p_end}
{p 4 8 2}{stata "margins msmoke":. margins msmoke}{p_end}

{pstd}Run marginsplot to visually display reweighted mean {cmd:bweight} for each level of {cmd:msmoke}{p_end}
{p 4 8 2} {stata "marginsplot,  plotopts(connect(i))": . marginsplot,  plotopts(connect(i))}{p_end}

{pstd}Run pairwise comparisons between reweighted treatment levels, with Bonferroni adjustment for multiple tests  {p_end}
{p 4 8 2}{stata "margins msmoke, pwcompare(effects) mcompare(bonferroni)":. margins msmoke, pwcompare(effects) mcompare(bonferroni)}{p_end}


{title:Saved results}

{p 4 8 2}
By default, {cmd:mmws} returns the following results, which 
can be displayed by typing {cmd: return list} after 
{cmd:mmws} is finished (see {help return}).  

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Scalars}{p_end}
{synopt:{cmd:r(suppmin)}}the minimum value of common support (will have a suffix for nominal treatments){p_end}
{synopt:{cmd:r(suppmax)}}the maximum value of common support (will have a suffix for nominal treatments){p_end}



{title:References}

{p 4 8 2}
Hong, G. 2010. Marginal mean weighting through stratification: adjustment for selection bias in multilevel data. 
{it:Journal of Educational and Behavioral Statistics} 35: 499-531.

{p 4 8 2}
Hong, G. 2012. Marginal mean weighting through stratification: a generalized method for evaluating multi-valued 
and multiple treatments with non-experimental data. {it:Psychological Methods} 17: 44-60.

{p 4 8 2}
Huang, I.-C., Frangakis, C., Dominici, F., Diette, G. B., Wu, A. W. 2005. Application of a propensity score 
approach for risk adjustment in profiling multiple physician groups on asthma care. {it:Health Services Research} 40: 253-278.

{p 4 8 2}
Linden, A. 2014. Combining propensity score-based stratification and weighting to improve 
causal inference in the evaluation of health care interventions. {it:Journal of Evaluation in Clinical Practice} 20: 1065-1071.

{p 4 8 2}
Linden, A. 2017a. Improving casual inference with a doubly robust estimator that combines propensity score stratification and weighting. 
{it:Journal of Evaluation in Clinical Practice} DOI:10.1111/jep.12714

{p 4 8 2}
Linden, A. 2017b. A comparison of approaches for stratifying on the propensity score to reduce bias. 
{it:Journal of Evaluation in Clinical Practice} DOI:10.1111/jep.12701

{p 4 8 2}
Linden, A. & Adams, J. L. (2008) Improving participant selection in disease management programs: insights gained from propensity score
stratification. {it:Journal of Evaluation in Clinical Practice}, 14, 914–918.

{p 4 8 2}
Linden, A., Uysal, S. D., Ryan, A., & Adams, J. L. (2016) Estimating causal effects for multivalued treatments: 
A comparison of approaches. {it: Statistics in Medicine} 35: 534-552.

{p 4 8 2}
Nichols, A. 2008. Erratum and discussion of propensity-score reweighting. {it: Stata Journal} 8: 532-539.

{p 4 8 2}
Robins, J. M., Hernan, M. A., Brumback B. 2000. Marginal Structural Models and Causal Inference in Epidemiology. {it:Epidemiology} 11: 550-560.

{p 4 8 2}
Sato, T., Matsuyama, Y. 2003. Marginal Structural Models as a Tool for Standardization. {it:Epidemiology} 14: 680-686.



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

{p 4 8 2}{cmd:mmws} 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. 
MMWS: Stata module for implementing mean marginal weighting through stratification. {browse "http://ideas.repec.org/c/boc/bocode/s457886.html":http://ideas.repec.org/c/boc/bocode/s457886.html}
{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:mmws}, and to Paul Walsh for pointing out a bug in the code for IPTW in the nominal treatment case.{p_end}


{title:Also see}

{p 4 8 2}Online:  {helpb xtile}, {helpb logit}, {helpb ologit}, {helpb mlogit}, {helpb margins}, {helpb marginsplot}, {helpb teffects},  
 {helpb pstrata} (if installed), {helpb qqplot3} (if installed), {helpb covbal} (if installed),  {helpb drmmws} (if installed) {p_end}