R2MLwiN (version 0.1-7)

runMLwiN: Calls MLwiN from R

Description

This function executes MLwiN and then brings results back to R. A summary of the model will be printed, and a list of output objects will be saved in the work directory.

Usage

runMLwiN(Formula, levID, D = "Normal", indata,
estoptions = list(EstM = 0), BUGO = NULL,
MLwiNPath = "C:/Program Files (x86)/MLwiN v2.27/", workdir=tempdir())

Arguments

Formula

A formula object (or a character string) specifying the model formula. See Formula.translate for details.

levID

A character (vector) specifying the level ID(s).

D

A character string/vector specifying the distribution to be modelled.

indata

A data.frame object containing the data to be modelled.

estoptions

A list of options used for estimating the model. See Value below.

BUGO

A vector specifying BUGS options. If non-null, then WinBUGS/OpenBUGS, in conjunction with MLwiN, are used for modelling. see Value below.

MLwiNPath

A path to the MLwiN folder. By default, MLwiNPath = "C:/Program Files (x86)/MLwiN v2.27/".

workdir

A path to the folder where the output files are to be saved. If the folder specified does not exist, a new folder of that name is created; workdir=tempdir() by default.

Value

• The argument estoptions is a list which can contain the following options used for estimating the model:
• resi.store
  A logical value indicating whether residuals are to be stored or not.
• resioptions
  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","sampling"); "variance" cannot be used together with the other options to calculate standardised, leverage, influence and deletion residuals.
• 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 FALSE: i.e., MLwiN is run in the background. If TRUE MLwiN remains open after the model has run, and must be closed for the output to be returned to R. This option currently works for the 32bit MLwiN only.
• x64
  A logical value indicating whether the 64 bit version of MLwiN is used. If FALSE (by default), the 32 bit version is called.
• clean.files
  If TRUE, the generated files will be removed from the workdir.
• show.file
  A logical value indicating whether the output files (e.g. macro file) are shown on the screen.
• 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 the covariance matrix element(s) defined by the pair(s) of rows . Each row corresponds to a removed entry of the covariance matrix.
• notation
  Specifies the model subscript notation to be used in the MLwiN equations window. "class" means no multiple subscripts, whereas "level" has multiple subscripts.
• 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 nlev+1, worksheet size in thousands of cells is 6000, the number of columns is 2500, the number of explanatory variables is num_vars+10, and the number of group labels is 20. nlev is the number of levels specified by levID, and num_vars is approximately the number of explanatory variables calculated initially.
• nonlinear
  LINEarise mode N order M. 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.
• Meth
  Specifies which maximum likelihood estimation method is 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 Meth=2, alternate between IGLS and RIGLS.
• merr
  A vector which sets-up measurement errors on predictor variables. The first element N defines the number of variables that have measurement errors. Then, for each variable with measurement error, a pair of inputs is required: value Ma is the explanatory variable number for the Mth variable which has measurement error and value Mb is the variance of the measurement errors for the Mth variable.
• fact
  A list of objects specified for factor analysis, including nfact, lev.fact, nfactor, factor, loading and constr. See MacroScript2 for details.
• weighting
  A list of objects specified for using weights in an analysis, including levels, weights, mode, FSDE and RSDE. See MacroScript1 for details.
• centring
  If not empty, centring is used for the selected explanatory variables. A list of objects, named by explanatory variables, specifies the ways to centre the variables. list(rv1=1,...) means that rv1 is centring by its ground mean; list(rv1=c(2,'group'),...) means that rv1 is centring by the mean of the specified group. 'group' is a string specifying the group binary indicator, i.e., a vector of (0, 1); list(rv1=c(3,value),...) means that rv1 is centring by the specified numerical value. Here rv1 is a string of the explanatory variable.
• xclass
  A list of objects specified for cross-classified and/or multiple membership models, including class, N1, weight, id and car. See MacroScript2 for details.
• mcmcMeth
  A list of objects specifying advanced MCMC methodology and prior options, including the following: iterations, burnin, thinning, seed, priorParam, scale, refresh, fixM, residM, Lev1VarM, OtherVarM, adaption, priorcode, startval, rate, tol, lclo and nopause. See MacroScript2 for details.
• mcmcOptions
  A list of objects specifying MCMC options, including the following: orth, hcen, smcm, smvn, paex and mcco. See MacroScript2 for details.
• The argument BUGO is a vector specifying BUGS options as follows:
• version
  This indicates the version of WinBUGS where 3 = version 1.3 and 4 = version 1.4.
• n.chains
  This specifies the number of chains used in the BUGS algorithm.
• debug
  This determines whether BUGS stays open following completion of the model run; debug=F by default.
• seed
  This sets the random number generator in BUGS.
• bugs
  This specifies the path of the BUGS executable.
• OpenBugs
  If OpenBugs=TRUE, OpenBUGS is used. Otherwise, WinBUGS is used.
• If BUGO is non-NULL then the output is an mcmc.list object. If the IGLS algorithm is used, (i.e., EstM=0), then the outputs are
• estIGLS
  Captures the parameter estimates from MLwiN using the IGLS algorithm. <_fp_b column=""> has the fixed part estimates and its variances and covariances are stored in <_fp_v column="">; <_rp_b column=""> has the random part estimates and its variances and covariances are stored in <_rp_v column="">; The likelihood statistic is stored in <_stats column="">.
• FP
  Displays the fixed part estimates.
• RP
  Displays the random part estimates.
• FP.cov
  Displays a covariance matrix of the fixed part estimates.
• RP.cov
  Displays a covariance matrix of the random part estimates.
• call
  The matched call.
• LIKE
  The likelihood statistic (-2*log(like))
• residual
  If resi.store is TRUE, then the residual estimates at all levels are returned.
• If the MCMC algorithm is used, (i.e., EstM=1), then the outputs are
• estMCMC
  Captures the parameter estimates from MLwiN using the MCMC algorithm. <_fp_b column=""> has the fixed part estimates and its variances and covariances are stored in <_fp_v column="">; <_rp_b column=""> has the random part estimates and its variances and covariances are stored in <_rp_v column="">; DIC and likelihood measures are stored in <_stats column="">.
• chains
  Captures the MCMC chains from MLwiN for all parameters.
• FP
  Displays the fixed part estimates.
• RP
  Displays the random part estimates.
• FP.cov
  Displays a covariance matrix of the fixed part estimates.
• RP.cov
  Displays a covariance matrix of the random part estimates.
• call
  The matched call.
• LIKE
  The likelihood statistic (-2*log(like))
• BDIC
  Bayesian Deviance Information Criterion (DIC)
• fact.loadings
  If fact is not empty, then the factor loadings are returned.
• fact.cov
  If fact is not empty, then factor covariances are returned.
• residual
  If resi.store is TRUE, then the residual estimates at all levels are returned.
• resi.chains
  If resi.store.levs is not empty, then the residual chains at these levels are returned.
• chains.bugs
  If BUGO is used, then the output chains from WinBUGS/OpenBUGS are returned.

See Also

Formula.translate,MacroScript1,MacroScript2

Examples

## The R2MLwiN package includes scripts to replicate all the analyses in
## Browne, W.J. (2009) MCMC estimation in MLwiN Version 2.13.
## Version 2.25 is available online; download from the following link:
## http://www.bristol.ac.uk/cmm/software/mlwin/download/mcmc-print.pdf
## Centre for Multilevel Modelling, University of Bristol

#Contents
#01 Introduction to MCMC Estimation and Bayesian Modelling
#02 Single Level Normal Response Modelling
#03 Variance Components Models
#04 Other Features of Variance Components Models
#05 Prior Distributions, Starting Values and Random Number Seeds
#06 Random Slopes Regression Models
#07 Using the WinBUGS Interface in MLwiN
#08 Running a Simulation Study in MLwiN
#09 Modelling Complex Variance at Level 1 / Heteroscedasticity
#10 Modelling Binary Responses
#11 Poisson Response Modelling
#12 Unordered Categorical Responses
#13 Ordered Categorical Responses
#14 Adjusting for Measurement Errors in Predictor Variables
#15 Cross Classified Models
#16 Multiple Membership Models
#17 Modelling Spatial Data
#18 Multivariate Normal Response Models and Missing Data
#19 Mixed Response Models and Correlated Residuals
#20 Multilevel Factor Analysis Modelling
#21 Using Structured MCMC
#22 Using the Structured MVN framework for models
#23 Using Orthogonal fixed effect vectors
#24 Parameter expansion
#25 Hierarchical Centring

## Take Chapter03 as an example
## To find the location of a demo for Chapter03
file.show(system.file("demo", "Chapter03.R", package="R2MLwiN"))

## MLwiN folder
mlwin = "C:/Program Files (x86)/MLwiN v2.27/"

## To run the demo for Chapter03
demo(Chapter03)