simul_these/Modules/ado/plus/g/gllapred.hlp

.-
help for ^gllapred^
.-

Predict command for gllamm
---------------------------

^gllapred^ varname [^if^ exp] [^in^ range] [,^u^ ^fac^ ^p^ ^xb^ 
           ^ustd^ ^co^oksd ^li^npred ^mu^ ^ma^rginal ^us(^varname^)^ 
           ^out^come^(^#^)^ ^ab^ove^(^#^,^...^,^#^)^ 
           ^pe^arson ^d^eviance ^a^nscombe  
           ^s^ ^ll^ ^fsample^ ^nooff^set 
           ^adapt^ ^adoonly^ ^fr^om^(^matrix^)^ ]

where only one of ^xb^ ^u^ ^fac^ ^p^ ^li^npred ^mu^ 
                  ^pe^arson ^d^eviance ^a^nscombe ^s^ ^ll^ 
may be specified at a time.


Description
-----------

^gllapred^ is a prediction command for @gllamm@. It computes 

-- Posterior means (empirical Bayes predictions) and standard 
deviations of the latent variables or random effects for models 
estimated using gllamm (see ^u^ and ^fac^ options).

-- Posterior probabilities for two level models with discrete
latent variables or random effects (see ^p^ option).

-- The fixed part of the linear predictor (^xb^ option) or the 
entire linear predictor (^linpred^ option) with empirical Bayes
estimates substituted for the latent variables or random effects.

-- The expectation of the response (see ^mu^ option). By default,
the expectation is with respect to the posterior distribution
of the latent variables, but the ^marginal^ option gives the
expectation with respect to the prior distribution. 
The ^us()^ option can be used to get the conditional expectation
for specified values of the latent variables.

--- Pearson, Deviance or Anscombe residuals. By default,
the posterior expectation, but the ^us^ option gives the
residuals for specified values of the latent variables.

-- The level 1 standard deviation (see ^s^ option).

-- Log-likelihood contributions of the highest level clusters
(see ^ll^ option).

In some cases the log-likelihood is also returned.
By default prediction is restricted to the estimation sample.
In this case (and if the ^if^ and ^in^ options are not specified),
the log-likelihood returned by gllapred should be the same
as that previously returned by gllamm.



Options
--------

^u^ the posterior means and standard deviation of the latent 
    variables or random effects are returned in "varname"m1, 
    "varname"m2, etc., and "varname"s1, "varname"s2, etc., 
    respectively, where the order of the latent variables is 
    the same as in the call to gllamm (in the order of the 
    equations in the eqs() option). In the case of continuos
    latent variables, the number of quadrature points used 
    is also the same as in the previous call to gllamm. If 
    the gllamm model includes equations for the latent variables 
    (geqs and/or bmatrix), the posterior means and standard
    deviations of the disturbances are returned.

^corr^ the posterior correlations of the random effects
    or latent variables are returned in "varname"c21, etc.
    This option only works together with the ^u^ option. If
    the model includes equations for the latent variables,
    posterior correlations of the disturbances are calculated.   

^fac^ If the gllamm model includes equations for the latent
    variables (^geqs()^ and/or ^bmatrix()^), ^fac^ causes
    predictions of the latent variables (e.g. factors) to be 
    returned in "varname"m1, "varname"m2, etc. instead of the 
    disturbances. In other words, predictions of the latent 
    variables on the left-hand side of the equations are returned.

^p^ can only be used for two-level models estimated using the 
    ip(f) option. gllapred returns the posterior probabilities 
    in "varname"1, "varname"2, etc., giving the probabilities
    of classes 1,2, etc. gllapred also prints out the (prior) 
    probability and location matrices to help interpret the 
    posterior probabilities.

^xb^ the linear predictor for the fixed effects is returned. This
     includes the offset (if there is one in the gllamm model)
     unless the ^nooffset^ option is specified.

^ustd^ standardized posterior mean - approximate sampling
    standard deviation is used, sqrt(prior var. - posterior var.)

^cooksd^ Cook's distances for the top-level units.

^linpred^ returns the linear predictor including both the fixed
   and random parts where posterior means are substituted 
   for the latent variables or random effects in the random 
   part. The offset is included (if there is one in the 
   gllamm model) unless the ^nooffset^ option is specified.

^mu^ returns the expecation of the response, for example
   the predicted probability in the case of dichotomous 
   responses. By default, the expectation is with respect
   to the posterior distribution of the latent variables, 
   but see ^marginal^ and ^us()^ options. The offset is included 
   (if there is one in the gllamm model) unless the 
   ^nooffset^ option is specified.

^marginal^ together with the ^mu^ option gives the
   expectation of the response with respect to the prior
   distribution of the latent variables. This is useful
   for looking at the 'marginal' or population average
   effects of covariates.

^us(^varname)^ can be used to specify values for the latent
   variables to calculate conditional quantities, such as
   the conditional mean of the responses (^mu^ option) 
   given the values of the latent variables. Here varname 
   specifies the stub-name (prefex) for the variables and 
   ^gllapred^ will look for "varname"1 "varname"2, etc.

^outcome(^#^)^ specifies the outcome for which the predicted
   probability should be returned (^mu^ option) if there
   is a nominal response. This option is not necessary if the 
   ^expanded()^ option was used in ^gllamm^ since in this 
   case predicted probabilities are returned for all outcomes.

^above(^#^,^...^,^#^)^ specifies the events for which the 
   predicted probabilities should be returned (^mu^ option)
   if there are ordinal responses. The probability of
   a value higher than that specified is returned for each
   ordinal response. A single number can be given for all
   ordinal responses.

^pearson^ returns Pearson residuals. By default, the posterior
   expectation with respect to the latent variables is 
   returned. The ^us()^ option can be used to obtain the
   conditional residual when certain values are substituted 
   for the latent variables.

^deviance^ returns deviance residuals. By default, the posterior
   expectation with respect to the latent variables is 
   returned. The ^us()^ option can be used to obtain the
   conditional residual when certain values are substituted 
   for the latent variables.

^anscombe^ returns Anscombe residuals. By default, the posterior
   expectation with respect to the latent variables is 
   returned. The ^us()^ option can be used to obtain the
   conditional residual when certain values are substituted 
   for the latent variables.

^s^ returns the scale or standard deviation. This is useful 
    if the ^s()^ option was used in gllamm to specify level 1 
    heteroscedasticity.

^ll^ returns the log-likelihood contributions of the highest
   level (level L) units. 
 
^adapt^ if the gllamm command did not use the adapt option, 
   gllapred will use ordinary quadrature for computing the
   posterior means and standard deviations unless the adapt
   option is used in the gllapred command.

^fsample^ causes gllapred to return predictions for the
   full sample (except observations exluded due to the
   if and in options), not just the estimation sample. 
   The returned log-likelihood may be missing since
   gllapred will not exclude observations with missing
   values on any of the variables used in the likelihood
   calculation. It is up to the user to exclude these
   observations using if or in.

^nooffset^ can be used together with the ^xb^, ^linpred^ or
   ^mu^ options to exclude the offset from the prediction.
   It will only make a difference if the offset option 
   was used in gllamm.

^adoonly^ causes all gllamm to use only ado-code. This option
   is not necessary if gllamm was run with the adoonly option.

^from(^matrix^)^ specifies a matrix of parameters for which 
   the predictions should be made. The column and equation
   names will be ignored. Without this option, the parameter
   estimates from the last gllamm model will be used.

Examples
--------

Estimate parameters of a three level logistic regression model:

    . ^gllamm resp x, i(id school) adapt trace family(binom)^
    

Predict random intercepts using empirical Bayes:

    . ^gllapred int, u^  


Predict marginal probability that resp=1 (with respect to random effects):

    . ^gllapred prob, mu marginal^


Predict conditional probability that resp==1 if random intercepts are 0:

    . ^gen z1 = 0^
    . ^gen z2 = 0^
    . ^gllapred prob, us(z)^


Predict posterior mean of Pearson residual

    . ^gllapred res, pearson^

Predict Pearson residual when random effects are equal to their posterior 
means (note that ^gllapred int, u^ above produced empirical Bayes 
predictions in intm1 intm2): 

    . ^gllapred res, pearson us(intm)^


Author
------
Sophia Rabe-Hesketh (sophiarh@@berkeley.edu)
as part of joint work with Andrew Pickles and Anders Skrondal.


Web-page
--------
http://www.gllamm.org


References
----------
Rabe-Hesketh, S., Skrondal, A. and Pickles, A. (2004). GLLAMM Manual. 
U.C. Berkeley Division of Biostatistics Working Paper Series. 
Working Paper 160.


Also see
--------
On-line:  help for @gllamm@, @gllasim@