```help reffadjust4nlcom
-------------------------------------------------------------------------------

Title

reffadjust4nlcom -- random effects adjustment: regression coefficient
formula to pass to nlcom

Syntax

reffadjust4nlcom depvar indepvars , eqn(string) [options]

options                         Description
-------------------------------------------------------------------------
eqn(string)                   name of the equation the adjusted
coefficients are to be extracted from
mcmcsum                       returned local in format for use with
chains from mcmcsum
sf(numlist)                   scaling factors corresponding to each
coefficient
sublevel(#)                   sublevel of a repeated group variable
-------------------------------------------------------------------------

Description

reffadjust4nlcom is a postestimation command to perform adjustment of
random effects estimates.  It runs with estimates from runmlwin or chains
from runmlwin by mcmcsum (Leckie and Charlton, 2011), xtmixed, xtmelogit,
and xtmepoisson.  It returns the formula for a regression coefficient to
pass to nlcom to generate a delta-method confidence interval.

For example, for an outcome variable Y (depvar) and covariate X1
(indepvar) the formula for the regression coefficient beta_X1 is:

beta_X1 = cov(Y,X1)/var(X1).

The approach is described in more detail in Macdonald-Wallis et al.
(2011, submitted).  Further details are given in reffadjust.

reffadjust4nlcom can return the formulae for upto four covariates and
returns locals for all specified covariates.  The covariates (indepvars)
can be specified in any order.  reffadjustsim can adjust for more
covariates.

See Buis (2011) for a description of how to retrieve random effect
variances and correlations from xt commands.

Note on multivariate response models:  Covariates (indepvars) in runmlwin
estimates from multivariate response models have suffix _#, where # is
the corresponding equation number.  For example, from equation 1 cons
would be referred to as cons_1.

Note on shrinkage estimates:  reffadjust4nlcom uses the estimated random
effect variances and covariances from the model.  It does not use the
shrinkage estimates of these parameters, i.e. the variances and
covariances of the residuals (see chapter 3 of the MLwiN User Manual).

Warning about P-values for these estimates The P-values associated with
these estimates from nlcom may be affected by boundary value issues in
the estimation of the random effect variances and covariances (see
Distribution theory for likelihood ratio tests subsection in [XT]
xtmixed, Gutierrez et al. 2001).

Interpretation of coefficients:  The coefficients estimated by
reffadjust4nlcom represent the mean difference in the random effect
entered as the dependent variable, which is associated with a unit
increase in each of the random effects entered as independent variables,
whilst adjusting for the other random effects included as independent
variables.

Parameters estimated with zero variance:  Sometimes a multilevel model
can be declared as converged but some parameters (especially random
effect variances and covariances) may not have a standard error.  A
warning is issued that resulting confidence intervals may not be valid in
this case.

Options

eqn(string) the name of the equation the coefficients are to be extracted
from.  For example a two level random effects model from runmlwin
will typically return four equations (FP1, FP2, RP1, RP2).

mcmcsum specifies that the returned local is to use variable names of
chains which are returned from MLwiN Bayesian MCMC estimation by
mcmcsum, getchains.  Only allowed with runmlwin estimates.

sf(numlist) a numlist of scaling factors.  If specified each number
corresponds to the respective covariate (indepvar), i.e. the first
number is the scaling factor for the first coefficient and so on.  If
specified the numlist must be the same length as the number of
covariates.  To scale the coefficient by 2 times the dependent
variable (Y), for example, then with one covariate (X) specify sf(2).
To scale the coefficient by 2 times the covariate specify sf(.5)
because the coefficient is by 2/2^2 since a regression coefficient is
given by: cov(X,Y)/var(X).

sublevel(#) the sublevel of a repeated group variable.  For example, in
the following model

. xtmixed f_p || school: z1 z2, nocons cov(id) || school: z3 z4,
nocons cov(un) options

z1 and z2 are at sublevel 1 and z3 and z4 are at sublevel 2 of
the school group variable.
Only valid with xtmixed, xtmelogit, and xtmepoisson.

Examples

---------------------------------------------------------------------------
Examples 1 & 2 assume the path to the MLwiN executable is set in global
MLwiN_path; see runmlwin

Example 1: Two level continuous response model (see page 59 of the MLwiN
User Manual)

. * read in data
. use http://www.bristol.ac.uk/cmm/media/runmlwin/tutorial, clear

. * fit model using MLwiN via runmlwin
. runmlwin normexam cons standlrt, level1(student: cons) level2(school:
cons standlrt) batch

. * report coefficient and delta-method confidence interval
. reffadjust4nlcom cons standlrt, eqn(RP2)
. nlcom `r(beta_standlrt)'

. * compare reporting coefficient as median with 2.5 & 97.5 percentiles
. reffadjustsim cons standlrt, eqn(RP2) seed(12345)

. * compare reporting coefficient as mean & Wald-type confidence interval
. * Warning: mean and Wald-type confidence are inaccurate in this example
. reffadjustsim cons standlrt, eqn(RP2) seed(12345) waldtype

. * to view just the coefficient or string expression for the coefficient
. reffadjust4nlcom cons standlrt, eqn(RP2)
. display `r(beta_standlrt)'
. mata st_macroexpand("`r(beta_standlrt)'")

. * compare with Bayesian posterior distribution
. runmlwin normexam cons standlrt, level1(student: cons) level2(school:
cons standlrt) batch mcmc(on) initsprevious seed(121211)
. mcmcsum, getchains
. reffadjust4nlcom cons standlrt, eqn(RP2) mcmcsum
. gen beta_standlrt = `r(beta_standlrt)'
. mcmcsum beta_standlrt, variables

Example 2: Multivariate response model (see page 214 of the MLwiN User
Manual)

. * read in data
. use http://www.bristol.ac.uk/cmm/media/runmlwin/gcsemv1, clear

. * fit model using MLwiN via runmlwin
. runmlwin (written cons female, eq(1)) (csework cons female, eq(2)),
level1(student: (cons, eq(1)) (cons, eq(2))) level2(school: (cons,
eq(1)) (cons, eq(2))) batch

. * report coefficient and delta-method confidence interval
. reffadjust4nlcom cons_1 cons_2, eqn(RP2)
. nlcom `r(beta_cons_2)'

. * compare reporting coefficient as median with 2.5 and 97.5 percentiles
. reffadjustsim cons_1 cons_2, eqn(RP2) seed(12345)

. * compare reporting coefficient as mean with Wald-type confidence
interval
. reffadjustsim cons_1 cons_2, eqn(RP2) seed(12345) waldtype

. * to view just the coefficient or string expression for the coefficient
. reffadjust4nlcom cons_1 cons_2, eqn(RP2)
. display `r(beta_cons_2)'
. mata st_macroexpand("`r(beta_cons_2)'")

. * compare with Bayesian posterior distribution
. runmlwin (written cons female, eq(1)) (csework cons female, eq(2)),
level1(student: (cons, eq(1)) (cons, eq(2))) level2(school: (cons,
eq(1)) (cons, eq(2))) batch mcmc(on) initsprevious seed(121211)
. mcmcsum, getchains
. reffadjust4nlcom cons_1 cons_2, eqn(RP2) mcmcsum
. gen beta_cons_2 = `r(beta_cons_2)'
. mcmcsum beta_cons_2, variables

Example 3: based on xtmixed helpfile
. webuse nlswork, clear
. xtmixed ln_w grade age c.age#c.age ttl_exp tenure c.tenure#c.tenure ||
idcode: tenure, cov(uns) var
. reffadjust4nlcom _cons tenure, eqn(idcode)
. nlcom `r(beta_tenure)'

Example 4: based on xtmelogit helpfile
. webuse bangladesh, clear
. xtmelogit c_use urban age child* || district: urban, cov(uns) var
. reffadjust4nlcom _cons urban, eqn(district)
. nlcom `r(beta_urban)'

Example 5: based on xtmepoisson helpfile
. webuse epilepsy, clear
. xtmepoisson seizures treat lbas lbas_trt lage visit || subject: visit,
cov(uns) var intpoints(9)
. reffadjust4nlcom _cons visit, eqn(subject)
. nlcom `r(beta_visit)'

Example 6: repeated group variable
. webuse nlswork, clear
. xtmixed ln_w grade age || idcode: tenure union, cov(uns) || idcode:
race, cov(uns) var
. reffadjust4nlcom tenure union, eqn(idcode) sub(1)
. nlcom `r(beta_union)'
. reffadjust4nlcom race _cons, eqn(idcode) sub(2)
. nlcom `r(beta__cons)'
---------------------------------------------------------------------------

Saved results

reffadjust4nlcom saves the following in r():

Macros
r(beta_indepvar)    Formula for beta_indepvar

References

Buis ML. 2011. Stata tip 97: Getting at rho's and sigma's. The Stata
Journal. 11(2) 315-317.

Gutierrez RG, Carter S, Drukker DM. 2001. sg160: On boundary-value
likelihood ratio tests. Stata Technical Bulletin. 60. 15-18.

Leckie G, Charlton C. 2011. runmlwin: Stata module for fitting multilevel
models in the MLwiN software package. Centre for Multilevel
Modelling, University of Bristol, UK.
http://www.bristol.ac.uk/cmm/software/runmlwin/

Macdonald-Wallis C, Lawlor DA, Palmer TM, Tilling K. 2011 (submitted).
Multivariate multilevel spline models for parallel growth processes:
application to weight and mean arterial pressure in pregnancy.
Statistics in Medicine.

Rasbash J, Charlton C, Browne WJ, Healy M, Cameron B. 2009. MLwiN version
2.1. Centre for Multilevel Modelling, University of Bristol, UK.
http://www.bristol.ac.uk/cmm/software/mlwin.

Rasbash J, Steele F, Browne WJ, Goldstein H. 2009. A user's guide to
MLwiN, v2.10. Centre for Multilevel Modelling, University of Bristol,
UK.

Authors

Tom Palmer, MRC Centre for Causal Analyses in Translational Epidemiology,
School of Social and Community Medicine, University of Bristol, UK.
tom.palmer@bristol.ac.uk.

Corrie Macdonald-Wallis, MRC Centre for Causal Analyses in Translational
Epidemiology, School of Social and Community Medicine, University of
Bristol, UK.  c.macdonald-wallis@bristol.ac.uk.

Also see

Help:  reffadjust, reffadjustsim, runmlwin (if installed), mcmcsum (if
installed), nlcom, xtmixed, xtmelogit, xtmepoisson
```