help reffadjustsim-------------------------------------------------------------------------------

Title

reffadjustsim-- random effects adjustment: simulating from the distribution of random effect variances and covariances

reffadjustsimdepvarindepvars,eqn(string)[options]

optionsDescription -------------------------------------------------------------------------eqn(string)name of the equation the adjusted coefficients are to be extracted fromcentileopts(string)options passed tocentilelevel(#)set confidence level; default islevel(95)mcmcsumuse chains frommcmcsumn(#)# of observations to simulate; default is 10,000postpost estimation resultsreplacereplace beta_indepvar if variable exists in datasetsaving(filename[,replace])save simulated observations tofilenamesf(numlist)scaling factors corresponding to each coefficientseed(#)seed for random-number generatorstatadrawnormuse Stata'sdrawnormfor Wald type CIssublevel(#)sublevel of a repeated group variablewaldtypereport means & Wald-type confidence intervals -------------------------------------------------------------------------

reffadjustsimis a postestimation command to perform adjustment of random effects estimates. It runs with estimates fromrunmlwinor chains fromrunmlwinbymcmcsum(Leckie and Charlton, 2011),xtmixed,xtmelogit, andxtmepoisson.

reffadjustsimgenerates the specified number of observations of the variances and covariances of the random effects from the corresponding multivariate normal distribution. Alternatively, values are used from the returned chains from Bayesian estimation in MLwiN bymcmcsum,getchains. For each observation the adjusted coefficient/s are estimated as described by Fisher (1925, chapter 5, section 29). The approach is described in more detail in Macdonald-Wallis et al. (2011, submitted). Further details are given inreffadjust. The covariates (indepvars) can be specified in any order.An alternative approach is to use the accompanying

reffadjust4nlcomcommand to generate the expression for the adjusted coefficient, and pass that tonlcomto estimate a delta-method confidence interval.See Buis (2011) for a description of how to retrieve random effect variance and correlations from

xtcommands.

Note on multivariate response models:Covariates (indepvars) inrunmlwinestimates from multivariate response models have suffix_#, where # is the corresponding equation number. For example, from equation 1conswould be referred to ascons_1.

Note on shrinkage estimates:reffadjustsimuses 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 waldtype option:By defaultreffadjustsimreports coefficients as medians with 2.5 and 97.5 percentiles. Coefficients can be reported as means with Wald-type confidence intervals with thewaldtypeoption. Means and Wald-type confidence intervals may not be accurate. It is always advised to compare results with the default output and if possible also with the delta-method confidence interval viareffadjust4nlcomandnlcom. In general, P-values associated with these estimates 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 byreffadjustsimrepresent 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.

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

centileopts(string)options passed tocentile, note you may not specify thecentile(#)option here. The reported percentiles can be changed through thelevel(#)option.

level(#); see[R] estimation options.

mcmcsumcalculates centiles from the Bayesian posterior distribution of the coefficients using chains imported by:mcmcsum, getchains. Note yourrunmlwinmodel must have been fitted by MCMC. Options:seed,n,statadrawnorm,waldtype(andpost) are not required/allowed withmcmcsum. Only allowed withrunmlwinestimates.

n(#)specifies the number of observations to be simulated. The default is 10,000 and is not allowed to be less than 10. Not allowed withmcmcsum, wherenis taken as the number of observations in the dataset imported bymcmcsum, getchains.

postcausesreffadjustsimto behave like a Stata estimation (eclass) command. May only be specified withwaldtype. Whenpostis specified,reffadjustsimwill post the vector of adjusted estimates and its estimated variance-covariance matrix toe(). Thus you could, afterposting, treat the estimation results in the same way as you would treat results from other Stata estimation commands. For example, after posting, you could redisplay the results by typingreffadjustsimwithout any arguments, or usetestto perform simultaneous tests of hypotheses on linear combinations of the estimates.Specifying

postclears out the previous estimation results, which can be recovered only by refitting the original model or by storing the estimation results before runningreffadjustsimand then restoring them; see[R] estimates store.

replaceoverwrites variables namedbeta_indepvarif they exist in the dataset. Only valid withmcmcsum.

saving(filename[,replace])saves the simulated realisations of the random effect variances and covariances tofilename, optionally replacingfilenameif it exists.

seed(#)specifies the initial value of the random-number seed. The default is the current random-number seed. Specifyingseed(#)is the same as typingset seed#before issuing the command; seeset_seed. Not allowed withmcmcsum.

sf(numlist)a numlist of scaling factors. If specified each number corresponds to the respective covariate (indepvar), i.e. first number is the scaling factor for the first coefficient and so on. If specified thenumlistmust 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 in this case you scale by 2/2^2 since a regression coefficient is given by: cov(X,Y)/var(X).

statadrawnormuse Stata'sdrawnormto simulate the adjusted coefficients. For speed by defaultreffadjustsimuses its own Mata implementation; seedrawnorm. Not allowed withmcmcsum.

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

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

z1andz2are at sublevel 1 andz3andz4are at sublevel 2 of theschoolgroup variable. Only valid withxtmixed,xtmelogit, andxtmepoisson.

waldtypereport coefficients as means with Wald-type confidence intervals. By defaultreffadjustsimreports coefficients as medians and centiles of the simulated coefficients. This option can produce inaccurate results, as per the warning above please compare with the default output. Not allowed withmcmcsum.

--------------------------------------------------------------------------- Examples 1 & 2 assume the path to the MLwiN executable is set in

globalMLwiN_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 as median with 2.5 & 97.5 percentiles.reffadjustsim cons standlrt, eqn(RP2) seed(12345)

. * report 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

. * compare with delta-method confidence interval (first refit model).runmlwin normexam cons standlrt, level1(student: cons) level2(school:cons standlrt) batch.reffadjust4nlcom cons standlrt, eqn(RP2).nlcom `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.reffadjustsim cons standlrt, eqn(RP2) mcmcsum

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 as median with 2.5 and 97.5 percentiles.reffadjustsim cons_1 cons_2, eqn(RP2) seed(12345). * report coefficient as mean with Wald-type confidence interval.reffadjustsim cons_1 cons_2, eqn(RP2) seed(12345) waldtype

. * compare with delta-method confidence interval (first refit model).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.reffadjust4nlcom cons_1 cons_2, eqn(RP2).nlcom `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.reffadjustsim cons_1 cons_2, eqn(RP2) mcmcsum

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.reffadjustsim _cons tenure, eqn(idcode) seed(12345)

Example 4: based on xtmelogit helpfile.webuse bangladesh, clear.xtmelogit c_use urban age child* || district: urban, cov(uns) var.reffadjustsim _cons urban, eqn(district) seed(12345)

Example 5: based on xtmepoisson helpfile.webuse epilepsy, clear.xtmepoisson seizures treat lbas lbas_trt lage visit || subject: visit,cov(uns) var intpoints(9).reffadjustsim _cons visit, eqn(subject) seed(12345)

Example 6: repeated group variable.webuse nlswork, clear.xtmixed ln_w grade age || idcode: tenure union, cov(uns) || idcode:race, cov(uns) var.reffadjustsim tenure union, eqn(idcode) sub(1) seed(12345).reffadjustsim race _cons, eqn(idcode) sub(2) seed(12345)---------------------------------------------------------------------------

reffadjustsimsaves the following inr():Scalars

r(N)number of simulated observationsIf

waldtypeis not specified,reffadjustsimsaves the following for each indepvar inr():Scalars

r(n_cent_indepvar)number of centiles requested (usually 2)r(c_1_indepvar)value of 1st centile for indepvarr(lb_1_indepvar)1st centile lower confidence boundr(ub_1_indepvar)1st centile upper confidence boundr(c_2_indepvar)value of 2nd centile for indepvarr(lb_2_indepvar)2nd centile lower confidence boundr(ub_2_indepvar)2nd centile upper confidence boundr(med_indepvar)median of indepvarr(lb_med_indepvar)median lower confidence boundr(ub_med_indepvar)median upper confidence boundIf

waldtypeis specified,reffadjustsimsaves the following inr():Matrices

r(b)vector of adjusted coefficientsr(V)estimated variance-covariance matrix of the adjusted coefficientsIf

waldtypeandpostare specified,reffadjustsimalso saves the following ine():Scalars

e(N)number of simulated observationsMacros

e(cmd)reffadjustsime(depvar)name of the dependent variablee(properties)b VMatrices

e(b)vector of adjusted coefficientse(V)estimated variance-covariance matrix of the adjusted coefficients

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

Fisher RA. 1925. Chapter 5: Tests of significance of means, differences of means, and regression coefficients, Section 29: Regression with several independent variates in Statistical Methods for Research Workers. Oliver and Boyd, Edinburgh.

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. http://www.bristol.ac.uk/cmm/software/mlwin/download/manuals.html.

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.

Kate Tilling, School of Social and Community Medicine, University of Bristol, UK.

Also seeHelp:

reffadjust,reffadjust4nlcom,runmlwin(if installed),mcmcsum(if installed),nlcom,xtmixed,xtmelogit,xtmepoisson