simul_confusion/Modules/ado/plus/g/gllasim.hlp

.-
help for ^gllasim^
.-

Simulate command for gllamm
---------------------------

^gllasim^ varname [^if^ exp] [^in^ range] [, ^y^ ^u^ ^fac^ ^li^npred
          ^mu^ ^out^come^(^#^)^ ^ab^ove^(^#^,^...^,^#^)^ 
          ^adapt^ ^fsample^ ^nooff^set ^adoonly^ ^fr^om^(^matrix^)^ 
          ^us(^varname^)^ ]

where only one of ^u^ ^fac^ ^li^npred ^mu^ may be used at a time.
^y^ can be specified in addition to one of the above.


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

^gllasim^ is a post-estimation command for @gllamm@. It simulates
the responses from to the model just estimated. 

By default responses are simulated for the estimation sample.
Use ^fsample^ to simulate responses for the full sample.

If the data were collapsed and the ^weight()^ option used in 
^gllamm^, it does not make sense to simulate responses unless
the data are first expanded. This is because each record
in the collapsed dataset represents several units who happened 
to have the same response in the data and it would not
make sense to simulate the same response for all these units. 


Options
--------

^y^ the simulated resonses are returned in "varname". This
    option is only necessary if ^u^, ^fac^, ^linpred^ or ^mu^ 
    are also specified.

^u^ the simulated latent variables or random effects are 
    returned in "varname"p1, "varname"p2, etc., 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). If the gllamm model includes equations for the 
    latent variables (geqs and/or bmatrix), the simulated
    disturbances are returned.

^fac^ If the gllamm model includes equations for the latent
    variables (^geqs()^ and/or ^bmatrix()^ options in ^gllamm^), 
    ^fac^ causes the simulated latent variables (e.g. factors)
    to be returned in "varname"p1, "varname"p2, etc. instead of 
    the disturbances, that is, the latent variables on the 
    left-hand side of the structural model. 

^linpred^ returns the linear predictor including the fixed
   and simulated random parts in "varname"p. The offset 
   is included (if there is one in the gllamm model) 
   unless the nooffset option is specified.

^mu^ returns the expected value of the response conditional
   on the simulated values for the latent variables, e.g.
   a probability if the responses are dichotmous.

^outcome(^#^)^ specifies the outcome for which the predicted
   probability should be returned (^mu^ option) if there
   is a nominal response and the ^expanded()^ option has not 
   been used in ^gllamm^ (with the ^expanded()^ option, 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.

^nooffset^ can be used together with the ^linpred^ and ^mu^
   options to exclude the offset from the simulated value.
   It will only make a difference if the ^offset()^ option 
   was used in gllamm.

^fsample^ causes gllasim to simulate values for the
   full sample (except observations exluded due to the
   if and in options), not just the estimation sample. 

^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.

^us(^varname^)^ specifies that, instead of simulating the 
   latent variables, gllasim should use the variables in 
   "varname"1, "varname"2, etc.

Examples
--------

Estimate parameters of a three level logistic regression model:

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


Simulate the random intercepts

    . ^gllasim int, u^


Simulate the responses

    . ^gllasim y^


Simulate responses when the latent variables are equal to the values
previously simulated (note that ^gllasim int, u^ above stored the 
random intercepts in intp1 and intp2):

     . ^gllasim y1, us(intp)^


Simulate predicted probabilities, i.e. predicted probabilities for 
simulated values of the latent variables:

     . ^gllasim prob, mu^


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@, @gllapred@