R2MLwiN (version 0.8-1)

runMLwiN: Calls MLwiN from R.

Description

This function executes MLwiN and then brings results back to R.

Usage

runMLwiN(Formula, levID = NULL, D = "Normal", data = NULL,
  estoptions = list(EstM = 0), BUGO = NULL, MLwiNPath = NULL,
  stdout = "", stderr = "", workdir = tempdir(), checkversion = TRUE,
  indata = NULL)

Arguments

Formula

A formula object specifying the model formula. See Formula.translate (Formula.translat

levID

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.

code

estoptions

pkg

R2MLwiN

tabular

lll

strong

Distribution

tab

Format of Formula object Where can equal... 'Normal' ~ 1 + + (1|) + (1|) + ... (identity link assumed) 'Poisson' () ~ 1 + offset() + + (1|) + ... log 'Negbinom'* () ~ 1 + offset() + (1|) + ... log 'Binomial' (, ) ~ 1 + + (1|) + ... logit,probit,cloglog 'Unordered Multinomial' (, , ) ~ 1 + + (1|) + ... logit 'Ordered Multinomial' (, , ) ~ 1 + + [] + (1[]|) + (1|) + ... logit,probit,cloglog 'Multivariate Normal' c(, , ...) ~ 1 + + [] + (1[]|) + (1|) + (1|) + ... (identity link assumed) c('Mixed', 'Normal', 'Binomial') c(, ..., (, ), ...) ~ 1 + + [] + (1[]|) + (1|) + (1|) + ... logit*,probit,cloglog* c('Mixed', 'Normal', 'Poisson')* c(, ..., (, ), ...) ~ 1 + + [] + (1[]|) + (1|) + (1|) + ... log

itemize

• EstM: specifies estimation method. WhenEstM = 0(default), estimation method is (R)IGLS, otherwiseEstM = 1specifies MCMC estimation.
• 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).