write.IGLS: Writes MLwiN macros to fit models using the iterative...

In R2MLwiN: Running 'MLwiN' from Within R

Writes MLwiN macros to fit models using the iterative generalized least squares (IGLS) algorithm.

Description

write.IGLS is an internal function which creates an MLwiN macro file to fit a multilevel model using IGLS.

Usage

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
)

Arguments

indata	A data.frame object containing the data to be modelled.
dtafile	The name of the temporary file used to send the data to MLwiN, which is in Stata format (i.e. with extension .dta).
oldsyntax	Specified as FALSE if new syntax has been used in Formula object, else specified as TRUE (to enable back-compatibility).
resp	A character string (vector) of the response variable name(s).
levID	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).
expl	A character string (vector) of explanatory (predictor) variable name(s).
rp	A character string (vector) of random part of random variable name(s).
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 runMLwiN, Formula.translate, Formula.translate.compat. 'Mixed' combinations can consist of 'Normal' and 'Binomial' or 'Normal' and 'Poisson'.
nonlinear	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.
categ	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.
notation	Specifies the model subscript notation to be used in the MLwiN equations window. 'class' means no multiple subscripts, whereas 'level' has multiple subscripts.
nonfp	Removes the fixed part of random variable(s). NA if no variable to be removed.
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.
Meth	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).
extra	If TRUE, extra binomial, extra negative binomial, extra Poisson or extra multinomial distributions assumed, else FALSE.
reset	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.
rcon	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.
fcon	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.
maxiter	Numeric value specifying the maximum number of iterations, from the start, before estimation halts.
convtol	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.
mem.init	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.
optimat	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.
weighting	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.
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.
macrofile	A file name where the MLwiN macro file will be saved. The default location is in the temporary folder.
IGLSfile	A file name where the parameter estimates will be saved. The default location is in the temporary folder.
resifile	A file name where the residuals will be saved. The default location is in the temporary folder.
resi.store	A logical value to indicate if the residuals are to be stored (TRUE) or not (FALSE).
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'); 'variance' cannot be used together with the other options to calculate standardised, leverage, influence and deletion residuals.
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).
startval	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.
namemap	A mapping of column names to DTA friendly shorter names
saveworksheet	A file name used to store the MLwiN worksheet after the model has been estimated.
rng.version	An integer indicating which random number generator should be used by MLwiN.

Value

Outputs a modified version of namemap containing newly generated short names.

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

write.MCMC

R2MLwiN documentation built on March 31, 2023, 9:17 p.m.