{smcl}
{* Last revised September 05, 2006}{...}
{hline}
help for {hi:regoprob}
{hline}

{title:Random Effects Generalized Ordered Probit Estimation}

{p 8 15 2}
	{cmdab:regoprob} {it:depvar} [{it:indepvars}]
	[{cmd:if} {it:exp}] [{cmd:in} {it:range}]
	[{cmd:,}
	{cmdab:i:(}{it:varname}{cmd:)}
	{cmdab:q:uadrat(}{it:#}{cmd:)}
	{cmdab:p:l}
	{cmdab:p:l(}{it:varlist}{cmd:)}
	{cmdab:np:l}
	{cmdab:np:l(}{it:varlist}{cmd:)}
	{cmdab:c:onstraints:(}{it:clist}{cmd:)}
	{cmdab:l:evel:(}{it:#}{cmd:)}
	{it:maximize_options} ]
{p_end}

{p 4 4 2}
{cmd:regoprob} shares the features of all estimation commands; see help
{help est}. {cmd:regoprob} typed without arguments redisplays previous results.
{p_end}

{p 4 4 2}
The syntax of {help predict} following {cmd:regoprob} is
{p_end}

{p 8 16 2}
{cmd:predict} [{it:type}] {it:newvarname}({it:s})
        [{cmd:if} {it:exp}] [{cmd:in} {it:range}]
	[{cmd:,} {it:statistic} {cmdab:o:utcome:(}{it:outcome}{cmd:)} ]
{p_end}

{p 4 4 2}
where {it:statistic} is
{p_end}

{p 8 21 2}
{cmd:p}{space 8}probability marginal on the individual effect
(specify one new variable and {cmd:outcome()} option, or specify k new
variables, k = # of outcomes); the default
{p_end}
{p 8 21 2}
{cmd:xb}{space 7}linear prediction xb ({cmd:outcome()} option
required)
{p_end}
{p 8 21 2}
{cmd:stdp}{space 5}S.E. of linear prediction ({cmd:outcome()}
option required)
{p_end}
{p 8 21 2}
{cmd:stddp}{space 4}S.E. of difference in linear predictions
({cmd:outcome()} option is {cmd:outcome(}{it:outcome1}{cmd:,}{it:outcome2}{cmd:)})
{p_end}

{p 4 4 2}
Note that you specify one new variable with {cmd:xb}, {cmd:stdp}, and
{cmd:stddp} and specify either one or k new variables with {cmd:p}.
{p_end}

{p 4 4 2}
These statistics are available both in and out of sample; type
"{cmd:predict} {it:...} {cmd:if e(sample)} {it:...}" if wanted only for the
estimation sample.
{p_end}


{title:Description}

{p 4 4 2}
{cmd:regoprob} is a user-written program that estimates panel data generalized
ordered probit models with random effects. The actual values taken on by the
dependent variable are irrelevant except that larger values are assumed to
correspond to "higher" outcomes. The generalized model relaxes the
{it:parallel regression} assumption of standard ordered probit models;
see help {help oprobit} and its random effects counterpart {help reoprob}.
{cmd:regoprob} supports linear constraints and allows the user to partially
relax the parallel regression assumption by specifying variables in {cmd:npl()}
or {cmd:pl()}. The likelihood contribution for each unit is approximated using
Gauss-Hermite quadrature. {cmd:regoprob} requires installation of the
{cmd:goprobit} and the {cmd:ghquadm} commands.
{p_end}

{p 4 4 2}
{cmd:regoprob} is a modified version of {cmd:goprobit}. {cmd:regoprob} was
written for Stata 8 and many of the references in this help file are for
Stata 8 manuals and commands.
{p_end}


{title:Options}

{p 4 8 2}
{cmd:i()} specifies the variable corresponding to an independent unit
(e.g., a subject id).  {cmd:i(}{it:varname}{cmd:)} is not optional.
{p_end}

{p 4 8 2}
{cmd:quadrat()} specifies the number of points to use for the Gauss-Hermite
quadrature. It is optional, and the default is 12. Increasing this value
improves accuracy, but also increases computation time.
{p_end}

{p 4 8 2}
{cmd:pl}, {cmd:npl}, {cmd:npl()}, {cmd:pl()} provide alternative means for
imposing or relaxing the parallel regression assumption. Only one may be
specified at a time.
{p_end}

{p 8 12 2}
{cmd:pl} specified without parameters constrains all independent
variables to meet the parallel regression assumption.  It will produce
results that are equivalent to {cmd:oprobit}.
{p_end}
{p 8 12 2}
{cmd:npl} specified without parameters relaxes the parallel
regression assumption for all explanatory variables. This is the default
option.
{p_end}

{p 8 12 2}
{cmd:pl(}{it:varlist}{cmd:)} constrains the specified explanatory
variables to meet the parallel regression assumption. All other variables
do not need to meet the assumption. The variables specified must be a subset
of the explanatory variables.
{p_end}

{p 8 12 2}
{cmd:npl(}{it:varlist}{cmd:)} frees the specified explanatory
variables from meeting the parallel regression assumption. All other
explanatory variables are constrained to meet the assumption. The variables
specified must be a subset of the explanatory variables.
{p_end}

{p 4 8 2}
{cmd:constraints(}{it:clist}{cmd:)} specifies the linear
constraints to be applied during estimation.  The default is to perform
unconstrained estimation.  Constraints are defined with the
{help constraint} command. {cmd:constraints(1)} specifies that the
model is to be constrained according to constraint 1;
{cmd:constraints(1-4)} specifies constraints 1 through 4;
{cmd:constraints(1-4,8)} specifies 1 through 4 and 8.  Keep in mind that the
{cmd:pl}, and {cmd:npl} options work by generating across-equation
constraints, which may affect how any additional constraints should be
specified.  When using the {cmd: constraint} command, refer to equations
by their equation #, e.g. #1, #2, etc.
{p_end}

{p 4 8 2}
{cmd:level(}{it:#}{cmd:)} specifies the confidence level in percent for
the confidence intervals of the coefficients; see help {help level}.
{p_end}


{p 4 8 2}
{it:maximize_options} control the maximization process; see
help {help maximize}. You should never have to specify them.
{p_end}


{title:Options for {help predict}}

{p 4 8 2}
{cmd:p}, the default, calculates predicted probabilities {it: marginal} on the
individual effect.
{p_end}

{p 8 8 2}
If you do not specify the {cmd:outcome()} option, you must specify k new
variables. For instance, say you fitted your model by typing
"{cmd:regoprob happy income health, i(persnr)}" and that {cmd:happy} takes on three values.
Then you could type "{cmd:predict p1 p2 p3, p}" to obtain all three predicted
probabilities.
{p_end}

{p 8 8 2}
If you also specify the {cmd:outcome()} option, then you specify one new
variable. Say that {hi:happy} took on values 1, 2, and 3. Then typing
"{cmd:predict p1, p outcome(1)}" would produce the same {hi:p1} as above,
"{cmd:predict p2, p outcome(2)}" the same {hi:p2} as above, etc. If {hi:happy}
took on values 7, 22, and 93, you would specify {cmd:outcome(7)},
{cmd:outcome(22)}, and {cmd:outcome(93)}. Alternatively, you could specify the
outcomes by referring to the equation number ({cmd:outcome(#1)},
{cmd:outcome(#2)}, and {cmd:outcome(#3)}.
{p_end}

{p 4 8 2}
{cmd:xb} calculates the linear prediction. You must also specify the
{cmd:outcome()} option.
{p_end}

{p 4 8 2}
{cmd:stdp} calculates the standard error of the linear prediction. You must
specify option {cmd:outcome()}.
{p_end}

{p 4 8 2}
{cmd:stddp} calculates the standard error of the difference in two linear
predictions. You must specify option {cmd:outcome()}, in this case with two
particular outcomes of interest inside the parentheses; for example,
"{cmd:predict sed, stdp outcome(1,3)}".
{p_end}

{p 4 8 2}
{cmd:outcome()} specifies for which outcome the statistic is to be calculated.
{cmd:equation()} is a synonym for {cmd:outcome()}: it does not matter which one
you use. {cmd:outcome()} and {cmd:equation()} can be specified using (1)
{cmd:#1}, {cmd:#2}, ..., with {cmd:#1} meaning the first category of the
dependent variable, {cmd:#2} the second category, etc.; or (2) values of the
dependent variable.
{p_end}


{title:Remarks and Methods}

{p 4 4 2}
Standard ordered response models such as {cmd:oprobit} or {cmd:reoprob}
impose what is called the {it:parallel regression assumption}. By default,
{cmd:regoprob} relaxes this assumption and allows the effects of the
explanatory variables to vary with the point at which the categories of
the dependent variable are dichotomized. However, if the {cmd:pl} option is
specified, {cmd:regoprob} estimates the standard random effects ordered
probit model, e.g., the commands {cmd:reoprob y x1 x2 x3, i(id)} and
{cmd:regoprob y x1 x2 x3, i(id) pl} will produce equivalent results.
{p_end}

{p 4 4 2}
More formally, suppose we have an ordinal dependent variable Y_it
which takes on the values 1, 2, ..., J, where i denotes cross-sectional
units and t the time dimension of the (panel) dataset (see help {help xt}).
The random effects generalized ordered probit model estimates a set of
coefficients (including one for the constant) for each of the J - 1 points
at which the dependent variable can be dichotomized. The probabilities that
Y_it will take on each of the values 1, ..., J conditional on the individual
effect u_i is equal to
{p_end}

	P( Y_it = 1 | u_i ) = F( -X_it B_1 - u_i )

	P( Y_it = j | u_i ) = F( -X_it B_j - u_i ) - F( -X_it B_(j-1) - u_i )
		j = 2, ..., J - 1

	P( Y_it = J | u_i ) = 1 - F( -X_it B_(J-1) - u_i )

{p 4 4 2}
The random effects generalized ordered probit model uses the standard normal
distribution as the cumulative distribution for F(.), although other distributions
may also be used. The individual effects are assumed to be normally distributed
with zero mean and variance sigma^2 which is parameterized as rho = sigma^2/(1+sigma^2).
{p_end}

{p 4 4 2}
The standard random effects ordered probit (estimated by {cmd:reoprob} and
{cmd:regoprob} with the {cmd:pl} option) restricts the B_j coefficients to
be the same for every dividing point j = 1, ..., J-1. The random effects
generalized ordered probit model (estimated in {cmd:regoprob} via the
{cmd:npl()} and {cmd:pl()} options) restricts some B_j coefficients to be
the same for every dividing point while others are free to vary.
{p_end}

{p 4 4 2}
Note that the generalized ordered probit model imposes explicit restrictions
on parameters. Since probabilities are by definition constrained to be in the
range [0,1], valid combinations must satisfy the following inequalities:
{p_end}

	X_it B_1 >= X_it B_2 >= X_it B_3 ... >= X_it B_J-1

{p 4 4 2}
The current version of {cmd:regoprob} does not impose these restrictions during
the maximization process. After fitting the model, the user should verify the
validity of the model by calculating predicted probabilities.
See help {help goprobit}, help {help gologit2} and
{browse "http://www.nd.edu/~rwilliam/gologit2/"} for further discussion
on this topic.
{p_end}

{p 4 4 2}
The likelihood contribution for each cross-sectional unit in the above model
is approximated using a Gauss-Hermite quadrature. See Butler and Moffitt (1982)
for details about using Gauss-Hermite quadrature to approximate such integrals.
{p_end}

{p 4 4 2}
{cmd:regoprob} uses the d1 method (analytic first derviatives) of
Stata's {cmd:ml} commands.
{p_end}


{title:Examples}

{p 8 12 2}
{cmd:. regoprob happy linc unempl health if male == 1, i(id)}{p_end}

{p 8 12 2}
{cmd:. regoprob happy linc unempl health if male == 1, i(id) npl(unempl)}{p_end}

{p 8 12 2}
{cmd:. regoprob, level(99)}
{p_end}

{p 8 12 2}
{cmd:. predict xb1, xb outcome(#1)}
{p_end}



{title:Author}

{p 5 5}
Stefan Boes{break}
Socioeconomic Institute{break}
Statistics and Empirical Economics Research Group{break}
University of Zurich{break}
boes@sts.unizh.ch{break}
{browse "http://www.unizh.ch/sts/"}
{p_end}



{title:Acknowledgements}

{p 5 5}
Guillaume R. Frechette of the New York University wrote {cmd:reoprob} and kindly
gave me permission to use parts of his code for {cmd:regoprob}. See {help reoprob}
for a description of the {cmd:reoprob} command.
{p_end}

{p 5 5}
Richard Williams of the Notre Dame Department of Sociology wrote {cmd:gologit2}
and kindly gave me permission to use parts of his code for programming {cmd:goprobit}.
For a more detailed description of {cmd:gologit2} and its features, see the reference
below or {help gologit2}.
{p_end}

{p 5 5}
{cmd:reoprob} combines the features of {cmd:goprobit} and {cmd:reoprob}, i.e., estimates
panel data generalized ordered probit models.
{p_end}



{title:References}

{p 5 5}
Boes, S. and R. Winkelmann (2006) "The Effect of Income on Positive and Negative
Subjective Well-Being." unpublished manuscript.
{p_end}

{p 5 5}
Butler, J.S. and  R. Moffitt (1982) "A computationally efficient quadrature
procedure for the one-factor multinomial probit model." Econometrica 50: 761-764.
{p_end}

{p 5 5}
Williams, Richard (2006) "Generalized Ordered Logit/ Partial Proportional Odds
Models for Ordinal Dependent Variables." The Stata Journal 6(1): 58-82. A pre-publication
version is available at {browse "http://www.nd.edu/~rwilliam/gologit2/gologit2.pdf"}.
{p_end}


{title:Also see}

{p 4 13 2}
Manual:
{hi:[U] 23 Estimation and post-estimation commands},{break}
{hi:[U] 29 Overview of Stata estimation commands}
{p_end}

{p 4 13 2} Online:  help for {help estcom}, {help postest}, {help constraint},
{help oprobit}, {help goprobit}, {help ologit}, {help gologit}, {help gologit2},
{help reoprob}
{p_end}