{smcl}
{* 02Oct2004}
{...} 
{hline}
help for {hi:mlboolean},{hi:mlboolfirst}
{hline}

{title:Boolean Logit and Probit}

{p 4 12 2}{cmd:mlboolean} {it:link_function} {it:n} ({it:calculus})
({it:depvar}) ({it:indepvars1}) ({it:indepvars2}) ...
{cmd:ystar(}{it:varname}{cmd:)}{cmd:,} {it:ml_options}


The syntax of {cmd:mlboolfirst} after {cmd:mlboolean} is

{p 4 12 2}{cmd:mlboolfirst} {it:indepvar}


{title:Description}

{p 0 0 2}{cmd:mlboolean} conducts a maximum-likelihood Boolean logit or
probit estimation (see Braumoeller 2003) in which there are multiple
causal "paths" to a given outcome or nonoutcome.  Each of the {it:n}
paths is modeled as a standard logit or probit curve, and the predicted
values for all of the curves cumulate in a manner described by a Boolean
probability calculus (for example, a and (b or c) cause y) to produce
the observed binary dependent variable.

{p 4 4 2} {ul:Example}. Imagine that in a given firm there are three
ways in which an employee can be fired: as a result of embezzlement, as
a result of poor performance, or as a result of a combination of
company-wide budget cutbacks and a low position in the company's
hierarchy.  We know whether each employee was fired, how much he or she
embezzled, some general indicators of job performance (on-time
percentage, recent customer service ratings, and recent overall
performance ratings), changes in the company's earnings and stock value,
and where the employee's position is in the company hierarchy.  We do
not know the combination of reasons that resulted in termination.  This
gives a system with four unobserved variables, modeled here as standard
probit equations

{p 8 8 2}y1* = norm(b1 + b2(embezzle))

{p 8 8 2}y2* = norm(b3 + b4(ontime) + b5(custserv) + b6(performance))

{p 8 8 2}y3* = norm(b7 + b8(earnings) + b9(stock))

{p 8 8 2}y4* = norm(b10 + b11(hierarchy)),

{p 4 4 2}and an observed dependent variable that is the binary
realization of an underlying process of the form

{p 8 8 2}p(fired) = 1 - (1-y1*) x (1-y2*) x (1-(y3* x y4*))

{p 4 4 2}{c -} that is, y1 or y2 or (y3 and y4) cause termination.  We
might then estimate an equation of the following form:

{p 8 8 2}{inp:. mlboolean probit 4 (aorbor(candd)) (fired) (embezzle) (ontime custserv performance) (earnings stock) (hierarchy)}

{p 4 4 2}The predicted values for "fired" and for the various yn* are
estimated automatically (see "Saved Variables," below).


{p 0 0 2}{cmd:mlboolfirst} calculates and graphs predicted values for a
given independent variable.  All other variables are set to their means
except for variables of type int, which are set to their modal values.
Similarly, predictions are plotted as curves for continuous variables and 
points for integers.  To manipulate whether or not {cmd:mlboolfirst} 
flags the variable as an integer, simply use the {help recast} command.


{title:Required Input}

{p 0 0 2}{cmd:mlboolean} requires the following, in order:

{p 4 4 2}A link function (either {it:logit} or {it:probit}).

{p 4 4 2}The number of causal paths {it:n} ({it:n} ² 5).

{p 4 4 2}The probability calculus that describes how they cumulate,
using "a" to denote y1*, "b" to denote y2*, and so on, connected by
"and" or "or".

{p 12 12 2}{ul:Examples}: (aorborc), ((aorb)andcandd).

{p 4 4 2}The binary dependent variable, in parentheses.

{p 4 4 2}{it:n} sets of independent variables, in parentheses.  The
independent variables can overlap partially {c -} for example, one set
might consist of x1-x4 and another of x1, x2, x5 and x6 if the
probabilities of the antecedent events in question are thought to be
correlated because each is influenced by x1 and x2.


{title:Options}

{p 0 4 2} {cmd:ystar(}{it:varname}{cmd:)} specifies the names of the
variables that will contain the predicted values of the latent variables
associated with each of the {it:n} "paths" (see "Saved Variables").  The
default is {cmd:ystar(ystar)}.

{p 0 0 2}{it:ml_options:} All other options are passed directly to
{cmd:ml}, so any options that  work with the latter should work with the
former.  See the {help ml} documentation for further details.  It is
worth noting, however, that some of these options are particularly
relevant in the context of {cmd:mlboolean}:

{p 0 4 2}{cmd:gtolerance(}{it:#}{cmd:)} specifies an optional tolerance
for the gradient relative to the coefficients. When |g*b| <=
{cmd:gtolerance()} for all parameters b_i and the corresponding elements
of the gradient g_i, then the gradient tolerance criterion is met.
Unlike {cmd:tolerance()} and {cmd:ltolerance()}, the {cmd:gtolerance()}
criterion must be met in addition to any other tolerance.  That is,
convergence is declared when {cmd:gtolerance()} is met and
{cmd:tolerance()} or {cmd:ltolerance()} is also met.  The
{cmd:gtolerance()} option is provided for particularly deceptive
likelihood functions that may trigger premature declarations of
convergence.  The option must be specified for gradient checking to be
activated; by default the gradient is not checked.

{p 0 4 2}{cmd:lf0(}{it:#k #ll}{cmd:)} specifies the number of parameters
and log-likelihood value of the "constant-only" model so that
{cmd:mlboolean} can report a likelihood-ratio test rather than a Wald
test.

{p 0 4 2}{cmd:difficult} specifies that the likelihood function is
likely to be difficult to maximize.  In particular, {cmd:difficult}
states that there may be regions where -H is not invertible and that, in
those regions, Stata's standard fixup may not work well. 
{cmd:difficult} specifies that a different fixup requiring substantially
more computer time is to be used.  {cmd:difficult} can be of some help
in obtaining "normal" parameter estimates when plateaus in profile
likelihoods produce absurdly large standard errors; it can also make
things worse.  Such situations are typically indicative of a dangerous
lack of information and should be treated with caution.

{p 0 4 2}{cmd:init(}{it:ml_init_args}{cmd:)} sets the initial parameter
values. Because {cmd:mlboolean} can produce convoluted likelihood
functions, the wise investigator will try an array of different starting
values before reporting final results.

{p 0 4 2}{cmd:nrtolerance(}{it:#}{cmd:)} specifies an optional tolerance
that is based on the gradient g and Hessian H.  The tolerance is met
when g*inv(H)*g' < {cmd:gtolerance()}.  Like {cmd:gtolerance()}, the
{cmd:nrtolerance()} criterion must be met in addition to any other
tolerance.  This option must be specified for g*inv(H)*g' to be checked;
by default it is not.

{p 0 4 2}{cmd:technique()} specifies how the likelihood function is to
be maximized.  The following algorithms are currently implemented in
{help ml}.

{p 4 8 2} {cmd:technique(nr)} specifies Stata's modified Newton-Raphson
(NR) algorithm.

{p 4 8 2} {cmd:technique(bhhh)} specifies the Berndt-Hall-Hall-Hausman
(BHHH) algorithm.

{p 4 8 2} {cmd:technique(dfp)} specifies Davidon-Fletcher-Powell (DFP)
algorithm.

{p 4 8 2} {cmd:technique(bfgs)} specifies the
Broyden-Fletcher-Goldfarb-Shanno (BFGS) algorithm.

{p 4 4 2} It is possible to switch between algorithms by specifying more
than one in the {cmd:technique()} option.  For example, specifying
{cmd:technique(bhhh} {cmd:dfp)} will cause {cmd:ml} to switch between
the BHHH and DFP algorithms. {cmd:ml} will use an algorithm for 5
iterations, by default, before switching to the next algorithm.  Thus
{cmd:technique(bhhh dfp)} will cause {cmd:ml} to switch between BHHH and
DFP every 5 iterations.  You may specify a different number of
iterations for each algorithm by including a count after it.  For
example {cmd:technique(bhhh 10 nr 1000)} will cause {cmd:ml} to optimize
the likelihood using BHHH for 10 iterations before switching to the
modified Newton-Raphson algorithm, then switch back to BHHH after
{cmd:ml} spends 1000 iterations using NR.


{p 0 4 2}{cmd:search(on}|{cmd:quietly}|{cmd:off)} specifies whether
{cmd:ml search} is to be used to improve the initial values.  Note that
{cmd:search(on)} is the default.

{p 0 4 2}{cmd:nowarning} is allowed only with {cmd:iterate(0)}. 
{cmd:nowarning} suppresses the "convergence not achieved" message.  Not
remotely recommended.


{title:Saved Variables}

{p 0 4 2}{inp:{it:boolpred}}: Predicted probability of occurrence of
dependent variable in a given case.

{p 0 4 2}{inp:{it:ystar_n}}: Predicted values of latent variables
associated with each of the {it:n} "paths."  Variable names can be
changed with the {cmd:ystar(}{it:varname}{cmd:)} option, above; default
is {cmd:ystar(}ystar{cmd:)}.

{p 4 4 2}{ul:Example}. In the job-termination example above, we might
estimate for a given employee that the probability of termination due to
embezzlement ({it:ystar_a}) is 0.1, the probability of termination due
to poor performance ({it:ystar_b}) is 0.5, the probability that cutbacks
will occur given the company's recent performance ({it:ystar_c}) is 0.7,
and the probability that the employee will be vulnerable to cutbacks
should they occur ({it:ystar_d}) is 0.6.  In that case, the prediction
would be that the employee will be fired with probability
1-((1-0.1)x(1-0.5)x(1-(0.6x0.7))), or 73.9%.


{title:Examples}

{p 8 12 2}{inp:. mlboolean logit 2 (aandb) (y) (x1 x2) (x3)}

{p 8 12 2}{inp:. mlboolean probit 4 ((aandb)or(candd)) (y) (x1 x2) (x3 x4 x5) (x6 x7) (x8), difficult}

{p 8 12 2}{inp:. mlboolean logit 2 (aandb) (plantliv) (H2O) (sunlite lamplite), robust}

{p 8 12 2}{inp:. mlboolean probit 3 (aorborc) (nonvoter) (apathy) (alienation) (indifference) [pweight=weight]}

{p 8 12 2}{inp:. mlboolean probit 3 (aand(borc)) (y) (x1 x2) (x1 x3 x4) (x5 x6), init(Path1:x1=0 Path1:x2=0 Path2:x1=0 Path2:x3=0 Path2:x4=0 Path3:x5=0 Path3:x6=0)}

{p 8 12 2}{inp:. probit dv}

{p 8 12 2}{inp:. mlboolean probit 2 (aandb) (dv) (x1 x2) (x1 x3 x4), lf0(1 -2517.1859)}



{title:Known Issues}

{p 0 4 2}The maximum number of paths is five.

{p 0 4 2}Partial observability routines are generically starved for
information, and this one is no different.  The routine requires
substantial variation for each independent variable at different levels
of all of the others.  The warning sign of the absence of such variation
is exploding standard errors, which typically correspond to plateaus in
the relevant profile likelihood.  This is an indicator that more data
are required.

{p 0 4 2}The probability calculus must contain as few parentheses as
logically possible; otherwise it will not be recognized.  For example,
((aorb)andcandd) will be recognized, but ((aandb)and(candd)) will not.


{title:Version}

{p 0 4 2}Version 1.3.  Contact bfbraum@fas.harvard.edu with comments or
questions.  Click {browse "http://www.people.fas.harvard.edu/~bfbraum":here} to check for updated versions.


{title:Required Files}

{p 0 4 2} mlboolean.ado, mlboolean.hlp, mlboolfirst.ado, mlboollog.ado,
mlboolpred.ado, mlboolprep.ado, mlboolprob.ado


{title:References}

{p 4 12 2}Braumoeller, Bear F. (2003) {browse "http://www.people.fas.harvard.edu/~bfbraum":"Causal Complexity and the Study of Politics."} {browse "http://www.pan.oupjournals.org/":Political Analysis} 11(3): 209-233.
