runMLwiN {R2MLwiN}

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,
  allowcontrast = FALSE,
  indata = NULL,
  saveworksheet = NULL
)

Arguments

Formula

A formula object specifying the model formula. See Formula.translate (Formula.translate.compat details back-compatible functionality for deprecated syntax used in versions of R2MLwiN prior to 0.8-0) and also ‘Details’ below.

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', '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 Formula.translate, Formula.translate.compat). For (R)IGLS estimation (i.e. EstM = 0 in estoptions) 'Mixed' combinations can consist of 'Normal' and 'Binomial' or 'Normal' and 'Poisson'; for MCMC estimation (i.e. EstM = 0), on the other hand, only a combination of 'Normal' and 'Binomial' is available.

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 year older than MLwiN version available when current version of R2MLwiN was released, in which case function call stopped and user invited to update via usual channels. Can disable via FALSE e.g. if slowing execution time down (for example in a simulation).

allowcontrast

If TRUE, factor variables will follow the R behaviour when creating contrast variables. If FALSE (default) factor variables will be converted into a series of zero/one dummies.

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.

saveworksheet

A file name (or list of file names if more than one chain is specified) used to store the MLwiN worksheet after the model has been estimated.

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, assuming cons is a constant of ones, normexam ~ cons + standlrt + (cons | student). (Note also, as further detailed below, for normal response models the level 1 ID (student in 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).

Further details are as follows.

The random part of the model is specified in sets of parentheses arranged in descending order with respect to their hierarchy. E.g. in the case of a 3-level model, the variable containing the level 3 ID is specified first, then the variable containing the level 2 ID, etc. Note that the variable containing the level 1 ID also needs to be explicitly specified unless it is a discrete response model (in which case you should not specify it).

The table below summarises the options for the Formula argument in R2MLwiN. They assume an intercept is added (via ~ 1; for alternative specifications see formula). <link> denotes the link function, <y1>, <y2>, etc. represent response variables, <denom> denotes the denominator, <offs> the offset (optional), <L2>, <L1>, etc. the variables containing the level 2 and level 1 identifying codes, and <ref_cat> represents the reference category of a categorical response variable (optional: if unspecified the lowest level of the factor is used as the reference category). Explanatory variables are specified as e.g. <x1> + <x2>. For 'Ordered Multinomial', 'Multivariate Normal' and 'Mixed' responses, [<common>] indicates a common coefficient (i.e. the same for each category) is to be fitted; here <common> takes the form of a numeric identifier indicating the responses for which a common coefficient is to be added (e.g. [1:5] to fit a common coefficient for categories 1 to 5 of a 6-point ordered variable, [1] to fit a common coefficient for the response variable specified first in the Formula object for a 'Mixed' response model, etc.) Otherwise a separate coefficient (i.e. one for each category) is added. For 'Mixed' response models, the Formula arguments need to be grouped in the order the distributions are listed in D.

* denotes IGLS only in the table below.

Distribution	Format of Formula object	Where <link> can equal...
'Normal'	<y1> ~ 1 + <x1> + (1|<L2>) + (1|<L1>) + ...	(identity link assumed)
'Poisson'	<link>(<y1>) ~ 1 + offset(<offs>) + <x1> + (1|<L2>) + ...	log
'Negbinom'	<link>(<y1>) ~ 1 + offset(<offs>) + (1|<L2>) + ...	log
'Binomial'	<link>(<y1>, <denom>) ~ 1 + <x1> + (1|<L2>) + ...	logit,probit,cloglog
'Unordered Multinomial'	<link>(<y1>, <denom>, <ref_cat>) ~ 1 + <x1> + (1|<L2>) + ...	logit
'Ordered Multinomial'	<link>(<y1>, <denom>, <ref_cat>) ~ 1 + <x1> + <x2>[<common>] + (1[<common>]|<L3>) + (1|<L2>) + ...	logit,probit,cloglog
'Multivariate Normal'	c(<y1>, <y2>, ...) ~ 1 + <x1> + <x2>[<common>] + (1[<common>]|<L3>) + (1|<L2>) + (1|<L1>) + ...	(identity link assumed)
c('Mixed', 'Normal', 'Binomial')	c(<y1>, ..., <link> (<y2>, <denom>), ...) ~ 1 + <x1> + <x2>[<common>] + (1[<common>]|<L3>) + (1|<L2>) + (1|<L1>) + ...	logit*,probit,cloglog*
c('Mixed', 'Normal', 'Poisson')*	c(<y1>, ..., <link>(<y2>, <offset>), ...) ~ 1 + <x1> + <x2>[<common>] + (1[<common>]|<L3>) + (1|<L2>) + (1|<L1>) + ...	log

The argument estoptions is a list which can contain the following options used for estimating the model:

• EstM: specifies estimation method. When EstM = 0 (default), estimation method is (R)IGLS, otherwise EstM = 1 specifies MCMC estimation.

• resi.store: a logical value indicating whether residuals are to be stored or not. Defaults to FALSE.

• 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. When EstM = 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). When EstM = 0 (i.e. (R)IGLS estimation), 'variance' cannot be specified together with 'standardised', 'leverage' or 'deletion' (function call stopped with appropriate error message). Default is resioptions = c('variance').

• resi.store.levs: an integer vector indicating the levels at which the residual chains are to be stored (NULL by default). Non-NULL values not valid when EstM = 0 (i.e. (R)IGLS estimation), else if EstM = 0 and resi.store.levs non-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 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).

• x64: a logical value indicating whether the 64 bit version of MLwiN is used (unless MLwiNPath or options(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. If FALSE, the 32 bit version is called, if TRUE 64 bit version is called.

• clean.files: specifies whether the generated files are removed from the workdir (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 to FALSE.

• 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 <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.

• notation: specifies the model subscript notation to be used in the MLwiN equations window. 'class' means no multiple subscripts, whereas 'level' has multiple subscripts. If notation = 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. Specify optimat = TRUE if 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 situation runMLwiN'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.

• 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 = 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. Pertains to discrete response models estimated via IGLS: i.e. when EstM = 0 in estoptions, and for starting values when estimated via IGLS for MCMC (EstM = 1).

• 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). Pertains to models estimated via (R)IGLS: i.e. when EstM = 0 in estoptions, 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 element N defines 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. See demo(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: see fpsandwich and rpsandwich for new method of doing so. weighting is a list of objects including levels, weights, mode, FSDE and RSDE; see write.IGLS for details.

• centring: deprecated method (only applicable when using old syntax pre-R2MLwiN v.0.8-0) specifying function by which explanatory variables are to be centred (users can instead transform variables prior to runMLwiN call). If non-NULL, centring is used for the selected explanatory variables (centring = NULL by default). centring is a list of objects specifying the methods to be used to centre specific explanatory variables. E.g. list(age = 1, ...) specifies that the explanatory variable age is to be centred around its grand mean; list(age = c(2, 'district'), ...) specifies that age is to be centred around its group mean, where group defined by the variable district; and list(age = c(3, 18), ...) specifies that age is to be centred around the value 18.

• xclass: a deprecated option for specifying cross-classified and/or multiple membership models; see xc and mm for new method of doing so. xclass is a list of objects including class, N1, weight, id and car; see write.MCMC for details.

• mcmcOptions: a list of objects specifying MCMC options, including the following:

  • orth: If orth = 1, orthogonal fixed effect vectors are used; zero otherwise.

  • hcen: An integer specifying the level where we use hierarchical centering.

  • smcm: If smcm = 1, structured MCMC is used; zero otherwise.

  • smvn: If smvn = 1, the structured MVN framework is used; zero otherwise.

  • paex: A matrix of Nx2; in each row, if the second digit is 1, 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 is 0, 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.

• drop.data: If TRUE (default) only the data involved in the model is passed to MLwiN, otherwise the entire dataset in data is passed.

• drop.levels: If TRUE (default) any unused levels are dropped from factors, otherwise the dataset is left unchanged.

• fpsandwich: 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.

• rpsandwich: 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.

• smat: a matrix with two rows the levels at which a diagonal matrix is to be specified. The first row specifies the level. If the value of the second row is 1 then the random covariance matrix is set to be diagonal.

• maxiter: a numeric value specifying the maximum number of iterations, from the start, before (R)IGLS estimation halts. Pertains to models estimated via (R)IGLS: i.e. when EstM = 0 in estoptions, and for starting values when estimated via (R)IGLS for MCMC (EstM = 1).

• tol: a numeric value specifying the convergence criterion. If value 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. Pertains to models estimated via (R)IGLS: i.e. when EstM = 0 in estoptions, and for starting values when estimated via (R)IGLS for MCMC (EstM = 1).

• extra: if TRUE, extra binomial, extra negative binomial, extra Poisson or extra multinomial distributions assumed, else FALSE. can only be specified for discrete response models (i.e. 'Binomial', 'Negbinom', 'Poisson', 'Multinomial') estimated via (R)IGLS (i.e. EstM = 0).

• reset: a vector 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.

• constraints: fixed.ui and fixed.ci are used to specify constraints on the fixed coefficients, and random.ui and random.ci to specify constraints on the random parameters. The syntax for specifying just fixed parameter constraints is constraints = list(fixed.ui = <fixed matrix>, fixed.ci = <fixed values>), where <fixed matrix> is a matrix where each row represents one fixed part parameter, in the same order that they appear in the results table, each column represents one constraint, and the values in the matrix are multipliers for the parameters; and <fixed values> is a vector of values, one per constraint, to which the parameters multiplied by the multipliers in the corresponding column of <fixed matrix> should be equal. For example, if we have a model with formula y ~ 1 + x1 + x2 + x3 + x4 + (1|lev1ID), then constraints = list(fixed.ui = matrix(c(0, 1, -1, 0, 0, 0, 0, 0, 1, 2), nrow = 5), fixed.ci = c(0, 2)) specifies the constraints that the coefficient of x1 equals the coefficient of x2 and that the coefficient of x3 plus twice the coefficient of x4 equals 2. Random constraints are specified similarly, and fixed and random constraints may be applied simultaneously. Applies to EstM = 0 (i.e. estimation via (R)IGLS) only.

• xc: indicates whether model is cross-classified (TRUE) or nested (FALSE). Ignored if EstM = 0, i.e. only applicable to models estimated via MCMC. Defaults to xc = FALSE, unless either mm or car are non-NULL, in which case xc = TRUE. Supersedes deprecated xclass.

• 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 df2matrix). In the case of the former, each element of the list corresponds to a level (classification) of the model, in descending order. If a level is not a multiple membership classification, then NA is specified. Otherwise, lists need to be assigned to mmvar and weights, with the former containing columns specifying the classification units, and the latter containing columns specifying the weights. Ignored if EstM = 0, i.e. only applicable to models estimated via MCMC. mm = NULL by default. Supersedes deprecated xclass. E.g. (from demo(MCMCGuide16)) for logearn ~ 1 + age_40 + sex + parttime + (1 | company) + (1 | id), if company is a multiple membership classification with the variables indicating the classifications in company, company2, company3, company4 and their weights in weight1, weight2, weight3 and weight4 then mm = list(list(mmvar = list('company', 'company2', 'company3', 'company4'), weights = list('weight1', 'weight2', 'weight3', 'weight4')), NA) with the NA, listed last, corresponding to the level 1 identifier (id).

• car: specifies the structure of a conditional autoregressive (CAR) model. Can be a list of variable names, a list of vectors, or a matrix (e.g. see df2matrix). In the case of the former, 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 NA is specified. Otherwise, lists need to be assigned to carvar and weights, with the former containing columns specifying the spatial classification units, and the latter containing columns specifying the weights. See demo(MCMCGuide17) for examples. Ignored if EstM = 0, i.e. only applicable to models estimated via MCMC. car = NULL by default. Supersedes deprecated xclass. See demo(MCMCGuide17) for examples.

• carcentre: if CAR model (i.e. if car is non-NULL), carcentre = TRUE mean-centres all random effects at that level.

• startval: a list of numeric vectors specifying the starting values. If multiple chains requested (via nchains), then can be a list of such lists. 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. startval = NULL by default: i.e. when EstM = 0 the OLS estimates are used, else if EstM = 1 the estimates obtained from IGLS are used as the starting values for MCMC.

• sort.force: If TRUE will sort data based on hierarchy as determined by model formula; defaults to FALSE.

• sort.ignore: If FALSE will check data is sorted in a manner in keeping with the hierarchy implied by the model formula, and will return a warning if that is not the case.

• rng.version: An integer value specifing the random number generator version to be used by MLwiN. If 10 (the default) this will be the Mersenne Twister; If 0 this will be the 3-Seed Wichmann-Hill (default in MLwiN prior to version 3).

• mcmcMeth: list of objects specifying MCMC methodology and prior options, including the following (see write.MCMC for further details):

  • iterations: Number of main iterations post-burnin (i.e. monitoring chain length), defaults to 5000.

  • burnin: Length of burnin, defaults to 500.

  • nchains: Number of MCMC chains to run, defaults to 1.

  • thinning: Thinning factor, defaults to 1.

  • seed: MCMC random number seed, defaults to 1 when nchains = 1, and to 1:nchains when multiple chains requested.

  • priorParam: A list specifying informative priors. This includes: fixe – for the fixed parameters, if proper normal priors are used for some parameters, a list of vectors of length two is provided, each of which specifies the mean and the standard deviation. If not given, default ('flat' or 'diffuse') priors are used for the parameters; fixe.common – for multivariate normal, multinomial and mixed response models, if common coefficients are added, use fixe.common rather than fixe; fixe.sep – if the common coefficients are added, use fixe.sep for the separate coefficients; rp1 – a list object specifying the Wishart or gamma prior for the covariance matrix or scalar variance at level 1 (this consists of: (1) estimate – a prior guess for the true value of the covariance matrix; (2) size – sample size for guess. Note that this is a weakly-informative prior and the default prior is used if missing); rp2 – a list object specifying the Wishart or gamma prior for the covariance matrix or scalar variance at level 2 (this consists of: (1) estimate – an estimate for the true value of the inverse of the covariance matrix; (2) size – the number of rows in the covariance matrix. Note that this is a weakly-informative prior and the default prior is used if missing).

  • scale: Scale factor for proposal variances: this number will be multiplied by the estimated parameter variance (from IGLS/RIGLS) to give the proposal distribution variance. Defaults to 5.8.

  • refresh: Number of iterations after which screen (in MLwiN GUI) is to be refreshed. Defaults to 50.

  • fixM: Specifies the estimation method for the fixed effects: 1 for Gibbs sampling, 2 for univariate Metropolis-Hastings (MH) sampling and 3 for multivariate MH sampling. Defaults to 2 if Poisson, Multinomial, Binomial or Mixed model, else defaults to 1.

  • residM: Specifies the estimation method for the random effects (residuals): 1 for Gibbs sampling, 2 for univariate Metropolis-Hastings (MH) sampling and 3 for multivariate MH sampling. Defaults to 2 if Poisson, Multinomial, Binomial or Mixed model, else defaults to 1.

  • Lev1VarM: Specifies the estimation method for the level 1 variance: 1 for Gibbs sampling, 2 for univariate Metropolis-Hastings (MH) sampling and 3 for multivariate MH sampling. Defaults to 2 if Poisson, Multinomial, Binomial or Mixed model, else defaults to 1.

  • OtherVarM: Specifies the estimation method for the higher level variance matrices: 1 for Gibbs sampling, 2 for univariate Metropolis-Hastings (MH) sampling and 3 for multivariate MH sampling. Defaults to 1.

  • adaption: adaption = 1 (the default) indicates adaptation is to be used, adaption = 0 indicates it is not.

  • tol: An integer specifying tolerance (as a percentage; defaults to 10) when adaption = 1 (ignored if adaption = 0).

  • rate: An integer specifying the acceptance rate (as a percentage; defaults to 50) when adaption = 1 (ignored if adaption = 0).

  • priorcode: A vector indicating which default priors are to be used for the variance parameters. It defaults to c(gamma = 1) in which case Gamma priors are used with MLwiN's defaults of Gamma a value (shape) = 0.001 and Gamma b value (scale) = 0.001, although alternative values for shape and scale can be specified in subsequent elements of the vector, e.g. c(gamma = 1, shape = 0.5, scale = 0.2)). Alternatively c(uniform = 1) specifies Uniform priors on the variance scale. To allow for back-compatibility with deprecated syntax used in versions of R2MLwiN prior to 0.8-2, if priorcode is instead specified as an integer, then 1 indicates that Gamma priors are used, whereas 0 indicates that Uniform priors are used. See the section on 'Priors' in the MLwiN help system for more details on the meaning of these priors.

  • startval: Deprecated: starting values are now specified directly within estoptions.

  • lclo: Toggles on/off the possible forms of complex level 1 variation when using MCMC. By default (lclo = 0) the level 1 variation is expressed as a function of the predictors. Else (lclo = 1) the log of the level 1 precision (1/variance) is expressed as a function of the predictors. Defaults to lclo = 0.

  • dami: Outputs a complete (i.e. including non-missing responses) response variable y. If dami = c(0, <iter1>, <iter2>, ...) then the response variables returned will be the value of y at the iterations quoted (as integers <iter1>, <iter2>, etc.); these can be used for multiple imputation. If dami = 1 the value of y will be the mean estimate from the iterations produced. dami = 2 is as for dami = 1 but with the standard errors of the estimate additionally being stored. dami = NULL by default.

The argument BUGO is a vector specifying BUGS options as follows:

• n.chains: specifies the number of chains used by BUGS.

• debug: determines whether BUGS stays open following completion of the model run; debug = FALSE by default.

• seed: sets the random number generator in BUGS.

• bugs.directory: specifies the path where WinBUGS has been installed (not required if OpenBugs = TRUE).

• OpenBugs: if OpenBugs = TRUE, OpenBUGS is used. Otherwise (i.e. OpenBugs = FALSE, the default) WinBUGS is used.

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.

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

formula, Formula.translate, Formula.translate.compat, write.IGLS, write.MCMC

Examples

## The R2MLwiN package includes scripts to replicate all the analyses in
## Rasbash et al (2012) A User's Guide to MLwiN Version 2.26 and
## Browne, W.J. (2012) MCMC estimation in MLwiN Version 2.26.
## The MLwiN manuals are available online, see:
## http://www.bristol.ac.uk/cmm/software/mlwin/download/manuals.html

## Not run: 
library(R2MLwiN)
# NOTE: if MLwiN not saved in location R2MLwiN defaults to, specify path via:
# options(MLwiN_path = 'path/to/MLwiN vX.XX/')
# If using R2MLwiN via WINE, the path may look like this:
# options(MLwiN_path = '/home/USERNAME/.wine/drive_c/Program Files (x86)/MLwiN vX.XX/')

## For a list of demo titles
demo(package = 'R2MLwiN')

## Take MCMCGuide03 as an example
## To view file
file.show(system.file('demo', 'MCMCGuide03.R', package='R2MLwiN'))

## To run the demo
demo(MCMCGuide03)

## End(Not run)