help for gologit2 version 3.2.5

Generalized Ordered Logit Models for Ordinal Dependent Variables

gologit2 depvar [indepvars]
[weight] [if exp] [in range]
[,
pl
pl(varlist)
npl
npl(varlist)
autofit
autofit(alpha)
link(logit/probit/cloglog/loglog/cauchit)
force
lrforce waldforce
gamma
gamma(name)
nolabel
mlstart
store(name)
constraints:(clist)
vce(vcetype)
robust
cluster:(varname)
level:(#)
coeflegend
nocnsreport
or log
display_options
maximize_options ]

NOTE!!! gologit2 now supports factor variables as well as the
svy: and user-written gsvy: prefixes.

gologit2 shares the features of all estimation commands; see help
est.
gologit2 typed without arguments redisplays previous results.
The following options may be given when redisplaying results:

gamma
gamma(name)
store(name)
or
level:(#)
coeflegend

gologit2 works under Stata 11.2 or higher. Download and
install gologit29 if you have an older version of Stata.

fweights, iweights, and pweights are
allowed; see help weights.

The syntax of predict following gologit2 is

predict [type] newvarname(s)
[if exp] [in range]
[, statistic outcome:(outcome) ]

where statistic is

p probability (specify one new variable and
outcome() option, or specify k new variables, k = # of
outcomes); the default

xb linear prediction (outcome() option
required)

stdp S.E. of linear prediction (outcome() option
required)

stddp S.E. of difference in linear predictions
(outcome() option is
outcome(outcome1,outcome2))

Note that you specify one new variable with xb, stdp, and
stddp and specify either one or k new variables with p.

These statistics are available both in and out of sample; type
"predict ... if e(sample) ..." if wanted only for the
estimation sample.

Description

gologit2 is a user-written program that estimates
generalized ordered logit models for ordinal dependent variables. The
actual values taken on by the dependent variable are irrelevant except
that larger values are assumed to correspond to "higher" outcomes. Up to
20 outcomes are allowed. gologit2 is inspired by Vincent Fu's
gologit program and is backward compatible with it (and with
gologit29) but offers several additional powerful options, including
support for factor variables and complex survey data estimation.

A major strength of gologit2 is that it can also
estimate three special cases of the generalized model: the
proportional odds/parallel lines model, the partial proportional
odds model, and the logistic regression model. Hence,
gologit2 can estimate models that are less restrictive than the
proportional odds /parallel lines models estimated by ologit
(whose assumptions are often violated) but more parsimonious and
interpretable than those estimated by a non-ordinal method, such as
multinomial logistic regression (i.e. mlogit). The autofit
option greatly simplifies the process of identifying partial
proportional odds models that fit the data.

An alternative but equivalent parameterization of the model
that has appeared in the literature is reported when the gamma
option is selected. Other key advantages of gologit2 include
support for linear constraints (making it possible to use
gologit2 for constrained logistic regression), survey data
estimation, and the computation of estimated probabilities via the
predict command.

Despite the program's name, probit, complementary log-log,
log-log and cauchit links can be used instead of logit by specifying the
link option, e.g. link(l) for logit (the default),
link(p) for probit, link(c) for complementary log-log,
link(ll) for log-log, and link(ca) for cauchit.

gologit2 works under Stata 11.2 and higher. Users of
older versions of Stata should download and install gologit29.

gologit2 now has two major enhancements over earlier
versions of the program: support for factor variables, and support for
the svy prefix. This also means that margins and related
commands should work correctly with gologit2. HOWEVER, when
working with svyset data and the autofit option, it is required
that you use the gsvy prefix rather than the svy prefix.
gsvy has the same syntax as svy but provides customized
support for gologit2's unique options. See the section below
about other cautions when using Stata prefix commands.

More information on the statistical theory behind
gologit2 as well as several worked examples and a troubleshooting
FAQ can be found at https://www3.nd.edu/~rwilliam/gologit2/.

Options

pl, npl, npl(), pl(), autofit
and autofit() provide alternative means for imposing or relaxing
the proportional odds/ parallel lines assumption. Only one may be
specified at a time.

autofit(alpha) uses an iterative process to
identify the partial proportional odds model that best fits the data.
alpha is the desired significance level for the tests; alpha
must be greater than 0 and less than 1. If autofit is specified
without parameters, the default alpha-value is .05. Note that, the
higher alpha is (e.g., .10), the easier it is to reject the
parallel lines assumption, and the less parsimonious the model will tend
to be. Especially when several variables are being tested or the sample
is large, a more stringent alpha-value (e.g. .01) may be called for.
This option can take a while because several models may need to
be estimated. The use of autofit is recommended but the other
options provide more control over the final model. Be careful of using
autofit with prefix commands that can change the sample being estimated
(e.g. bootstrap, mi estimate) as they may result in
different autofitted models for different sample selections.

pl specified without parameters constrains all
independent variables to meet the proportional odds/ parallel lines
assumption. It will produce results that are equivalent to
ologit.

npl specified without parameters relaxes the
proportional odds/ parallel lines assumption for all explanatory
variables. This is the default option and presents results equivalent
to the original gologit.

pl(varlist) constrains the specified
explanatory variables to meet the proportional odds/ parallel lines
assumption. All other variable effects do not need to meet the
assumption. The variables specified must be a subset of the explanatory
variables.

npl(varlist) frees the specified explanatory
variables from meeting the proportional odds/ parallel lines assumption.
All other explanatory variables are constrained to meet the assumption.
The variables specified must be a subset of the explanatory variables.

link(logit/probit/cloglog/loglog/cauchit)
specifies the link function to be used. The legal values are
link(logit), link(probit), link(cloglog),
link(loglog), and link(cauchit), which can be abbreviated as
link(l), link(p), link(c), link(ll) and
link(ca). link(logit) is the default if the option is omitted.

The following advice is adapted from Norusis (2005, p. 84):
Probit and logit models are reasonable choices when the changes in the
cumulative probabilities are gradual. If there are abrupt changes, other
link functions should be used. The log-log link may be a good model when
the cumulative probabilities increase from 0 fairly slowly and then
rapidly approach 1. If the opposite is true, namely that the cumulative
probability for lower scores is high and the approach to 1 is slow, the
complementary log-log link may describe the data. The cauchit
distribution has tails that are bigger than the normal distribution’s,
hence the cauchit link may be useful when you have more extreme values
in either direction.

NOTE: Programs differ in the names used for these latter two
links. Stata's loglog link corresponds to SPSS PLUM's cloglog link; and
Stata's cloglog link is called nloglog in SPSS.

force can be used to force gologit2 to issue only
warning messages in some situations when it would normally give a fatal
error:

By default, the dependent variable can have a maximum of 20
categories. A variable with more categories than that is probably a
mistaken entry by the user, e.g. a continuous variable has been
specified rather than an ordinal one. But, if your dependent variable
really is ordinal with more than 20 categories, force will let
gologit2 analyze it (although other practical limitations, such
as small sample sizes within categories, may keep it from coming up with
a final solution.)

Also, variables specified in npl(varlist) and
pl(varlist) are required to be a subset of the explanatory variables.
However, prefix commands like sw and nestreg estimate models
that may use only a subset of the X variables, and those subsets may not
include all the variable specified in the npl/pl varlists. Using
force will allow model estimation to continue in those cases.

Obviously, you should only use force when you are
confident that you are not making a mistake.

lrforce forces Stata to report a Likelihood Ratio
Statistic under certain conditions when it ordinarily would not. Note
that the lrforce option will be ignored when robust standard
errors are specified either directly or indirectly, e.g. via use of the
robust or svy: options. THIS OPTION IS NOW THE DEFAULT. and
is included for compatibility with earlier versions of gologit2. Use
waldforce to override.

waldforce forces Stata to report a Wald Statistic even
when a Likelihood Ratio statistic is possible. Some types of constraints
can make a Likelihood Ratio chi-square test invalid. But, Likelihood
Ratio statistics should be correct for the types of constraints imposed
by the pl and npl commands. Use waldforce if you are
imposing additional constraints of your own and are not sure a
Likelihood Ratio test is appropriate.

store(name) causes the command
estimates store name to be executed when gologit2 finishes.
This is useful for when you wish to estimate a series of models and want to save
the results. This option can also be specified when replaying the results.

gamma displays an alternative but equivalent
parameterization of the partial proportional odds model used by Peterson
and Harrell (1990) and Lall et al (2002). Under this parameterization,
there is one Beta coefficient and M-2 Gamma coefficients for each
explanatory variable, where M = the number of categories for Y. The
gammas indicate the extent to which the proportional odds assumption is
violated by the variable, i.e. when the gammas do not significantly
differ from 0 the proportional odds assumption is met. Advantages of
this parameterization include the fact that it is more parsimonious than
the default layout. In addition, by examining the test statistics for
the Gammas, you can get a feel for which variables meet the
proportionality assumption and which do not.

gamma(name) causes the gamma estimates to be stored as
name, e.g. g(gamma1) would store the gamma estimates under
the name gamma1. This makes the gamma results easily usable with
post- estimation table formatting commands like outreg2 and
estout. Do NOT try to make the gamma results active and then use
other post-estimation commands, e.g. predict or test. Such
commands either will not work or, if they do work, may give incorrect
results. Note that only the variances and standard errors of the gamma
estimates are correct; all the covariances of the estimates are set
equal to zero.

nolabel causes the equations to be named eq1, eq2, etc.
The default is to use the first 32 characters of the value labels and/or
the values of Y as the equation labels. Note that some characters
cannot be used in equation names, e.g. the space ( ), the period (.),
the dollar sign ($), and the colon(:), and will be replaced with the
underscore (_) character. Square brackets ([]) and parentheses will be
replaced with curly brackets ({}). The default behavior works well when
the value labels are short and descriptive. It may not work well when
value labels are very long and/or include characters that have to be
changed. If the printout looks unattractive and/or you are getting
strange errors, try changing the value labels of Y or else use the
nolabel option.

mlstart uses an alternative method for computing start
values. This method is slower but sometimes surer. This option shouldn't
be necessary but it can be used if the program is having trouble for
unclear reasons or if you want to confirm that the program is working
correctly.

log displays the iteration log. By default it is
suppressed.

or reports the estimated coefficients transformed to
odds ratios, that is, exp(b) rather than b. Standard errors and
confidence intervals are similarly transformed. This option affects how
results are displayed, not how they are estimated. or may be
specified at estimation or when replaying previously estimated results.
Options rrr, eform, irr and hr produce identical
results (labeled differently) and can also be used. It is up to the user
to decide whether the exp(b) transformation makes sense given the link
function used, e.g. it probably doesn't make sense when using the probit
link.

constraints(clist) specifies the linear
constraints to be applied during estimation. The default is to perform
unconstrained estimation. Constraints are defined with the
constraint command. constraints(1) specifies that the model is to
be constrained according to constraint 1; constraints(1-4)
specifies constraints 1 through 4; constraints(1-4,8) specifies 1
through 4 and 8. Keep in mind that the pl, npl, and
autofit options work by generating across-equation constraints,
which may affect how any additional constraints should be specified.

vce(vcetype) specifies the type of standard
error reported, which includes types that are derived from asymptotic
theory (oim), that are robust to some kinds of misspecification
(robust), that allow for intragroup correlation (cluster clustvar).
vce(bootstrap) and vce(jackknife) are not supported but you can use the
prefix commands for them. The older options robust and
cluster(varname) are also supported.

robust specifies that the Huber/White/sandwich estimator
of variance is to be used in place of the traditional calculation.
robust combined with cluster() allows observations which are
not independent within cluster (although they must be independent
between clusters). If you specify pweights, robust is
implied.

cluster(varname) specifies that the
observations are independent across groups (clusters) but not
necessarily within groups. varname specifies to which group each
observation belongs; e.g., cluster(personid) in data with repeated
observations on individuals. cluster() affects the estimated
standard errors and variance-covariance matrix of the estimators (VCE),
but not the estimated coefficients. cluster() can be used with
pweights to produce estimates for unstratified cluster-sampled
data.

level(#) specifies the confidence level in
percent for the confidence intervals of the coefficients;
see help level.

coeflegend specifies that the legend of the coefficients
and how to specify them in an expression be displayed rather than
displaying the statistics for the coefficients.

nocnsreport causes constraints not to be displayed.

display_options control how results are displayed. These
are generic options in Stata and not all have been tested with gologit2.
In some cases the option may already be specified and cannot be
overridden. See estimation options. A few other
options, along with abbreviations for commands, are listed at
_get_diopts.

maximize_options control the maximization process; see
help maximize. You should never have to specify most of these.
However, the difficult option can sometimes be useful with models
that are running very slowly or not converging at all.

Options for Survey Data Estimation

Stata's svy prefix command is now supported. See help
svy. The old svy option is no longer allowed. However,
rather than use the svy: prefix, it is recommended that you use
the gsvy: prefix, and you are required to do so when
using autofit. The gsvy prefix has the same syntax as
svy but provides customized support for some of the non-standard
features of gologit2, such as the autofit and gamma options.
gsvy and gologit2_svy are synonyms for each other and
either can be used.

NOTE: If you want to use the svy subpop option,
if you don't already have one it is best to compute
a 0/1 selection variable beforehand (e.g. mysample) and
then say something like
gsvy, subpop(mysample). More complicated subpop
statements can sometimes cause
errors with gologit2.

Options for predict

p, the default, calculates predicted probabilities.

If you do not also specify the outcome() option, you
must specify k new variables. For instance, say you fitted your model
by typing "gologit2 insure age male" and that insure takes
on three values. Then you could type "predict p1 p2 p3, p" to
obtain all three predicted probabilities.

If you also specify the outcome() option, then you
specify one new variable. Say that insure took on values 1, 2, and
3. Then typing "predict p1, p outcome(1)" would produce the same
p1 as above, "predict p2, p outcome(2)" the same p2 as
above, etc. If insure took on values 7, 22, and 93, you would
specify outcome(7), outcome(22), and outcome(93).
Alternatively, you could specify the outcomes by referring to the
equation number (outcome(#1), outcome(#2), and
outcome(#3), or, if the variable values are labeled, you can do
something like outcome(low), outcome(medium), and
outcome(high).

If you do not specify outcome(), p (with one new
variable specified), xb, and stdp assume outcome(#1).
You must specify outcome() with the stddp option.
For p, xb, and stdp you can compute predictions for
each of the M outcomes of Y.

xb calculates the linear prediction. You should also
specify the outcome() option. Default is outcome(#1).

outcome() specifies for which outcome the statistic is
to be calculated. equation() is a synonym for outcome(): it
does not matter which you use. outcome() and equation() can
be specified using (1) #1, #2, ..., with #1 meaning
the first category of the dependent variable, #2 the second
category, etc.; (2) values of the dependent variable; or (3) the value
labels (if any) of the dependent variable.

stdp calculates the standard error of the linear
prediction. You should also specify the outcome() option. Default
is outcome(#1).

stddp calculates the standard error of the difference in
two linear predictions. You must specify option outcome() and in
this case you specify the two particular outcomes of interest inside the
parentheses; for example, "predict sed, stddp outcome(1,3)".

Some cautions about using gologit2 (especially autofit) with Stata prefix commands

Be careful when using prefix commands with the autofit option.
These commands often change the sample that is being used which could result
in differing models after autofit. If you have this mad desire to
use bootstrapping or jackknifing or multiple imputation, it may
be safer to specify the model without using autofit. The output from
autofit will contain information on alternative ways to specify the model
by using the pl option.

Keep in mind that many prefix commands do not work when factor
variables are used. Also there are many possible esoteric combinations of
prefix commands and gologit2 options and gologit2 is not
guaranteed to be problem-free with all of them.

Examples

Example 1. Proportional Odds/ Parallel Lines Assumption
Violated. Long and Freese (2003) present data from the 1977/ 1989
General Social Survey. Respondents are asked to evaluate the
following statement: "A working mother can establish just as warm and
secure a relationship with her child as a mother who does not work."
Responses were coded as 1 = Strongly Disagree (1SD), 2 = Disagree
(2D), 3 = Agree (3A), and 4 = Strongly Agree (4SA). We can do a
global test of the proportional odds assumption by estimating a model
in which no variables are constrained to meet the assumption and
contrasting it with a model in which all are so constrained (the
latter is equivalent to the ologit model).

. use https://www3.nd.edu/~rwilliam/statafiles/ordwarm2, clear

. gologit2 warm i.yr89 i.male i.white age ed prst, store(unconstrained)

. gologit2 warm i.yr89 i.male i.white age ed prst, pl store(constrained)

. lrtest constrained unconstrained

The LR chi-square from the above is 49.20. These data fail the global test.

However, we can now use the autofit option to see whether a
partial proportional odds model can fit the data. In a partial proportional odds model,
some variables meet the proportional odds assumption while others do not.

. gologit2 warm i.yr89 i.male i.white age ed prst, autofit

The results show that 4 of the 6 variables (white, age, ed,
prst) meet the parallel lines assumption. Only yr89 and male do not.
This model is less restrictive than a model estimated by ologit
would be (whose assumptions are violated in this case) but much more
parsimonious than a non-ordinal alternative such as mlogit.

Example 2: Alternative parameterization using the gamma
option. Peterson & Harrell (1990) and Lall et al (2002) present an
alternative parameterization of the partial proportional odds model. In
this parameterization, gamma coefficients represent deviations from
proportionality. When the gammas of an explanatory variable do not
significantly differ from 0, the parallel lines assumption for that
variable is met. Using the autofit and gamma options, we can (a)
confirm that Lall came up with the correct partial proportional odds
model, and (b) replicate the results from his Table 5.

. use https://www3.nd.edu/~rwilliam/statafiles/lall.dta, clear

. gologit2 hstatus i.heart i.smoke, gamma autofit

Example 3: Complex survey data estimation. By using the
svy or gsvy prefixes, we can estimate models with complex
survey data that have been svyset. gsvy is required if
autofit is used.

. webuse nhanes2f, clear

. gsvy: gologit2 health i.female i.black age c.age#c.age, autofit

. gsvy, subpop(female): gologit2 health i.black age c.age#c.age, autofit

. svy: gologit2 health i.female i.black age c.age#c.age, pl

. svy, subpop(female): gologit2 health i.black age c.age#c.age, pl

Example 4. The predict command.
In addition to the standard options (xb, stdp, stddp) the predict
command supports the pr option (abbreviated p) for predicted
probabilities; pr is the default option if nothing else is specified.
For example,

. use https://www3.nd.edu/~rwilliam/statafiles/ordwarm2, clear

. quietly gologit2 warm i.yr89 i.male i.white age ed prst, pl(i.yr89 i.male)

. predict p1 p2 p3 p4

. list p1 p2 p3 p4 in 1/10

Example 5. Constrained logistic regression.
Here is an example of how you can impose your own linear constraints on variables.

. use https://www3.nd.edu/~rwilliam/statafiles/ordwarm2, clear

. recode warm (1 2 = 0)(3 4 = 1), gen(agree)

. * Constrain the effects of male and white to be equal

. constraint 1 1.male = 1.white

. gologit2 agree yr89 i.male i.white age ed prst, store(constrained) c(1)

Example 6. Other link functions. By default, and
as its name implies. gologit2 uses the logit link. If you
prefer, however, you can specify probit, complementary log log,
log log, or cauchit links. For example, to estimate a goprobit model,

. use https://www3.nd.edu/~rwilliam/statafiles/ordwarm2, clear

. gologit2 warm i.yr89 i.male i.white age ed prst, link(p)

Example 7. The margins command.

. use https://www3.nd.edu/~rwilliam/statafiles/ordwarm2, clear

. gologit2 warm i.yr89 i.male i.white age ed prst, pl

. margins yr89 male white

. margins yr89 male white, predict(outcome(1))

. margins yr89 male white, predict(outcome(2))

. margins yr89 male white, predict(outcome(3))

. margins yr89 male white, predict(outcome(4))

Example 8. The spost13 commands. Long & Freese's spost13 commands
(download and install spost13_ado) make it much easier to work with ordinal
and multinomial models. Here is one simple example.

. webuse nhanes2f, clear

. gologit2 health i.female i.black c.age, auto(.01)

. quietly mtable, at (black = 0 age = 20 ) rown(20 year old white) dec(4)

. quietly mtable, at (black = 1 age = 20 ) rown(20 year old black) dec(4) below

. quietly mtable, at (black = 0 age = 47 ) rown(47 year old white) dec(4) below

. quietly mtable, at (black = 1 age = 47 ) rown(47 year old black) dec(4) below

. quietly mtable, at (black = 0 age = 74 ) rown(74 year old white) dec(4) below

. mtable, at (black = 1 age = 74 ) rown(74 year old black) dec(4) below

Author

Richard Williams

Notre Dame Department of Sociology

rwilliam@ND.Edu

https://www3.nd.edu/~rwilliam/gologit2/

Acknowledgements

Vincent Kang Fu of the Utah Department of Sociology wrote
gologit 1.0 and graciously allowed Richard Williams to incorporate
parts of its source code and documentation in gologit2.

The documentation for Stata 8.2's mlogit command and the
program mlogit_p were major aids in developing the gologit2
documentation and in adding support for the predict command. Much
of the code is adapted from Maximum Likelihood Estimation with
Stata, Second Edition, by William Gould, Jeffrey Pitblado and
William Sribney.

Sarah Mustillo, Dan Powers, J. Scott Long, Nick Cox, Kit Baum
and Joseph Hilbe provided stimulating and helpful comments. Kerry
Kammire helped with updating the program to work with factor variables
and the margins command. Jeff Pitblado played a critical role in
updating the program to use numerous Stata features, including the
gsvy: prefix.

References

Fu, Vincent. 1998. "Estimating Generalized Ordered Logit
Models." Stata Technical Bulletin 8:160-164.

Lall, R., S.J. Walters, K. Morgan, and MRC CFAS Co-operative
Institute of Public Health. 2002. "A Review of Ordinal Regression
Models Applied on Health-Related Quality of Life Assessments."
Statistical Methods in Medical Research 11:49-67.

Long, J. Scott and Jeremy Freese. 2014. "Regression Models
for Categorical Dependent Variables Using Stata, 3rd Edition." College
Station, Texas: Stata Press.

Norusis, Marija. 2005. "SPSS 13.0 Advanced Statistical
Procedures Companion." Upper Saddle River, New Jersey: Prentice Hall.

Peterson, Bercedis and Frank E. Harrell Jr. 1990. "Partial
Proportional Odds Models for Ordinal Response Variables." Applied
Statistics 39(2):205-217.

Suggested citations if using gologit2 in published work

gologit2 is not an official Stata command. It is a free
contribution to the research community, like a paper. Please cite it
as such. You can email Richard Williams if you do not otherwise have
access to these articles.

Williams, Richard. 2006. "Generalized Ordered Logit/ Partial
Proportional Odds Models for Ordinal Dependent Variables." The Stata
Journal 6(1):58-82. The published article is available for free at
http://www.stata-journal.com/article.html?article=st0097.

Williams, Richard. 2016. 2016. "Understanding and interpreting
generalized ordered logit models." The Journal of Mathematical
Sociology, 40:1, 7-20,
http://www.tandfonline.com/doi/full/10.1080/0022250X.2015.1112384.

Updates to the program that have been made since the 2006 Stata
Journal article are summarized at
https://www3.nd.edu/~rwilliam/gologit2/gologit2.pdf.