Writes MLwiN macros to fit models using Markov chain Monte Carlo (MCMC) methods
Description
write.MCMC is an internal function which creates an MLwiN macro file to fit models using MCMC.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14  write.MCMC(indata, dtafile, oldsyntax = FALSE, resp, levID, expl, rp,
D = "Normal", nonlinear = c(0, 1), categ = NULL, notation = NULL,
nonfp = NULL, clre = NULL, Meth = 1, merr = NULL, carcentre = FALSE,
maxiter = 20, convtol = 2, seed = 1, iterations = 5000,
burnin = 500, scale = 5.8, thinning = 1, priorParam = "default",
refresh = 50, fixM = 1, residM = 1, Lev1VarM = 1, OtherVarM = 1,
adaption = 1, priorcode = c(gamma = 1), rate = 50, tol = 10,
lclo = 0, mcmcOptions, fact = NULL, xc = NULL, mm = NULL,
car = NULL, BUGO = NULL, mem.init = "default", optimat = FALSE,
modelfile, initfile, datafile, macrofile, IGLSfile, MCMCfile, chainfile,
MIfile, resifile, resi.store = FALSE, resioptions, resichains,
FACTchainfile, resi.store.levs = NULL, debugmode = FALSE,
startval = NULL, dami = NULL, namemap = sapply(colnames(indata),
as.character), saveworksheet = NULL)

Arguments
indata 
A data.frame object containing the data to be modelled. 
dtafile 
The file name of the dataset to be imported into MLwiN, which is in Stata format (i.e. with extension .dta). 
oldsyntax 
Specified as 
resp 
A character string (vector) of response variable(s). 
levID 
A character string (vector) of the specified level ID(s). The
ID(s) should be sorted in the descending order of levels (e.g.

expl 
A character string (vector) of explanatory (predictor) variable(s). 
rp 
A character string (vector) of random part of random variable(s). 
D 
A character string/vector specifying the type of distribution to be modelled, which
can include 
nonlinear 
A character vector specifying linearisation method for IGLS
starting values for discrete
response models (see Chapter 9 of Rasbash et al 2012, and Goldstein 2011).

categ 
Specifies categorical variable(s) as a matrix. Each column
corresponds to a categorical variable; the first row specifies the name(s)
of variable(s); the second row specifies the name(s) of reference group(s),

notation 
Specifies the model subscript notation to be used in the
MLwiN equations window. 
nonfp 
Removes the fixed part of random variable(s). 
clre 
A matrix used to estimate some, but not all, of the variances and covariances for a set of coefficients at a particular level. Remove from the random part at level <first row> the covariance matrix element(s) defined by the pair(s) of rows <second row> <third row>. Each row corresponds to a removed entry of the covariance matrix. 
Meth 
Specifies the maximum likelihood estimation method to be used
when generating starting values via (R)IGLS.
If 
merr 
A vector which setsup measurement errors on predictor
variables. The first element 
carcentre 
If CAR model (i.e. if 
maxiter 
When generating starting values via (R)IGLS, a numeric
value specifying the total number of iterations, from
the start, before IGLS estimation halts (if 
convtol 
When generating starting values via (R)IGLS, a numeric
value specifying the IGLS convergence criterion, as
specified in the 
seed 
An integer specifying the random seed in MLwiN. 
iterations 
An integer specifying the number of iterations after burnin. 
burnin 
An integer specifying length of the burnin. 
scale 
An integer specifying the scale factor of proposed variances; this number will be multiplied by the estimated parameter variance (from IGLS/RIGLS) to give the proposal distribution variance. 
thinning 
An integer specifying the frequency with which successive
values in the Markov chain are stored. By default 
priorParam 
A vector specifying the informative priors used, as output
from 
refresh 
An integer specifying how frequently the parameter estimates
are refreshed on the screen during iterations; only applies if

fixM 
Specifies the fixed effect method: 
residM 
Specifies the residual method: 
Lev1VarM 
Specifies the level 1 variance method: 
OtherVarM 
Specifies the variance method for other levels: 
adaption 

priorcode 
A vector indicating which default priors are to be used
for the variance parameters. It defaults to 
rate 
An integer specifying the acceptance rate (as a percentage);
this command is ignored if 
tol 
An integer specifying tolerance (as a percentage) for the acceptance rate. 
lclo 
This command toggles on/off the possible forms of complex level
1 variation when using MCMC. 
mcmcOptions 
A list of other MCMC options used. See ‘Details’ below. 
fact 
A list of objects specified for factor analysis. See ‘Details’ below. 
xc 
Indicates whether model is crossclassified ( 
mm 
Specifies the structure of a multiple membership model.
Can be a list of variable names, a list of vectors, or a matrix (e.g. see

car 
A list specifying structure of a conditional autoregressive (CAR)
model. Each element of the list corresponds to a level (classification) of
the model, in descending order. If a level is not a spatial classification,
then 
BUGO 
If non 
mem.init 
A vector which sets and displays worksheet capacities for
the current MLwiN session according to the value(s) specified. By default,
the number of levels is 
optimat 
This option instructs MLwiN to limit the maximum matrix size
that can be allocated by the (R)IGLS algorithm. Specify 
modelfile 
A file name where the BUGS model will be saved in .txt format. 
initfile 
A file name where the BUGS initial values will be saved in .txt format. 
datafile 
A file name where the BUGS data will be saved in .txt format. 
macrofile 
A file name where the MLwiN macro file will be saved. 
IGLSfile 
A file name where the IGLS estimates will be saved. 
MCMCfile 
A file name where the MCMC estimates will be saved. 
chainfile 
A file name where the MCMC chains will be saved. 
MIfile 
A file name where the missing values will be saved. 
resifile 
A file name where the residual estimates will be saved. 
resi.store 
A logical value to indicate if residuals are to be stored
( 
resioptions 
A string vector to specify the various residual options.
The 
resichains 
A file name where the residual chains will be saved. 
FACTchainfile 
A file name where the factor chains will be saved. 
resi.store.levs 
An integer vector indicating the levels at which the residual chains are to be stored. 
debugmode 
A logical value determining whether MLwiN is run in the
background or not. The default value is 
startval 
A list of numeric vectors specifying the starting values
when using MCMC. 
dami 
This command outputs a complete (i.e. including nonmissing
responses) response variable y. If 
namemap 
A mapping of column names to DTA friendly shorter names 
saveworksheet 
A list of file names (one for each chain) used to store the MLwiN worksheet after the model has been estimated. 
Details
A list of other MCMC options as used in the argument
mcmcOptions
:

orth
: Iforth = 1
, orthogonal fixed effect vectors are used; zero otherwise. 
hcen
: An integer specifying the level where we use hierarchical centering. 
smcm
: Ifsmcm = 1
, structured MCMC is used; zero otherwise. 
smvn
: Ifsmvn = 1
, the structured MVN framework is used; zero otherwise. 
paex
: A matrix of Nx2; in each row, if the second digit is1
, parameter expansion is used at level <the first digit>. 
mcco
: This command allows the user to have constrained settings for the lowest level variance matrix in a multivariate Normal model. If value is0
, it estimates distinct variances for each residual error and distinct covariances for each residual error pair. Four other settings are currently available:
1
fits stuctured errors with a common correlation paramater and a common variance parameter; 2
fits AR1 errors with a common variance parameter; 3
fits structured errors with a common correlation parameter and independent variance parameters; 4
fits AR1 errors with independent variance parameters.
A list of objects specified for crossclassified and/or multiple membership
models, as used in the argument xclass
:

class
: An integer (vector) of the specified class(es). 
N1
: This defines a multiple membership acrossN1
units at levelclass
.N1
>1 if there is multiple membership. 
weight
: If there is multiple membership then the column numberweight
, which is the length of the dataset, will contain the first set of weights for the multiple membership. Note that there should beN1
weight columns and they should be sequential in the worksheet starting fromweight
. 
id
: If the response is multivariate then the column numberid
must be input and this contains the first set of identifiers for the classification. Note that for a pvariate model each lowest level unit contains p records and the identifiers (sequence numbers) for each response variate need to be extracted intoid
and following columns. There should beN1
of these identifier columns and they should be sequential starting fromid
in the multivariate case. 
car
:car = TRUE
indicates the spatial CAR model;FALSE
otherwise.car = FALSE
if ignored.
A list of objects specified for factor analysis, as used in the argument
fact
:

nfact
: Specifies the number of factors 
lev.fact
: Specifies the level/classification for the random part of the factor for each factor. 
nfactcor
: Specifies the number of correlated factors 
factcor
: a vector specifying the correlated factors: the first element corresponds to the first factor number, the second to the second factor number, the third element corresponds to the starting value for the covariance and the fourth element to whether this covariance is constrained (1
) or not (0
). If more than one pair of factors is correlated, then repeat this sequence for each pair. 
loading
: A matrix specifying the starting values for the factor loadings and the starting value of the factor variance. Each row corresponds to a factor. 
constr
: A matrix specifying indicators of whether the factor loadings and the factor variance are constrained (1
) or not (0
).
Value
Outputs a modified version of namemap containing newly generated short names.
Note
Note that for FixM
, residM
, Lev1VarM
and
OtherVarM
, not all combinations of methods are available for all sets
of parameters and all models.
Author(s)
Zhang, Z., Charlton, C.M.J., Parker, R.M.A., Leckie, G., and Browne, W.J. (2016) Centre for Multilevel Modelling, University of Bristol.
References
Goldstein, H. (2011) Multilevel Statistical Models. 4th Edition. London: John Wiley and Sons.
Rasbash, J., Steele, F., Browne, W.J. and Goldstein, H. (2012) A User's Guide to MLwiN Version 2.26. Centre for Multilevel Modelling, University of Bristol.
See Also
write.IGLS