{smcl}
{* 07Aug2009}{...}
{cmd:help intgph} {right:{hi: Bennet Zelner and Dan Blanchette}}
{hline}

{title:Title}

{p2colset 10 20 22 2}{...}
{p2col :{hi:intgph} {hline 2}}Employs King et al.'s (2000) simulation-based approach to interpret interaction effects in 
selected nonlinear models and presents the results graphically in the manner suggested in Zelner (2009){p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 16 2}
{cmd:intgph} {it:modelname}
{cmd:{help varlist:depvar}}
[{it:{help varlist:indepvars}}]
[{it:{help if:if exp}}] [{it:{help in:in range}}] [{it:{help weight:weight}}]
{cmd:,} {cmd:{help intgph ##options:options}}
{p_end}


{synoptset 22 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Required}

{synopt :{opt ivars(varlist)}} names of the two variables to be interacted{p_end}

{syntab:Optional}

{synopt :{opt cmdopts(options)}} valid options for the estimation command specified by {it:modelname}{p_end}
{synopt :{opt l:evel(#)}} a positive integer between {cmd:1} and {cmd:99} (default value is {cmd:95}){p_end}
{synopt :{opt sims(#)}} a positive integer (default value is {cmd:1000}){p_end}
{synopt :{opt setx(options)}} options for {helpb setx} command{p_end}
{synopt :{opt genname(newvars)}} {cmd:genname} option for {helpb estsimp} command{p_end}
{synopt :{opt difvals(numlist)}} pair of values of the second interacted variable used to calculate the difference in predicted
                                  values plotted on the chart's y-axis{p_end}
{synopt :{opt xinc(#)}} positive integer specifying the number of points on the chart's x-axis{p_end}
{synopt :{opt gphdif}} produces a chart showing two sets of predicted values rather than difference in predicted values{p_end}
{synopt :{opt gphsym}} produces chart with symbols denoting statistical significance instead of confidence interval bars{p_end}
{synopt :{opt xt:itle(axis_title)}} title for chart's {cmd:X} axis{p_end}
{synopt :{opt yt:itle(axis_title)}} title for chart's {cmd:Y} axis{p_end}
{synopt :{opt g:phopts(options)}} additional {help twoway_options:twoway options}{p_end}
{synopt :{opt slopet:est(numlist)}} pair of x-axis values used to test corresponding predicted values against the null hypothesis 
                                     that they are equal to one another{p_end}
{synopt :{opt mod:data}} permits dataset in memory to be modified{p_end}
{synopt :{opt verbose}} runs {cmd:intgph} with more output to results window{p_end}


{title:Description}

{pstd}
{cmd:intgph} estimates a selected nonlinear model that includes a multiplicative interaction term, and uses simulated 
parameters generated by King et al.'s (2000) {helpb estsimp} command (part of the "Clarify" suite of commands) 
to evaluate and graphically portray the effect of one interacted variable conditional on different values 
of the other interacted variable. The first interacted variable must be continuous and the second interacted variable 
(whose effect is assessed conditional on the first interacted variable) may be either continuous or binary. Neither of 
the interacted variables should appear in a higher-order term in the model. Currently supported models include 
{helpb logit}, {helpb probit}, {helpb poisson} and {helpb nbreg}{p_end}

{pstd}
The default chart produced by {cmd:intgph} is the type illustrated in Zelner (2009). The y-axis of the chart measures the change 
in the predicted probability of a positive outcome (for {helpb logit} and {helpb probit} models) or incidence (for 
{helpb poisson} and {helpb nbreg} models) associated with a discrete change in the value of the second interacted variable. 
{cmd:intgph} plots this quantity and (by default) the confidence interval that surrounds it against the observed range
of values of the first interacted variable, measured on the x-axis. Alternatively, {cmd:intgph} can also produce a chart
showing the predicted values themselves (rather than the difference in predicted values). {cmd:intgph} optionally creates a
series of new variables that can be used to produce additional charts or conduct hypothesis tests.{p_end}

{marker options}{...}
{title:Options}

{phang}
{opt ivars(varlist)} identifies the two variables, {cmd:ivar1} and {cmd:ivar2}, to be included in the interaction term. 
The variables should not appear explicitly in {it:indepvars}; {cmd:intgph} will automatically add them to the model along with 
the interaction term. {cmd:ivar1} must be continuous and {cmd:ivar2} may be either binary or continuous.{p_end}

{phang}
{opt l:evel(#)} sets the significance level used to plot confidence intervals, conduct hypothesis tests etc. The value of {cmd:level}
must be an integer between {cmd:1} and {cmd:99}. If unspecified, {cmd:level} takes a default value of {cmd:95}.{p_end}

{phang}
{opt cmdopts(options)} allows the user to add command options to the estimation command specified by {it:modelname}. 
Options should be typed as they normally would, e.g., {cmd:cmdopts(vce(r))} produces robust standard errors.{p_end}

{phang}
{opt sims(#)} is a positive integer specifying the number of simulations performed by {helpb estsimp}. The default 
is {cmd:1000} simulations.  For more information, consult the help entry for {helpb estsimp}.{p_end}

{phang}
{opt genname(newvar)} specifies a stub name for the newly created variables containing the simulated coefficient values 
created by {helpb estsimp}. The default variable names are {bind:{cmd:b1}, {cmd:b2}, ... , {cmd:bk}}. For more information, 
consult the help entry for {helpb estsimp}.{p_end}

{phang}
{opt setx(options)} sets the values of the variables in {it:indepvars} for purposes of creating the chart. If the {cmd:setx} 
option is not specified, {cmd:intgph} will automatically set the value of each non-binary variable in {it:indepvars} to its estimating
sample mean, and each binary variable to its estimating sample mode. If the {cmd:setx} option is specified
(using the syntax described in the help entry for {helpb setx}) to assign values to any of the variables in {it:indepvars}, then 
these values will override the default values set by {cmd:intgph}, and the remaining variables in {it:indepvars} will retain their default
values. In no case will the {cmd:setx} option affect the values of {cmd:ivar1} and {cmd:ivar2} used to create the chart.{p_end}

{phang}
{opt difvals(numlist)} sets the two values of the second interacted variable used to calculate the difference in predicted 
values plotted on the chart's y-axis by default. This difference is equal to {bind:{cmd:Pr(Y=1|ivar2 = hi_val) - Pr(Y=1|ivar2 = lo_val)}} 
for {helpb logit} and {helpb probit} models, and {bind:{cmd:E(Y|ivar2 = }{it:hi_val}{cmd:) - E(Y|ivar2 = }{it:lo_val}{cmd:)}} 
for {helpb poisson} and {helpb nbreg} models. If {cmd:difvals} is not specified and {cmd:ivar2} is binary, then {cmd:lo_val} 
takes a default value of {cmd:0} and {cmd:hi_val} takes a default value of 1. If {cmd:difvals} is not specified and {cmd:ivar2} 
is continuous, then {cmd:lo_val} takes a default value of {cmd:ivar2}'s estimating sample mean and {cmd:hi_val} takes a default 
value of {cmd:ivar2}'s estimating sample mean plus one standard deviation. Note that the {opt gphdif} option can be used to plot the predicted values
themselves rather than the difference in predicted values.{p_end}

{phang}
{opt xinc(#)} is a positive integer specifying the number of points on the chart's x-axis for which the values on the y-axis are
calculated and plotted. The x-axis points are evenly spaced between {cmd:ivar2}'s estimating sample minimum and maximum. If {cmd:xinc}
is not specified, it takes a default value of {cmd:100}. Higher values of {cmd:xinc} will increase the amount of time it takes
{cmd:intgph} to run.{p_end}

{phang}
{opt gphdif} produces a chart showing the two sets of predicted values associated with {cmd:lo_val} and {cmd:hi_val} from the
{opt difvals(numlist)} option rather than the difference between these predicted values. If {opt gphdif} is specified, then for
{helpb logit} and {helpb probit} models, the chart will include
separate schedules for {bind:{cmd:Pr(Y=1|ivar2 = hi_val)}} and {bind:{cmd:Pr(Y=1|ivar2 = lo_val)}}, and for {helpb poisson} and
{helpb nbreg} models, the chart will include separate schedules for {bind:{cmd:E(Y|ivar2 = }{it:hi_val}{cmd:)}} and
{bind:{cmd:E(Y|ivar2 = }{it:lo_val}{cmd:)}}.{p_end}

{phang}
{opt gphsym} produces a chart that uses symbols to denote the regions in which the values plotted on the y-axis differ significantly
from zero at the level specified in {opt l:evel(#)}}. If {opt gphsym} is specified, the chart will not include confidence interval bars.{p_end}

{phang}
{opt xt:itle(axis_title)} sets the x-axis title (specified as a string surrounded by quotation marks) for the chart produced 
by {cmd:intgph}. If not specified, the default title for the x-axis is the variable name of {cmd:ivar1}.{p_end}

{phang}
{opt yt:itle(axis_title)} sets the y-axis title (specified as a string surrounded by quotation marks) for the chart produced by 
{cmd:intgph}. If not specified, {cmd:intgph} will choose an appropriate default title.{p_end}

{phang}
{opt g:phopts(options)}} specifies additional {helpb twoway_options} options for the chart. For more information, consult the 
help entry for {helpb twoway_options}.{p_end}

{phang}
{opt slopet:est(numlist)} tests whether the "slope" of a specified segment of the schedule representing the difference in predicted probabilities
in the default chart type (i.e., when {opt gphdif} is not specified) is significantly different from zero at the level specified in {opt l:evel(#)}
(95% by default). Because the confidence intervals calculated by {cmd:intgph} are derived using the simulation-based approach, there is no mathematical
formula for these intervals or related inferential statistics. The "slope" test is thus a test of the null hypothesis that a double difference--the difference
between the difference in predicted values associated with one value of the variable appearing on the x-axis differs from that associated with a second
value--is different from zero. The arguments of {opt slopet:est(numlist)} are the two values of the variable on the x-axis for which one- and two-tailed
versions of this test are performed. {opt slopet:est(numlist)} accepts multiple pairs of x-axis variable values.{p_end}

{phang}
{opt mod:data} instructs {cmd:intgph} to leave variables that it creates in the dataset. These include the simulated coefficient values and the variables used 
to produce the charts: {cmd:X}, which contains the values of {cmd:ivar1} used to plot the chart; {cmd:Y0}, which contains the predicted value associated with 
the first of the two values to which {cmd:ivar2} is set using the {cmd:difvals} option; {cmd:Y1}, which contains the predicted value associated with 
the second of the two values to which {cmd:ivar2} is set using the {cmd:difvals} option; {cmd:dY}, the difference between the predicted values {cmd:Y1} and
{cmd:Y0}; and six variables ending in the stub {cmd:lb} or {cmd:ub}, which respectively represent the lower and upper bounds of the confidence intervals
surrounding {cmd:Y0}, {cmd:Y1}, and {cmd:dY}.{p_end} 

{phang}
{cmd:verbose} creates additional screen output showing the intermediate steps used to construct the chart.{p_end}



{title:Examples}

{pstd}
Setup{p_end}
{phang}
{cmd: . webuse union}{p_end}

{pstd}
Logit model with black and time variables interacted{p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa, ivars(t0 black)}{p_end}

{pstd}
Same as above + robust standard errors{p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa, ivars(t0 black) cmdopts(r)}{p_end}

{pstd}
Same as above + set value of south to 1 when producing the chart{p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa, ivars(t0 black) cmdopts(r) setx(south 1)}{p_end}

{pstd}
Same as above + include second interaction term and set relevant variable values meaningfully{p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa southXt, ivars(t0 black) cmdopts(r) setx(south 1 t0 5 southXt 5)}{p_end}
       
{pstd}
Same as above + perform hypothesis test that Pr(union=1|t0=5) ~=  Pr(union=1|t0=15){p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa southXt, ivars(t0 black) cmdopts(r) setx(south 1 t0 5 southXt 5) slopetest(5 15)}{p_end}

{pstd}
Same as above + plot predicted probabilities rather than difference in predicted probabilities}{p_end}
{phang}
{cmd: . intgph logit union south age grade not_smsa southXt, ivars(t0 black) cmdopts(r) setx(south 1 t0 5 southXt 5) slopetest(5 15) gphdif}{p_end}




{title:Reference}

{pstd}
If you use this program, please cite:{p_end}

{p 8 8 2}
Zelner, Bennet A. 2009. "Using simulation to interpret results{break}
from logit, probit, and other nonlinear models." Strategic{break}
Management Journal. doi: 10.1002/smj.783 (print version forthcoming).{p_end} 
{pstd}
and:{p_end}

{p 8 8 2}
Gary King, Michael Tomz, and Jason Wittenberg. 2000. "Making{break}
the most of statistical analyses: improving interpretation and{break}
presentation." American Journal of Political Science 44, no. 2{break}
(April): 347-61.{p_end}



{title:Authors}

{pstd}
Bennet A. Zelner{break}
Assistant Professor of Strategy{break}
Duke University's Fuqua School of Business{break}
bzelner@duke.edu{p_end}

{pstd}
Dan Blanchette{break}
Center for Entrepreneurship and Innovation{break}
Duke University's Fuqua School of Business{break}
Dan.Blanchette@Duke.edu{p_end}


{title:Also see}

{psee}
Online: {helpb estsimp}, {helpb simqi}, {helpb setx}, {helpb twoway options}, {helpb logit}, {helpb probit}, {helpb poisson} 
and {helpb nbreg}{p_end}