**[R] asroprobit** -- Alternative-specific rank-ordered probit regression

__Syntax__

**asroprobit** *depvar* [*indepvars*] [*if*] [*in*] [*weight*] **,** **case(***varname***)**
__alt__**ernatives(***varname***)** [*options*]

*options* Description
-------------------------------------------------------------------------
Model
* **case(***varname***)** use *varname* to identify cases
* __alt__**ernatives(***varname***)** use *varname* to identify the alternatives
available for each case
__casev__**ars(***varlist***)** case-specific variables
__const__**raints(***constraints***)** apply specified linear constraints
__col__**linear** keep collinear variables

Model 2
__corr__**elation(***correlation***)** correlation structure of the
latent-variable errors
__std__**dev(***stddev***)** variance structure of the latent-variable
errors
__struc__**tural** use the structural covariance
parameterization; default is the
differenced covariance parameterization
__fact__**or(***#***)** use the factor covariance structure with
dimension *#*
__nocons__**tant** suppress the alternative-specific constant
terms
__base__**alternative(***#*|*lbl*|*str***)** alternative used for normalizing location
__scale__**alternative(***#*|*lbl*|*str***)** alternative used for normalizing scale
**altwise** use alternativewise deletion instead of
casewise deletion
__rev__**erse** interpret the lowest rank in *depvar* as the
best; the default is the highest rank is
the best

SE/Robust
**vce(***vcetype***)** *vcetype* may be **oim**, __r__**obust**, __cl__**uster**
*clustvar*, **opg**, __boot__**strap**, or __jack__**knife**

Reporting
__l__**evel(***#***)** set confidence level; default is **level(95)**
__notran__**sform** do not transform variance-covariance
estimates to the standard deviation and
correlation metric
__nocnsr__**eport** do not display constraints
*display_options* control columns and column formats, row
spacing, line width, display of omitted
variables and base and empty cells, and
factor-variable labeling

Integration
__intm__**ethod(***seqtype***)** type of quasi- or pseudouniform sequence
__intp__**oints(***#***)** number of points in each sequence
__intb__**urn(***#***)** starting index in the Hammersley or Halton
sequence
__ints__**eed(***code*|*#***)** pseudouniform random-number seed
__anti__**thetics** use antithetic draws
__nopiv__**ot** do not use integration interval pivoting
__initb__**hhh(***#***)** use the BHHH optimization algorithm for the
first *#* iterations
**favor(**__spe__**ed**|__spa__**ce)** favor speed or space when generating
integration points

Maximization
*maximize_options* control the maximization process

__coefl__**egend** display legend instead of statistics
-------------------------------------------------------------------------

*correlation* Description
-------------------------------------------------------------------------
__uns__**tructured** one correlation parameter for each pair of
alternatives; correlations with the
**basealternative()** are zero; the default
__exc__**hangeable** one correlation parameter common to all pairs of
alternatives; correlations with the
**basealternative()** are zero
__ind__**ependent** constrain all correlation parameters to zero
__pat__**tern** *matname* user-specified matrix identifying the
correlation pattern
__fix__**ed** *matname* user-specified matrix identifying the fixed and
free correlation parameters
-------------------------------------------------------------------------

*stddev* Description
-------------------------------------------------------------------------
__het__**eroskedastic** estimate standard deviation for each
alternative; standard deviations for
**basealternative()** and **scalealternative()** set
to one
__hom__**oskedastic** all standard deviations are one
__pat__**tern** *matname* user-specified matrix identifying the standard
deviation pattern
__fix__**ed** *matname* user-specified matrix identifying the fixed and
free standard deviations
-------------------------------------------------------------------------

*seqtype* Description
-------------------------------------------------------------------------
__ham__**mersley** Hammersley point set
__hal__**ton** Halton point set
__ran__**dom** uniform pseudorandom point set
-------------------------------------------------------------------------

* **case(***varname***)** and **alternatives(***varname***)** are required.
*indepvars* and *varlist* may contain factor variables; see fvvarlist.
**bootstrap**, **by**, **jackknife**, and **statsby** are allowed; see prefix.
Weights are not allowed with the **bootstrap** prefix.
**fweight**s, **iweight**s, and **pweight**s are allowed; see weight.
**coeflegend** does not appear in the dialog box.
See **[R] asroprobit postestimation** for features available after
estimation.

__Menu__

**Statistics > Ordinal outcomes > Rank-ordered probit regression**

__Description__

**asroprobit** fits rank-ordered probit (ROP) models by using maximum
simulated likelihood (MSL). The model allows you to relax the
independence of irrelevant alternatives (IIA) property that is
characteristic of the rank-ordered logistic model by estimating the
variance-covariance parameters of the latent-variable errors. Each
unique identifier in the **case()** variable has multiple alternatives
identified in the **alternatives()** variable, and *depvar* contains the ranked
alternatives made by each case. Only the order in the ranks, not the
magnitude of their differences, is assumed to be relevant. By default,
the largest rank indicates the more desirable alternative. Use the
**reverse** option if the lowest rank should be interpreted as the more
desirable alternative. Tied ranks are allowed, but they increase the
computation time because all permutations of the tied ranks are used in
computing the likelihood for each case. **asroprobit** allows two types of
independent variables: alternative-specific variables, in which the
values of each variable vary with each alternative, and case-specific
variables, which vary with each case.

The estimation technique of **asroprobit** is nearly identical to that of
**asmprobit**, and the two routines share many of the same options; see **[R]**
**asmprobit**.

__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 alternativewise 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.

**reverse** directs **asroprobit** to interpret the rank in *depvar* that is
smallest in value as the preferred alternative. By default, the rank
that is the largest in value is the favored alternative.

+-----------+
----+ SE/Robust +--------------------------------------------------------

**vce(***vcetype***)** specifies the type of standard error reported, which
includes types that are derived from asymptotic theory (**oim**, **opg**),
that are robust to some kinds of misspecification (**robust**), that
allow for intragroup correlation (**cluster** *clustvar*), and that use
bootstrap or jackknife methods (**bootstrap**, **jackknife**); 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**.

*display_options*: **noci**, __nopv__**alues**, __noomit__**ted**, **vsquish**, __noempty__**cells**,
__base__**levels**, __allbase__**levels**, __nofvlab__**el**, **fvwrap(***#***)**, **fvwrapon(***style***)**,
**cformat(***%fmt***)**, **pformat(%***fmt***)**, **sformat(%***fmt***)**, and **nolstretch**; 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(rngstate)**.

**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, **asroprobit**
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
non-positive-definite Hessian. **asroprobit** 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 **asroprobit** 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*: __dif__**ficult**, __tech__**nique(***algorithm_spec***)**, __iter__**ate(***#***)**,
[__no__]__lo__**g**, __tr__**ace**, __grad__**ient**, **showstep**, __hess__**ian**, __showtol__**erance**,
__tol__**erance(***#***)**, __ltol__**erance(***#***)**, __nrtol__**erance(***#***)**, __nonrtol__**erance**, and
**from(***init_specs***)**; see **[R] maximize**.

The following options may be particularly useful in obtaining
convergence with **asroprobit**: **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)**.

When specifying **from(***matname* [**, copy**]**)**, the values in *matname*
associated with the latent-variable error variances must be for the
log-transformed standard deviations and inverse-hyperbolic
tangent-transformed correlations. This option makes using the
coefficient vector from a previously fitted **asroprobit** model
convenient as a starting point.

The following option is available with **asroprobit** but is not shown in the
dialog box:

**coeflegend**; see **[R] estimation options**.

__Examples__

Setup
**. webuse wlsrank**

Fit alternative-specific rank-ordered probit model, excluding cases with
tied ranks; specify that lowest **rank** is most preferred
**. asroprobit rank high low if noties,** **case(id) alternatives(jobchar)**
**casevars(female score) reverse**

Specify exchangeable correlation model for latent-variable errors
**. asroprobit rank high low if noties,** **case(id) alternatives(jobchar)**
**casevars(female score)** **reverse correlation(exchangeable)**

__Stored results__

**asroprobit** stores the following in **e()**:

Scalars
**e(N)** number of observations
**e(N_case)** number of cases
**e(N_ties)** number of ties
**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 overall model test
**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(reverse)** **1** if minimum rank is best, **0** if maximum rank
is best
**e(chi2)** chi-squared
**e(p)** p-value for model test
**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)** **asroprobit**
**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(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)** **Hammersley**, **Halton**, or **uniform random**;
technique to generate sequences
**e(mc_rngstate)** random-number state used
**e(user)** name of likelihood-evaluator program
**e(technique)** maximization technique
**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**
**e(asbalanced)** factor variables **fvset** as **asbalanced**
**e(asobserved)** factor variables **fvset** as **asobserved**

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