help asmprobit dialog: asmprobit
also see: asmprobit postestimation
-------------------------------------------------------------------------------
Title
[R] asmprobit -- Alternative-specific multinomial probit regression
Syntax
asmprobit depvar [indepvars] [if] [in] [weight], case(varname)
alternatives(varname) [options]
options description
-------------------------------------------------------------------------
Model
* case(varname) use varname to identify cases
* alternatives(varname) use varname to identify the alternatives
available for each case
casevars(varlist) case-specific variables
constraints(constraints) apply specified linear constraints
collinear keep collinear variables
Model 2
correlation(correlation) correlation structure of the
latent-variable errors
stddev(stddev) variance structure of the latent-variable
errors
structural use the structural covariance
parameterization; default is the
differenced covariance parameterization
factor(#) use the factor covariance structure with
dimension #
noconstant suppress the alternative-specific constant
terms
basealternative(#|lbl|str) alternative used for normalizing location
scalealternative(#|lbl|str) alternative used for normalizing scale
altwise use alternative-wise deletion instead of
casewise deletion
SE/Robust
vce(vcetype) vcetype may be oim, robust, cluster
clustvar, opg, bootstrap, or jackknife
Reporting
level(#) set confidence level; default is level(95)
notransform do not transform variance-covariance
estimates to the standard deviation and
correlation metric
nocnsreport do not display constraints
Integration
intmethod(seqtype) type of quasi- or pseudouniform point set
intpoints(#) number of points in each sequence
intburn(#) starting index in the Hammersley or Halton
sequence
intseed(code|#) pseudouniform random-number seed
antithetics use antithetic draws
nopivot do not use integration interval pivoting
initbhhh(#) use the BHHH optimization algorithm for the
first # iterations
favor(speed|space) favor speed or space when generating
integration points
Maximization
maximize_options control the maximization process
+ coeflegend display coefficients' legend instead of
coefficient table
-------------------------------------------------------------------------
correlation description
-------------------------------------------------------------------------
unstructured one correlation parameter for each pair of
alternatives; correlations with the
basealternative() are zero; the default
exchangeable one correlation parameter common to all pairs of
alternatives; correlations with the
basealternative() are zero
independent constrain all correlation parameters to zero
pattern matname user-specified matrix identifying the
correlation pattern
fixed matname user-specified matrix identifying the fixed and
free correlation parameters
-------------------------------------------------------------------------
stddev description
-------------------------------------------------------------------------
heteroskedastic estimate standard deviation for each
alternative; standard deviations for
basealternative() and scalealternative() set
to one
homoskedastic all standard deviations are one
pattern matname user-specified matrix identifying the standard
deviation pattern
fixed matname user-specified matrix identifying the fixed and
free standard deviations
-------------------------------------------------------------------------
seqtype description
-------------------------------------------------------------------------
hammersley Hammersley point set
halton Halton point set
random uniform pseudorandom point set
-------------------------------------------------------------------------
* cases(varname) and alternatives(varname) are required.
+ coeflegend does not appear in the dialog box.
bootstrap, by, jackknife, statsby, and xi are allowed; see prefix.
Weights are not allowed with the bootstrap prefix.
fweights, iweights, and pweights are allowed; see weight.
See [R] asmprobit postestimation for features available after estimation.
Menu
Statistics > Categorical outcomes > Alternative-specific multinomial
probit
Description
asmprobit fits multinomial probit (MNP) models by using maximum simulated
likelihood (MSL) implemented by the Geweke-Hajivassiliou-Keane (GHK)
algorithm. By estimating the variance-covariance parameters of the
latent-variable errors, the model allows you to relax the independence of
irrelevant alternatives (IIA) property that is characteristic of the
multinomial logistic model.
asmprobit requires multiple observations for each case (decision), where
each observation represents an alternative that may be chosen. The cases
are identified by the variable specified in the case() option, whereas
the alternatives are identified by the variable specified in the
alternative() option. The outcome (chosen alternative) is identified by
a value of 1 in depvar, with 0 indicating the alternatives that were not
chosen; only one alternative may be chosen for each case.
asmprobit allows two types of independent variables:
alternative-specific variables and case-specific variables.
Alternative-specific variables vary across both cases and alternatives
and are specified in indepvars. Case-specific variables vary only across
cases and are specified in the casevars() option.
Options
+-------+
----+ Model +------------------------------------------------------------
case(varname) specifies the variable that identifies each case. This
variable identifies the individuals or entities making a choice.
case() is required.
alternatives(varname) specifies the variable that identifies the
alternatives for each case. The number of alternatives can vary with
each case; the maximum number of alternatives is 20. alternatives()
is required.
casevars(varlist) specifies the case-specific variables that are constant
for each case(). If there are a maximum of J alternatives, there will
be J-1 sets of coefficients associated with casevars().
constraints(constraints), collinear; see [R] estimation options.
+---------+
----+ Model 2 +----------------------------------------------------------
correlation(correlation) specifies the correlation structure of the
latent-variable errors.
correlation(unstructured) is the most general and has J(J-3)/2+1
unique correlation parameters. This is the default unless
stdev() or structural are specified.
correlation(exchangeable) provides for one correlation coefficient
common to all latent variables, except the latent variable
associated with the basealternative() option.
correlation(independent) assumes that all correlations are zero.
correlation(pattern matname) and correlation(fixed matname) give you
more flexibility in defining the correlation structure. See
Variance structures in [R] asmprobit for more information.
stddev(stddev) specifies the variance structure of the latent-variable
errors.
stddev(heteroskedastic) is the most general and has J-2 estimable
parameters. The standard deviations of the latent-variable
errors for the alternatives specified in basealternative() and
scalealternative() are fixed to one.
stddev(homoskedastic) constrains all the standard deviations to equal
one.
stddev(pattern matname) or stddev(fixed matname) give you added
flexibility in defining the standard deviation parameters. See
Variance structures in [R] asmprobit for more information.
structural requests the J x J structural covariance parameterization
instead of the default J-1 x J-1 differenced covariance
parameterization (the covariance of the latent errors differenced
with that of the base alternative). The differenced covariance
parameterization will achieve the same MSL regardless of the choice
of basealternative() and scalealternative(). On the other hand, the
structural covariance parameterization imposes more normalizations
that may bound the model away from its maximum likelihood and thus
prevent convergence with some datasets or choices of
basealternative() and scalealternative().
factor(#) requests that the factor covariance structure of dimension # be
used. The factor() option can be used with the structural option but
cannot be used with stddev() or correlation(). A # x J (or # x J-1)
matrix, C, is used to factor the covariance matrix as I + C'C, where
I is the identity matrix of dimension J (or J-1). The column
dimension of C depends on whether the covariance is structural or
differenced. The row dimension of C, #, must be less than or equal
to floor((J(J-1)/2-1)/(J-2)), because there are only J(J-1)/2-1
identifiable variance-covariance parameters. This covariance
parameterization may be useful for reducing the number of covariance
parameters that need to be estimated.
If the covariance is structural, the column of C corresponding to the
base alternative contains zeros. The column corresponding to the
scale alternative has a one in the first row and zeros elsewhere. If
the covariance is differenced, the column corresponding to the scale
alternative (differenced with the base) has a one in the first row
and zeros elsewhere.
noconstant suppresses the J-1 alternative-specific constant terms.
basealternative(#|lbl|str) specifies the alternative used to normalize
the latent-variable location (also referred to as the level of
utility). The base alternative may be specified as a number, label,
or string. The standard deviation for the latent-variable error
associated with the base alternative is fixed to one, and its
correlations with all other latent-variable errors are set to zero.
The default is the first alternative when sorted. If a fixed or
pattern matrix is given in the stddev() and correlation() options,
the basealternative() will be implied by the fixed standard
deviations and correlations in the matrix specifications.
basealternative() cannot be equal to scalealternative().
scalealternative(#|lbl|str) specifies the alternative used to normalize
the latent-variable scale (also referred to as the scale of utility).
The scale alternative may be specified as a number, label, or string.
The default is to use the second alternative when sorted. If a fixed
or pattern matrix is given in the stddev() option, the
scalealternative() will be implied by the fixed standard deviations
in the matrix specification. scalealternative() cannot be equal to
the basealternative().
If a fixed or pattern matrix is given for the stddev() option, the
base alternative and scale alternative are implied by the standard
deviations and correlations in the matrix specifications, and they
need not be specified in the basealternative() and scalealternative()
options.
altwise specifies that alternative-wise deletion be used when marking out
observations due to missing values in your variables. The default is
to use casewise deletion; that is, the entire group of observations
making up a case is deleted if any missing values are encountered.
This option does not apply to observations that are marked out by the
if or in qualifier or the by prefix.
+-----------+
----+ SE/Robust +--------------------------------------------------------
vce(vcetype) specifies the type of standard error reported, which
includes types that are derived from asymptotic theory, that are
robust to some kinds of misspecification, that allow for intragroup
correlation, and that use bootstrap or jackknife methods; see [R]
vce_option.
If specifying vce(bootstrap) or vce(jackknife), you must also specify
basealternative() and scalealternative().
+-----------+
----+ Reporting +--------------------------------------------------------
level(#); see [R] estimation options.
notransform prevents retransforming the Cholesky-factored
variance-covariance estimates to the correlation and standard
deviation metric.
This option has no effect if structural is not specified because the
default differenced variance-covariance estimates have no interesting
interpretation as correlations and standard deviations. notransform
also has no effect if the correlation() and stddev() options are
specified with anything other than their default values. Here it is
generally not possible to factor the variance-covariance matrix, so
optimization is already performed using the standard deviation and
correlation representations.
nocnsreport; see [R] estimation options.
+-------------+
----+ Integration +------------------------------------------------------
intmethod(hammersley|halton|random) specifies the method of generating
the point sets used in the quasi-Monte Carlo integration of the
multivariate normal density. intmethod(hammersley), the default,
uses the Hammersley sequence; intmethod(halton) uses the Halton
sequence; and intmethod(random) uses a sequence of uniform random
numbers.
intpoints(#) specifies the number of points to use in the quasi-Monte
Carlo integration. If this option is not specified, the number of
points is 50 x J if intmethod(hammersley) or intmethod(halton) is
used and 100 x J if intmethod(random) is used. Larger values of
intpoints() provide better approximations of the log likelihood, but
at the cost of added computation time.
intburn(#) specifies where in the Hammersley or Halton sequence to start,
which helps reduce the correlation between the sequences of each
dimension. The default is 0. This option may not be specified with
intmethod(random).
intseed(code|#) specifies the seed to use for generating the uniform
pseudorandom sequence. This option may be specified only with
intmethod(random). code refers to a string that records the state of
the random-number generator runiform(); see [R] set seed. An integer
value # may be used also. The default is to use the current seed
value from Stata's uniform random-number generator, which can be
obtained from c(seed).
antithetics specifies that antithetic draws be used. The antithetic draw
for the J - 1 vector uniform-random variables, x, is 1 - x.
nopivot turns off integration interval pivoting. By default, asmprobit
will pivot the wider intervals of integration to the interior of the
multivariate integration. This improves the accuracy of the
quadrature estimate. However, discontinuities may result in the
computation of numerical second-order derivatives using finite
differencing (for the Newton-Raphson optimize technique, tech(nr))
when few simulation points are used, resulting in a
nonpositive-definite Hessian. asmprobit uses the
Broyden-Fletcher-Goldfarb-Shanno optimization algorithm, by default,
which does not require computing the Hessian numerically using finite
differencing.
initbhhh(#) specifies that the Berndt-Hall-Hall-Hausman (BHHH) algorithm
be used for the initial # optimization steps. This option is the
only way to use the BHHH algorithm along with other optimization
techniques. The algorithm switching feature of ml's technique()
option cannot include bhhh.
favor(speed|space) instructs asmprobit to favor either speed or space
when generating the integration points. favor(speed) is the default.
When favoring speed, the integration points are generated once and
stored in memory, thus increasing the speed of evaluating the
likelihood. This speed increase can be seen when there are many
cases or when the user specifies a large number of integration
points, intpoints(#). When favoring space, the integration points
are generated repeatedly with each likelihood evaluation.
For unbalanced data, where the number of alternatives varies with
each case, the estimates computed using intmethod(random) will vary
slightly between favor(speed) and favor(space). This is because the
uniform sequences will not be identical, even when initiating the
sequences using the same uniform seed, intseed(code|#). For
favor(speed), ncase blocks of intpoints(#) X J-2 uniform points are
generated, where J is the maximum number of alternatives. For
favor(space), the column dimension of the matrices of points varies
with the number of alternatives that each case has.
+--------------+
----+ Maximization +-----------------------------------------------------
maximize_options: difficult, technique(algorithm_spec), iterate(#),
[no]log, trace, gradient, showstep, hessian, showtolerance,
tolerance(#), ltolerance(#), nrtolerance(#), nonrtolerance,
from(init_specs); see [R] maximize.
The following options may be particularly useful in obtaining
convergence with asmprobit: difficult, technique(algorithm_spec),
nrtolerance(#), nonrtolerance, and from(init_specs).
If technique() contains more than one algorithm specification, bhhh
cannot be one of them. To use the BHHH algorithm with another
algorithm, use the initbhhh() option and specify the other algorithm
in technique().
Setting the optimization type to technique(bhhh) resets the default
vcetype to vce(opg).
The following option is available with asmprobit but is not shown in the
dialog box:
coeflegend; see [R] estimation options.
Examples
Setup
. webuse travel
Fit alternative-specific multinomial probit model by using the default
differenced covariance parameterization
. asmprobit choice travelcost termtime, casevars(income) case(id)
alternatives(mode)
Same as above, but use the structural covariance parameterization
. asmprobit choice travelcost termtime, casevars(income) case(id)
alternatives(mode) structural
Same as above, but specify an exchangeable correlation matrix
. asmprobit choice travelcost termtime, casevars(income) case(id)
alternatives(mode) correlation(exchangeable)
Saved results
asmprobit saves the following in e():
Scalars
e(N) number of observations
e(N_case) number of cases
e(k) number of parameters
e(k_alt) number of alternatives
e(k_indvars) number of alternative-specific variables
e(k_casevars) number of case-specific variables
e(k_sigma) number of variance estimates
e(k_rho) number of correlation estimates
e(k_eq) number of equations in e(b)
e(k_eq_model) number of equations in model Wald test
e(k_autoCns) number of base, empty, and omitted constraints
e(df_m) model degrees of freedom
e(ll) log simulated-likelihood
e(N_clust) number of clusters
e(const) constant indicator
e(i_base) base alternative index
e(i_scale) scale alternative index
e(mc_points) number of Monte Carlo replications
e(mc_burn) starting sequence index
e(mc_antithetics) antithetics indicator
e(chi2) chi-squared
e(p) significance
e(fullcov) unstructured covariance indicator
e(structcov) 1 if structured covariance; 0 otherwise
e(cholesky) Cholesky-factored covariance indicator
e(alt_min) minimum number of alternatives
e(alt_avg) average number of alternatives
e(alt_max) maximum number of alternatives
e(rank) rank of e(V)
e(ic) number of iterations
e(rc) return code
e(converged) 1 if converged, 0 otherwise
Macros
e(cmd) asmprobit
e(cmdline) command as typed
e(depvar) name of dependent variable
e(indvars) alternative-specific independent variable
e(casevars) case-specific variables
e(case) variable defining cases
e(altvar) variable defining alternatives
e(alteqs) alternative equation names
e(alt#) alternative labels
e(wtype) weight type
e(wexp) weight expression
e(title) title in estimation output
e(clustvar) name of cluster variable
e(correlation) correlation structure
e(stddev) variance structure
e(cov_class) class of the covariance structure
e(chi2type) Wald, type of model chi-squared test
e(vce) vcetype specified in vce()
e(vcetype) title used to label Std. Err.
e(opt) type of optimization
e(which) max or min; whether optimizer is to perform
maximization or minimization
e(ml_method) type of ml method
e(mc_method) technique used to generate sequences
e(mc_seed) random-number generator seed
e(user) name of likelihood-evaluator program
e(technique) maximization technique
e(singularHmethod) m-marquardt or hybrid; method used when
Hessian is singular
e(crittype) optimization criterion
e(datasignature) the checksum
e(datasignaturevars) variables used in calculation of checksum
e(properties) b V
e(estat_cmd) program used to implement estat
e(mfx_dlg) program used to implement estat mfx dialog
e(predict) program used to implement predict
e(marginsnotok) predictions disallowed by margins
Matrices
e(b) coefficient vector
e(Cns) constraints matrix
e(stats) alternative statistics
e(stdpattern) variance pattern
e(stdfixed) fixed and free standard deviations
e(altvals) alternative values
e(altfreq) alternative frequencies
e(alt_casevars) indicators for estimated case-specific
coefficients -- e(k_alt) x e(k_casevars)
e(corpattern) correlation structure
e(corfixed) fixed and free correlations
e(ilog) iteration log (up to 20 iterations)
e(gradient) gradient vector
e(V) variance-covariance matrix of the estimators
e(V_modelbased) model-based variance
Functions
e(sample) marks estimation sample
Also see
Manual: [R] asmprobit
Help: [R] asmprobit postestimation;
[R] asclogit, [R] asroprobit, [R] mlogit, [R] mprobit
