A character vector specifying the level ID(s). Deprecated
syntax: by default this is NULL and level ID(s) are specified
in the Formula object.
D
A character string/vector specifying the type of distribution to be modelled, which
can include 'Normal' (the default), 'Binomial', 'Poisson',
'Negbinom', 'Unordered Multinomial', 'O
data
A data.frame object containing the data to be modelled.
Optional (but recommended): if empty, data taken from environment of
formula.
estoptions
A list of options used for estimating the model. See
`Details' below.
BUGO
A vector specifying BUGS options. If non-null, then
WinBUGS/OpenBUGS, in conjunction with MLwiN, are used for modelling. Non-null
only applicable if EstM = 1. See `Details', below.
MLwiNPath
A path to the MLwiN folder. By default, MLwiNPath = NULL
and path set by options('MLwiN_path'), the default for which can be
changed via options(MLwiN_path = 'path/to/MLwiN vX.XX/')).
stdout
See system2; '' by default (i.e.
output to stdout sent to R console).
stderr
See system2; '' by default (i.e.
output to stderr sent to R console).
workdir
A path to the folder where the outputted files are to be saved.
If the folder specified does not exist, a new folder of that name is
created; workdir = tempdir() by default.
checkversion
If TRUE (default), returns version number unless
(a) version detected is unknown or newer than MLwiN version available
when current version of R2MLwiN was released, in which case returns text
to this effect, or (b) version detected > 1 yea
indata
A data.frame object containing the data to be modelled.
Deprecated syntax: by default this is NULL and the data.frame
is instead referenced via data.
Value
If BUGO is non-NULL then the output is an mcmc.list
object.
If the IGLS algorithm is used (i.e., EstM = 0), then returns mlwinfitIGLS-class object;
if MCMC estimation used (i.e., EstM = 1), then returns mlwinfitMCMC-class object.
resi.store: a logical value indicating whether residuals are to be
stored or not. Defaults toFALSE.
resioptions: a string vector to specify the various residual options.
The'variance'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.
WhenEstM = 1(i.e. MCMC estimation)'variance'is default value, and the only other permissible value is'standardised'(else function call stopped with appropriate error message).
WhenEstM = 0(i.e. (R)IGLS estimation),'variance'cannot be specified together with'standardised','leverage'or'deletion'(function call stopped with appropriate error message).
Default isresioptions = c('variance').
resi.store.levs: an integer vector indicating the levels at which the
residual chains are to be stored (NULLby default). Non-NULLvalues
not valid whenEstM = 0(i.e. (R)IGLS estimation), else ifEstM = 0andresi.store.levsnon-NULL, residual chains at specified levels
are returned.
debugmode: a logical value determining whether MLwiN is run in the
background or not. The default value isFALSE: i.e. MLwiN is run in
the background. IfTRUEthe 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 theworkdirready to be read byR2MLwiN. Users can
instead opt to 'Abort macro' in which case the outputs are not saved to theworkdir. This option currently
works for 32 bit version of MLwiN only (automatically switches unlessMLwiNPathoroptions(MLwiNPath)has been set directly to the executable).
x64: a logical value indicating
whether the 64 bit version of MLwiN is used (unlessMLwiNPathoroptions(MLwiNPath)has been set directly to the executable). The default is determined by the characteristics
of the operating system on which the script is executed. IfFALSE,
the 32 bit version is called, ifTRUE64 bit version is called.
clean.files: specifies whether the generated files are removed from
theworkdir(TRUE, the default) or not (FALSE).
show.file: a logical value indicating whether the output files (e.g.
MLwiN macro file) are shown on the screen. Defaults toFALSE.
clre: 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 the covariance matrix element(s)
defined by the pair(s) of rows . Each column
corresponds to a removed entry of the covariance matrix. See e.g.demo(UserGuide07)for an example.
notation: specifies the model subscript notation
to be used in the MLwiN equations window.'class'means no multiple
subscripts, whereas'level'has multiple subscripts. Ifnotation = NULL, defaults to'level'if'xc = NULL'else
defaults to'class'.
mem.init: sets and displays worksheet capacities for
the current MLwiN session. A vector of length 5 corresponding to
the following order: number of levels (defaults to 1 + the number of
levels specified in the function call); worksheet size in thousands of cells
(default is 6000); the number of columns (default is 2500); the number of
explanatory variables (default it 10 + number of explanatory variables
calculated initially); the number of group labels (default is 20).
optimat: instructs MLwiN to limit the maximum matrix size
that can be allocated by the (R)IGLS algorithm. Specifyoptimat = TRUEif MLwiN gives the following error message 'Overflow allocating smatrix'.
This error message arises if one or more higher-level units is/are extremely
large (containing more than 800 lower-level units). In this situationrunMLwiN's
default behaviour is to instruct MLwiN to allocate a larger matrix size to
the (R)IGLS algorithm than is currently possible. Specifyingoptimat = TRUEcaps the maximum matrix size at 800 lower-level units,
circumventing the MLwiN error message, and allowing most MLwiN
functionality.
nonlinear: a character vector specifying linearisation method for discrete
response models estimated via IGLS (see Chapter 9 of Rasbash et al 2012,
and Goldstein 2011).N = 0specifies marginal quasi-likelihood
linearization (MQL), whilstN = 1specifies penalised quasi-
likelihood linearization (PQL);M = 1specifies first order
approximation, whilstM = 2specifies 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. Pertains to discrete response models estimated via IGLS: i.e. whenEstM = 0inestoptions, and for starting values when estimated via IGLS
for MCMC (EstM = 1).
Meth: specifies which maximum likelihood estimation method is to be
used. IfMeth = 0estimation method is set to RIGLS. IfMeth = 1estimation method is set to IGLS (the default setting). Pertains to models
estimated via (R)IGLS: i.e. whenEstM = 0inestoptions, and for starting
values when estimated via (R)IGLS for MCMC (EstM = 1).
merr: a vector which sets-up measurement errors on predictor
variables. The first elementNdefines the number of variables that
have measurement errors. Then, for each variable with measurement error, a
pair of inputs are required: the first of these is the explanatory variable
name as a character string, and the second is the variance of
the measurement error for this variable. Seedemo(MCMCGuide14)for an
example.
fact: a list of objects specified for factor analysis,
including:
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).
weighting: a deprecated option for specifying weights in IGLS estimation:
seefpsandwichandrpsandwichfor new method of doing so.weightingis a list of objects includinglevels,weights,mode,FSDEandRSDE; seewrite.IGLSfor details.
centring: deprecated method (only applicable when using old syntax
pre-R2MLwiNv.0.8-0) specifying function by
which explanatory variables are to be centred (users can instead transform
variables prior torunMLwiNcall).
If non-NULL, centring is used for the selected explanatory
variables (centring = NULLby default).centringis a list of
objects specifying the methods to be used to centre specific explanatory
variables. E.g.list(age = 1, ...)specifies that the explanatory
variableageis to be centred around its grand mean;list(age = c(2, 'district'), ...)specifies thatageis to be
centred around its group mean, where group defined by the variabledistrict;
andlist(age = c(3, 18), ...)specifies thatageis to
be centred around the value18.
xclass: a deprecated option for specifying cross-classified and/or
multiple membership models; seexcandmmfor new method of
doing so.xclassis a list of objects includingclass,N1,weight,idandcar; seewrite.MCMCfor details.
mcmcOptions: a list of objects specifying MCMC options, including the
following:
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 .
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:
ll{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.
Details
With regard to runMLwiN's Formula object, see formula
for notes on general usage, noting the following differences:
The intercept is not included by default (this is keeping with the manner
in which models are specified in MLwiN). To include an intercept, then, one
can specify e.g.normexam ~ 1 + standlrt + (1 | student)or, assumingconsis a constant of ones,normexam ~ cons + standlrt + (cons | student). (Note also,
as further detailed below, for normal response models the level 1 ID (studentin this example)
needs to be explicitly included in the random part of the model formula; this is not the
case for discrete response models.
The link function and denominator are included in the Formula object, e.g.
fitting a logistic model in which the variable denom is specified as the denominator:
logit(resp, denom) ~ 1 + age + (1 | region).