write.IGLS is an internal function which creates an MLwiN macro file to fit a multilevel model using IGLS.
write.IGLS(
indata,
dtafile,
oldsyntax = FALSE,
resp,
levID,
expl,
rp,
D = "Normal",
nonlinear = c(0, 1),
categ = NULL,
notation = NULL,
nonfp = NA,
clre = NULL,
Meth = 1,
extra = FALSE,
reset,
rcon = NULL,
fcon = NULL,
maxiter = 20,
convtol = 2,
mem.init = "default",
optimat = FALSE,
weighting = NULL,
fpsandwich = FALSE,
rpsandwich = FALSE,
macrofile,
IGLSfile,
resifile,
resi.store = FALSE,
resioptions,
debugmode = FALSE,
startval = NULL,
namemap = sapply(colnames(indata), as.character),
saveworksheet = NULL,
rng.version = 10
)Outputs a modified version of namemap containing newly generated short names.
A data.frame object containing the data to be modelled.
The name of the temporary file used to send the data to MLwiN, which is in Stata format (i.e. with extension .dta).
Specified as FALSE if new syntax has been used in
Formula object, else specified as TRUE (to enable
back-compatibility).
A character string (vector) of the response variable name(s).
A character string (vector) of the specified level ID name(s). The
ID(s) should be sorted in the descending order of levels (e.g.
levID = c('level2', 'level1') where 'level2' is the higher
level).
A character string (vector) of explanatory (predictor) variable name(s).
A character string (vector) of random part of random variable name(s).
A character string/vector specifying the type of distribution to be modelled, which
can include 'Normal' (the default), 'Binomial', 'Poisson',
'Negbinom', 'Unordered Multinomial', 'Ordered Multinomial',
'Multivariate Normal', or 'Mixed'. In the case of the latter,
'Mixed' precedes the response types which also need to be listed in
D, e.g. c('Mixed', 'Normal', 'Binomial'); these need to be
be listed in the same order to which they are referred to in the
Formula object (see runMLwiN, Formula.translate,
Formula.translate.compat. 'Mixed' combinations can consist of
'Normal' and 'Binomial' or 'Normal' and 'Poisson'.
A character vector specifying linearisation method for discrete
response models (see Chapter 9 of Rasbash et al 2012, and Goldstein 2011).
N = 0 specifies marginal quasi-likelihood
linearization (MQL), whilst N = 1 specifies penalised quasi-
likelihood linearization (PQL); M = 1 specifies first order
approximation, whilst M = 2 specifies second order approximation.
nonlinear = c(N = 0, M = 1) by default. First order marginal
quasi-likelihood (MQL1) only option for single-level discrete response
models.
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),
NA(s) if no reference group; the third row states the number of
categories for each variable. Supports back-compatibility with R2MLwiN
versions <0.8-0.
Specifies the model subscript notation to be used in the
MLwiN equations window. 'class' means no multiple subscripts, whereas
'level' has multiple subscripts.
Removes the fixed part of random variable(s). NA if no
variable to be removed.
A matrix used to define which elements of the random effects matrix
to remove (i.e. hold constant at zero). Removes
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 column
corresponds to a removed entry of the covariance matrix. See e.g. demo(UserGuide07)
for an example.
Specifies which maximum likelihood estimation method to be used.
If Meth = 0 estimation method is set to RIGLS. If Meth = 1
estimation method is set to IGLS (the default setting).
If TRUE, extra binomial, extra negative binomial,
extra Poisson or extra multinomial distributions assumed, else FALSE.
A vector of length(levID) specifying the action to be
taken, at each level, if a variance parameter is estimated at a particular
iteration to be negative during estimation. Values specified in
ascending order of level hierarchy: if 0 a negative variance
estimate is reset to zero and so are any associated covariances; if 1
a negative variance estimate is reset to zero but not the associated
covariances; if 2 no resetting takes place. E.g. reset = c(0, 1)
to assign value 0 to level 1 and value 1 to level 2 of
two-level model.
Matrix specifying constraints on the random parameters as
specified in random.ui and random.ci in the constraints
option within estoptions (see runMLwiN). random.ci
is appended to the bottom row of random.ui.
Matrix specifying constraints on the fixed coefficients as
specified in fixed.ui and fixed.ci in the constraints
option within estoptions (see runMLwiN). fixed.ci
is appended to the bottom row of fixed.ui.
Numeric value specifying the maximum number of iterations, from the start, before estimation halts.
Numeric value specifying the convergence criterion, as
specified in the tol option within estoptions (see
runMLwiN). If value of convtol is m, estimation will be
deemed to have converged when the relative change in the estimate for all
parameters from one iteration to the next is less than 10(-m). Defaults to
value of 2 for m if not otherwise specified.
If calling write.IGLS directly, if wish to use defaults, value needs to be
specified as 'default', else specify a vector of length 5 corresponding
to the following order: number of levels; worksheet size in thousands of cells;
the number of columns; the number of explanatory variables; the number of group
labels.
This option instructs MLwiN to limit the maximum matrix size
that can be allocated by the (R)IGLS algorithm. Specify optimat = TRUE
if MLwiN gives the following error message 'Overflow allocating smatrix'.
This error message arises if one more higher-level units is extremely large
(contains more than 800 lower-level units). In this situation R2MLwiN's
default behaviour is to instruct MLwiN to allocate a larger matrix size to
the (R)IGLS algorithm than is currently possible. Specifying
optimat = TRUE caps the maximum matrix size at 800 lower-level units,
circumventing the MLwiN error message, and allowing most MLwiN
functionality.
A list of two items, one of which is a list called weightvar
the length of which corresponds
to the number of levels in the model, in descending order from highest level first.
The other is an option standardised which is TRUE or FALSE.
Specifies standard error type for fixed parameters. If
fpsandwich = TRUE, robust or `sandwich' standard errors based on raw
residuals are used, if fpsandwich = FALSE (default) then standard,
uncorrected, IGLS or RIGLS computation used.
Specifies standard error type for random parameters. If
rpsandwich = TRUE, robust or `sandwich' standard errors based on raw
residuals are used, if rpsandwich = FALSE (default) then standard,
uncorrected, IGLS or RIGLS `plug in' estimates used.
A file name where the MLwiN macro file will be saved. The default location is in the temporary folder.
A file name where the parameter estimates will be saved. The default location is in the temporary folder.
A file name where the residuals will be saved. The default location is in the temporary folder.
A logical value to indicate if the residuals are to be
stored (TRUE) or not (FALSE).
A string vector to specify the various residual options.
The 'variances' option calculates the posterior variances instead of
the posterior standard errors; the 'standardised', 'leverage',
'influence' and 'deletion' options calculate standardised,
leverage, influence and deletion residuals respectively; the
'sampling' option calculates the sampling variance covariance matrix
for the residuals; the 'norecode' option prevents residuals with
values exceedingly close or equal to zero from being recoded to missing; the
reflate option returns unshrunken residuals. Note that the default option is
resioptions = c('variance'); 'variance' cannot be used together
with the other options to calculate standardised, leverage, influence and
deletion residuals.
A logical value determining whether MLwiN is run in the
background or not. The default value is FALSE: i.e. MLwiN is run in
the background. If TRUE the MLwiN GUI is opened, and then pauses after the model
has been set-up, allowing user to check starting values; pressing 'Resume macro'
will then fit the model. Once fit, pressing 'Resume macro' once more will save
the outputs to the workdir ready to be read by R2MLwiN. Users can
instead opt to 'Abort macro' in which case the outputs are not saved to the
workdir. This option currently
works for 32 bit version of MLwiN only (automatically switches unless
MLwiNPath or options(MLwiNPath)
has been set directly to the executable).
A list of numeric vectors specifying the starting values.
FP.b corresponds to the estimates for the fixed
part; FP.v specifies the variance/covariance estimates for the fixed
part; RP.b specifies the variance estimates for the random part;
RP.v corresponds to the variance/covariance matrix of the variance
estimates for the random part.
A mapping of column names to DTA friendly shorter names
A file name used to store the MLwiN worksheet after the model has been estimated.
An integer indicating which random number generator should be used by MLwiN.
Zhang, Z., Charlton, C.M.J., Parker, R.M.A., Leckie, G., and Browne, W.J. (2016) Centre for Multilevel Modelling, University of Bristol.
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.
write.MCMC