Running MLwiN from within R

Description

R2MLwiN is an R command interface to the MLwiN multilevel modelling software package, allowing users to fit multilevel models using MLwiN (and also WinBUGS / OpenBUGS) from within the R environment.

New features in version 0.8-3

Support for model comparison tables via texreg-package and memisc-package have been added to R2MLwiN version 0.8-3. For an example of using texreg-package see e.g. demo(MCMCGuide04).

Important differences between version 0.8-0 and earlier versions

A number of wide-ranging changes, including a new model-fitting syntax more in keeping with that conventionally used in R, were introduced in R2MLwiN version 0.8-0.

The demos, which replicate both the User's Guide to MLwiN (Rasbash et al, 2012) and MCMC Estimation in MLwiN (Browne, 2012) manuals, provide practical demonstrations of many of these changes. See demo(package = "R2MLwiN") for a list of demo titles; to run one type e.g. demo(UserGuide03) or view a demo's script via file.show(system.file("demo", "UserGuide03", package = "R2MLwiN")).

• The Formula is now specified via a formula object (with some differences in specification: see runMLwiN). So, for example, previously a 2-level model random intercept model would be specified by e.g. normexam ~ (0|cons + standlrt) + (2|cons) + (1|cons), levID = c('school', 'student'), with normexam the response variable, cons a constant of ones forming the intercept, which is allowed to vary at level 1 (student) and level 2 (school), and standlrt included as a predictor in the fixed part of the model. Whilst back-compatibility is preserved (i.e. this specification will currently still work) the same model can now be more parsimoniously specified via normexam ~ 1 + standlrt + (1 | school) + (1 | student). As well examples in the demos, see runMLwiN and Formula.translate for further info.

• As a means of specifying cross-classified, multiple membership or CAR models, xclass is now deprecated. Instead, cross-classified models are specified via xc = TRUE, multiple membership models are specified via mm, and CAR models are specified via car, in the list of estoptions. mm and car can be a list of variable names, a list of vectors, or a matrix. See runMLwiN for further details.

• Multiple membership/CAR information can now be specified using matrices. df2matrix and matrix2df functions have also been added to convert such information between data.frame and matrix formats.

• As a means of specifying common (i.e. the same for each category) or separate (i.e. one for each category) coefficients in ordered multinomial and multivariate response models, c (for common) and s (for separate) have been replaced by the employment of square brackets after the relevant variable to indicate a common coefficient is to be fitted (a separate coefficient will be fitted otherwise). Within these square brackets needs to be placed a numeric identifier indicating the responses for which a common coefficient is to be added (see runMLwiN for further details). E.g. what would have been previously specified, within the Formula object, as ... (0s|cons + ravens) + (0c|fluent{1, 0}) ... would now be specified by ... 1 + ravens + fluent[1] ....

• When added as a predictor, a variable encoded as a factor is automatically handled as categorical, replacing the previous use of square brackets after the variable name.

• A number of generic s4 methods have been added to improve compatibility with statistical functions which use them (e.g. see stats4-package). So, for example, the addition of a logLik means a likelihood ratio test can now be conducted on two mlwinfitIGLS-class objects using the lrtest function, e.g. lrtest(mymodel1, mymodel2). See help(package = "R2MLwiN") for the index listing these various methods.

References

R2MLwiN

Zhang, Z., Parker, R.M.A., Charlton, C.M.J., Leckie, G. and Browne, W.J. (2016) R2MLwiN: A Package to Run MLwiN from within R. Journal of Statistical Software, 72(10), 1-43. doi:10.18637/jss.v072.i10

MLwiN software and manuals

Browne, W.J. (2012) MCMC Estimation in MLwiN, v2.26. Centre for Multilevel Modelling, University of Bristol.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Rasbash, J., Charlton, C. and Pillinger, R. (2012) Manual Supplement to MLwiN v2.26. Centre for Multilevel Modelling, University of Bristol.

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.

OpenBUGS

Thomas, A., O'Hara, B., Ligges, U. and Sturtz, S. (2006) Making BUGS Open. R News, 6, 12:17.

WinBUGS

Spiegelhalter, D.J., Thomas, A. and Best, N.G. (1999) WinBUGS Version 1.2 User Manual. MRC Biostatistics Unit.

Maintainer

Zhengzheng Zhang zhengzheng236@gmail.com

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.

See Also

Useful links:

• http://www.bristol.ac.uk/cmm/software/r2mlwin/

• https://r-forge.r-project.org/projects/r2mlwin/

• http://www.bristol.ac.uk/cmm/software/mlwin/

Examples

## 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/')

data(tutorial, package = "R2MLwiN")

(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
                     estoptions = list(EstM = 1), data = tutorial))

## 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

## 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)

Calculates Brooks-Draper diagnostic

Description

An internal function, for use in sixway, which calculates the Brooks-Draper diagnostic, based on an unpublished paper by David Draper. It estimates the length of a Markov chain required to produce a mean estimate to k significant figures with a given accuracy (alpha). See Browne (2012) for further details.

Usage

BD(est, var, rho, k = 2, alpha = 0.05)

Arguments

Value

The Brooks-Draper diagnostic statistic is returned.

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

Browne, W.J. (2012) MCMC Estimation in MLwiN, v2.26. Centre for Multilevel Modelling, University of Bristol.

See Also

sixway

An internal function to translate an R formula into an R list object.

Description

A model formula, as a formula object written in R-type syntax, is translated into an R list object.

Usage

Formula.translate(Formula, D = "Normal", indata)

Arguments

Value

Outputs an R list object, which is then used as the input for write.IGLS or write.MCMC.

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.

See Also

runMLwiN, write.IGLS, write.MCMC; for function allowing back-compatibility with Formula syntax used in older versions of R2MLwiN (<0.8.0) see Formula.translate.compat.

Examples

## Not run: 
# NB: See demo(packge = 'R2MLwiN') for a wider range of examples.
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/')

# Two-level random intercept model with student (level 1) nested within
# school (level 2) and standlrt added to the fixed part.
# Importantly, the ordering of school and student reflects their hierarchy,
# with the highest level (school) specified first.
# E.g. see demo(UserGuide04)
data(tutorial, package = 'R2MLwiN')
(mymodel1 <- runMLwiN(normexam ~ 1 + standlrt + (1 | school) + (1 | student),
                     data = tutorial))

# Adding a random slope
(mymodel2 <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school)
                     + (1 | student), data = tutorial))

# Exploring complex level 1 variation
# E.g. see demo(UserGuide07)
(mymodel3 <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school)
                      + (1 + standlrt | student), data = tutorial))

# Logit link with cons specified as denominator
# Note level 1 ID not explicitly specified
# E.g. see demo(UserGuide09)
data(bang, package = 'R2MLwiN')
(mymodel4 <- runMLwiN(logit(use, cons) ~ 1 + lc + age + (1 | district),
                      D = 'Binomial', data = bang))

# Mixed response model
# Note using MCMC estimation (EstM = 1)
# Normal (english) and Bernoulli (behaviour) distributed responses
# probit link modelling behaviour with cons as denominator
# E.g. see demo(MCMCGuide19)
data(jspmix1, package = 'R2MLwiN')
(mymodel <- runMLwiN(c(english, probit(behaviour, cons)) ~
                     1 + sex + ravens + fluent[1] + (1 | school) + (1[1] | id),
                     D = c('Mixed', 'Normal', 'Binomial'),
                     estoptions = list(EstM = 1,
                     mcmcMeth = list(fixM = 1, residM = 1, Lev1VarM = 1)),
                     data = jspmix1))

## End(Not run)

An internal function, allowing back-compatibility, which translates a model formula from a formula object or character string into an R list object.

Description

Supports Formula syntax as used in earlier (<0.8-0) versions of R2MLwiN. A model formula, as a formula object (or a character string) is translated into an R list object. Called by runMLwiN if oldsyntax = TRUE (when user specifies levID not NULL in runMLwiN function call). For corresponding function supporting new syntax, see Formula.translate.

Usage

Formula.translate.compat(Formula, levID, D = "Normal", indata)

Arguments

Details

If Formula is a character string, then the following syntax applies:

• ~ A tilde is used to separate response variable(s) and explanatory variable(s).

• () Round brackets are used to specify each random variable in the model together with its fixed/random part information.

• | Separates explanatory variable(s) (placed to the right of |) from the fixed/random part information (placed to the left of |) when placed within ().

• [] When placed immediately after an explanatory variable, indicates that the variable is categorical. The string in the [] represents the reference category; if empty, no reference category is used; See note.

• : Indicates an interaction term: i.e. the variables adjacent to :, and separated by it, are interacted with each other.

• 0 When placed to the left of | within () indicates that the variables to the right of | within the same () are to be added to the fixed part of the model.

• 1 When placed to the left of | within () indicates that the coefficients of the variables placed to the right of | within the same () are to be allowed to randomly vary at level 1 (and so on for 2 for level 2, 3 for level 3, etc.)

• 0s/0c When placed to the left of | within () indicates that separate (hence s) / common (hence c) coefficients for the variables to the right of | within the same () are to be added to the fixed part (hence 0) of multivariate normal, multinomial and mixed responses models.

• 2s/2c When placed to the left of | within () indicates that separate (hence s) / common (hence c) coefficients for the variables to the right of | within the same () are to be added to the random part of the model, and allowed to vary at level 2; applies to multivariate normal, multinomial and mixed responses models only.

• {} gives a vector of binary indicators specifying a common coefficient. 1 is to include the component at the corresponding positions; zero otherwise. These digits are separated by commas; applies to multivariate normal, multinomial and mixed responses models only.

• . Used for adding a separate coefficient for a particular component at a specific level; applies to multivariate normal, multinomial and mixed responses models only

If Formula is a formula object, 0s/0c, 2s/2c, .... and {} have to be replaced by `0s`/`0c`, `2s`/`2c`, .... and () respectively. Other syntax remains the same.

Value

Outputs an R list object, which is then used as the input for write.IGLS and/or write.MCMC.

Note

Note that some characters listed above have special meanings in the formula, so avoid using them when you name the random variable. Alphanumeric characters (i.e. [:alnum:]) are recommended for naming the random variable. They are also recommended for naming a reference category, inside []. Note: use [] notation only in the fixed part when there is no categorical variable in the random effects. If there is one in the random part, the categorical variable has to be converted into a set of binary variables (e.g., using Untoggle).

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.

See Also

runMLwiN, write.IGLS, write.MCMC, Formula.translate

Calculates the estimated Monte Carlo standard error (MCSE)

Description

An internal function which calculates the estimated Monte Carlo standard error (MCSE) for the posterior estimate of the mean, for use in sixway. As MCMC is a simulation-based approach this induces (Monte Carlo) uncertainty due to the random numbers it uses. This uncertainty reduces with more iterations, and is measured by the MCSE. See Browne (2012) for further details.

Usage

MCSE(chain, rho, ll = 0.5, ul = 20)

Arguments

Value

The Monte Carlo standard error (MCSE) for the posterior estimate of the mean is returned.

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

Browne, W.J. (2012) MCMC Estimation in MLwiN, v2.26. Centre for Multilevel Modelling, University of Bristol.

See Also

sixway

Converts a categorical variable into several separate binary variables

Description

This function converts a vector (factor) of categorical character strings (integers) into several separate vectors of binary indicators to enable back-compatibility with versions of R2MLwiN prior to 0.8-0.

Usage

Untoggle(categrv, name = NULL)

Arguments

Value

A matrix containing the generated dummy variables.

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.

Examples

## Not run: 
library(R2MLwiN)
# NOTE: Assumes MLwiN path is C:/Program Files (x86)/MLwiN v2.30/
# ...so please change relevant line if different
# if using R2MLwiN via WINE, the path may look like 
# options(MLwiN_path='/home/USERNAME/.wine/drive_c/Program Files (x86)/MLwiN v2.30/') 

# Example: tutorial
data(tutorial)
names(tutorial)
tutorial = cbind(tutorial, Untoggle(tutorial$school, 'school'))
names(tutorial)

## End(Not run)

Extract or Replace parts of "mlwinfitIGLS" objects

Description

Extract or Replace parts of "mlwinfitIGLS" objects

Usage

## S4 method for signature 'mlwinfitIGLS,ANY,ANY,ANY'
x[i, j, drop]

## S4 replacement method for signature 'mlwinfitIGLS,ANY,ANY,ANY'
x[i, j] <- value

## S4 method for signature 'mlwinfitIGLS'
x[[i, j, drop]]

## S4 replacement method for signature 'mlwinfitIGLS'
x[[i, j]] <- value

Arguments

Extract or Replace parts of "mlwinfitMCMC" objects

Description

Extract or Replace parts of "mlwinfitMCMC" objects

Usage

## S4 method for signature 'mlwinfitMCMC,ANY,ANY,ANY'
x[i, j, drop]

## S4 replacement method for signature 'mlwinfitMCMC,ANY,ANY,ANY'
x[i, j] <- value

## S4 method for signature 'mlwinfitMCMC'
x[[i, j, drop]]

## S4 replacement method for signature 'mlwinfitMCMC'
x[[i, j]] <- value

Arguments

Chemistry A-level results from one exam board

Description

Chemistry A-level results from one exam board; subset from Yang & Woodhouse, 2001. See also Rasbash et al. (2012) and Browne (2012).

Usage

alevchem

Format

A data frame with 2166 observations on the following 8 variables:

lea

Local Education Authority ID.

estab

Establishment (institution) ID.

pupil

Pupil ID.

a_point

A-level point score (an ordered factor with levels: F, E, D, C, B, A).

gcse_tot

Total GCSE point score.

gcse_no

Number of GCSEs taken.

cons

Constant of ones

gender

Pupil's gender (a factor with levels: male, female).

Details

The alevchem dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

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.

Yang, M., Woodhouse, G. (2001) Progress from GCSE to A and AS level: institutional and gender differences, and trends over time. British Educational Research Journal 27: 245-267.

Examples

## Not run: 

data(alevchem, package = "R2MLwiN")

alevchem$gcseav <- alevchem$gcse_tot/alevchem$gcse_no - 6

# Note: Establishment codes on their own do not uniquely identify schools.
# Schools are instead uniquely identified by LEA code, establishment ID
# combination. Thus, here we generated a unique school ID.

alevchem$school <- as.numeric(factor(paste0(alevchem$lea, alevchem$estab)))

(mymodel <- runMLwiN(logit(a_point, cons, 6) ~ 1 + gcseav[1:5] + I(gcseav^2)[1:5] +
  gender[1:5] + (1[1:5] + gcseav[1:5] | school), 
  D = "Ordered Multinomial", estoptions = list(EstM = 1), data = alevchem))


## End(Not run)

Augment data frame with information derived from the model fit (broom package).

Description

Augment data frame with information derived from the model fit (broom package).

Usage

## S3 method for class 'mlwinfitIGLS'
augment(x, data = x@frame, newdata = NULL, type.predict, type.residuals, ...)

Arguments

See Also

augment

Augment data frame with information derived from the model fit (broom package).

Description

Augment data frame with information derived from the model fit (broom package).

Usage

## S3 method for class 'mlwinfitMCMC'
augment(x, data = x@data, newdata = NULL, type.predict, type.residuals, ...)

Arguments

See Also

augment

Sub-sample from the 1989 Bangladesh Fertility Survey (see Huq & Cleveland, 1990)

Description

A subset of data from the 1989 Bangladesh Fertility Survey, consisting of 2867 women across 61 districts.

Usage

bang

Format

A data frame with 2867 observations on the following 12 variables:

woman

Identifying code for each woman (level 1 unit).

district

Identifying code for each district (level 2 unit).

use

Contraceptive use status at time of survey; a factor with levels Not_using and Using.

use4

Contraceptive use status and method (a factor with levels: Sterilization, Modern_reversible_method, Traditional_method, Not_using_contraception).

lc

Number of living children at time of survey; a factor with ordered levels None, One_child, Two_children, Three_plus.

age

Age of woman at time of survey (in years), centred on sample mean of 30 years.

urban

Type of region of residence; levels are Rural and Urban.

educ

Woman's level of education (a factor with ordered levels None, Lower_primary, Upper_primary, Secondary_and_above.

hindu

Woman's religion; levels are Muslim and Hindu.

d_lit

Proportion of women in district who are literate.

d_pray

Proportion of Muslim women in district who pray every day (a measure of religiosity).

cons

Constant of ones.

Details

The bang dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and is a subset of data from the 1989 Bangladesh Fertility Survey (Huq and Cleland, 1990) used by Rasbash et al. (2012) as an example when fitting logistic models for binary and binomial responses. The full sample was analysed in Amin et al. (1997).

Source

Amin, S., Diamond, I., Steele, F. (1997) Contraception and religiosity in Bangladesh. In: G. W. Jones, J. C. Caldwell, R. M. Douglas, R. M. D'Souza (eds) The Continuing Demographic Transition, 268–289. Oxford: Oxford University Press.

Huq, N. M., Cleland, J. (1990) Bangladesh fertility survey, 1989. Dhaka: National Institute of Population Research and Training (NIPORT).

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

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

See mlmRev package for an alternative format of the same dataset, with fewer variables.

Examples

## Not run: 

data(bang, package = "R2MLwiN")

bang$use4 <- relevel(bang$use4, 4)

# Change contrasts if wish to avoid warning indicating that, by default,
# specified contrasts for ordered predictors will be ignored by runMLwiN
# (they will be fitted as "contr.treatment" regardless of this setting). To
# enable specified contrasts, set allowcontrast to TRUE (this will be the
# default in future package releases).
my_contrasts <- options("contrasts")$contrasts
options(contrasts = c(unordered = "contr.treatment",
                      ordered = "contr.treatment"))

# As an alternative to changing contrasts, can instead use C() to specify
# contrasts for ordered predictors in formula object, e.g.:

# F1 <- log(use4, cons) ~ 1 + C(lc, "contr.treatment") + (1 | district)

# (mymodel <- runMLwiN(Formula = F1, 
#                      D = "Unordered Multinomial",
#                      estoptions = list(EstM = 1, nonlinear = c(1, 2)),
#                      data = bang,
#                      allowcontrast = TRUE))

F1 <- log(use4, cons) ~ 1 + lc + (1 | district)

(mymodel <- runMLwiN(Formula = F1, 
                     D = "Unordered Multinomial",
                     estoptions = list(EstM = 1, nonlinear = c(1, 2)),
                     data = bang))

# Change contrasts back to pre-existing:
options(contrasts = my_contrasts)


## End(Not run)

Sub-sample from the 1989 Bangladesh Fertility Survey

Description

A subset of data from the 1989 Bangladesh Fertility Survey, consisting of 1934 women across 60 districts.

Usage

bang1

Format

A data frame with 1934 observations on the following 11 variables:

woman

Identifying code for each woman (level 1 unit).

district

Identifying code for each district (level 2 unit).

use

Contraceptive use status at time of survey; a factor with levels Not_using and Using.

lc

Number of living children at time of survey; an ordered factor with levels None, One_child, Two_children, Three_plus.

age

Age of woman at time of survey (in years), centred on sample mean of 30 years.

urban

Type of region of residence; a factor with levels Rural and Urban.

educ

Woman's level of education; an ordered factor with levels None, Lower_primary, Upper_primary, Secondary_and_above.

hindu

Woman's religion; a factor with levels Muslim and Hindu.

d_illit

Proportion of women in district who are literate.

d_pray

Proportion of Muslim women in district who pray every day (a measure of religiosity).

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

Details

The bang1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and is a subset of data from the 1989 Bangladesh Fertility Survey (Huq and Cleland, 1990) used by Browne (2012) as an example when fitting logistic models for binary and binomial responses. The full sample was analysed in Amin et al. (1997).

Source

Amin, S., Diamond, I., Steele, F. (1997) Contraception and religiosity in Bangladesh. In: G. W. Jones, J. C. Caldwell, R. M. Douglas, R. M. D'Souza (eds) The Continuing Demographic Transition, 268–289. Oxford: Oxford University Press.

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Huq, N. M., Cleland, J. (1990) Bangladesh fertility survey, 1989. Dhaka: National Institute of Population Research and Training (NIPORT).

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

See Also

See mlmRev package for an alternative format of the same dataset, with fewer variables.

Examples

## Not run: 

data(bang1, package = "R2MLwiN")

bang1$denomb <- 1

# Change contrasts if wish to avoid warning indicating that, by default,
# specified contrasts for ordered predictors will be ignored by runMLwiN
# (they will be fitted as "contr.treatment" regardless of this setting). To
# enable specified contrasts, set allowcontrast to TRUE (this will be the
# default in future package releases).
my_contrasts <- options("contrasts")$contrasts
options(contrasts = c(unordered = "contr.treatment",
                      ordered = "contr.treatment"))

# As an alternative to changing contrasts, can instead use C() to specify
# contrasts for ordered predictors in formula object, e.g.:

# F1 <- logit(use, denomb) ~ 1 + age + C(lc, "contr.treatment") + urban +
#   (1 + urban | district)

# (mymodel <- runMLwiN(Formula = F1,
#                      D = "Binomial",
#                      estoptions = list(EstM = 1),
#                      data = bang1,
#                      allowcontrast = TRUE))

F1 <- logit(use, denomb) ~ 1 + age + lc + urban + (1 + urban | district)

(mymodel <- runMLwiN(Formula = F1,
                     D = "Binomial",
                     estoptions = list(EstM = 1),
                     data = bang1))

# Change contrasts back to pre-existing:
options(contrasts = my_contrasts)


## End(Not run)

Subsample from British Election Study, '83.

Description

Subsample from British Election Study, consisting of 800 voters across 110 areas.

Usage

bes83

Format

A data frame with 800 observations on the following 10 variables:

voter

Voter identifier.

area

Identifier for voters' constituencies.

defence

Score on a 21 point scale of attitudes towards nuclear weapons with low scores indicating disapproval of Britain possessing them. This variable is centred about its mean.

unemp

Score on a 21 point scale of attitudes towards unemployment with low scores indicating strong opposition and higher scores indicating a preference for greater unemployment if it results in lower inflation. This variable is centred about its mean.

taxes

Score on a 21 point scale of attitudes towards tax cuts with low scores indicating a preference for higher taxes to pay for more government spending. This variable is centred about its mean.

privat

Score on a 21 point scale of attitudes towards privatization of public services with low scores indicating opposition. This variable is centred about its mean.

votecons

If respondent voted Conservative; a factor with levels Other and Voted_Conservative.

cons

This variable is constant (= 1) for all voters.

denom

This variable is constant (= 1) for all voters.

Details

The bes83 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009). See Heath et al (1996), and also Rasbash et al (2012) and Browne (2012).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Heath, A., Yang, M., Goldstein, H. (1996). Multilevel analysis of the changing relationship between class and party in Britain 1964-1992. Quality and Quantity, 30:389-404.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

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.

Examples

## Not run: 

data(bes83, package = "R2MLwiN")

(mymodel <- runMLwiN(logit(votecons, cons) ~ 1 + defence + unemp + taxes + privat + (1 | area),
  D = "Binomial", estoptions = list(EstM = 1), data = bes83))


## End(Not run)

Draws a caterpillar plot (in MLwiN style).

Description

A convenient wrapper for the plot function with the addition of error bars, e.g. to create caterpillar plots.

Usage

caterpillar(
  y,
  x,
  qtlow,
  qtup,
  xlab = "",
  ylab = "",
  xlim = NULL,
  ylim = NULL,
  main = ""
)

Arguments

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, U.K.

See Also

caterpillarR

Examples

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

# Example using tutorial dataset
data(tutorial, package = 'R2MLwiN')
(mymodel <- runMLwiN(normexam ~ 1 + (1 | school) + (1 | student),
                     estoptions = list(resi.store = TRUE),
                     data = tutorial))

# For each school, calculate the CIs...
residuals <- mymodel@residual$lev_2_resi_est_Intercept
residualsCI <- 1.96 * sqrt(mymodel@residual$lev_2_resi_var_Intercept)
residualsRank <- rank(residuals)
rankno <- order(residualsRank)

caterpillar(y = residuals[rankno], x = 1:65, qtlow = (residuals - residualsCI)[rankno],
           qtup = (residuals + residualsCI)[rankno], xlab = 'Rank', ylab = 'Intercept')

## End(Not run)

Draws caterpillar plots of the residuals from a mlwinfitIGLS-class or mlwinfitMCMC-class object, at a chosen level of the multilevel model.

Description

Uses qqmath in the lattice package to draw Quantile-Quantile plots of the residuals at a chosen level of a multilevel model against a theoretical distribution.

Usage

caterpillarR(resi, lev = 2)

Arguments

Value

See qqmath.

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.

See Also

caterpillar, qqmath

Examples

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

# Example using tutorial dataset
data(tutorial, package = 'R2MLwiN')
mymodel <- runMLwiN(normexam ~ 1 + (1 | school) + (1 | student),
                    estoptions = list(resi.store = TRUE),
                    data = tutorial)
# Caterpillar plot
caterpillarR(mymodel['residual'], lev = 2)

## End(Not run)

Extract the coefficient vector from "mlwinfitIGLS" objects

Description

Extract the coefficient vector from "mlwinfitIGLS" objects

Usage

## S4 method for signature 'mlwinfitIGLS'
coef(object, ...)

Arguments

See Also

coef-methods

Extract the coefficient vector from "mlwinfitMCMC" objects

Description

Extract the coefficient vector from "mlwinfitMCMC" objects

Usage

## S4 method for signature 'mlwinfitMCMC'
coef(object, ...)

Arguments

See Also

coef-methods

Extract the coefficient vector from "mlwinfitIGLS" objects

Description

Extract the coefficient vector from "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
coef(object, ...)

Arguments

See Also

coef

Extract the coefficient vector from "mlwinfitMCMC" objects

Description

Extract the coefficient vector from "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
coef(object, ...)

Arguments

See Also

coef

Data from the 1998 Scottish Health Survey on cardiovascular disease status of 8804 respondents

Description

Data from the 1998 Scottish Health Survey, with 8804 respondents aged between 18 and 64. The outcome, cvddef, is a self-report of a doctor-diagnosed cardiovascular disease (CVD) condition (angina, diabetes, hypertension, acute myocardial infarction, etc.). This is a binary response, whether (1) or not (0) respondents have CVD condition.

Usage

cvd

Format

A data frame with 8804 observations on the following 9 variables:

age

Age.

sex

Gender (factor with levels: male, female).

sc

Social class (factor with levels: 12 (social class 1 and 2), 3 (social class 3), 45 (social class 4 and 5)).

cvddef

Self-reported cardiovascular disease (0 = does not have condition, 1 = has condition)

carstair

Carstairs score.

smoke

Smoking frequency (factor with levels: lite (<10 a day), mod (10-19 a day), hvy (20+ a day), ex (ex-smoker), nevr (never smoked)).

id

Respondent identifier.

area

Postcode sector

Details

The cvd dataset is one of the example datasets analysed in Leyland and Groenewegen (2020), and provided with the multilevel-modelling software package MLwiN (Charlton et al., 2024), as cvd_data.

Source

Charlton, C., Rasbash, J., Browne, W.J., Healy, M. and Cameron, B. (2024) MLwiN Version 3.09 Centre for Multilevel Modelling, University of Bristol.

Leyland A.H. (2005) Socioeconomic gradients in the prevalence of cardiovascular disease in Scotland: the roles of composition and context. J Epidemiol Community Health 59:799–803

Leyland, A.H., Groenewegen, P.P. (2020). Untangling Context and Composition. In: Multilevel Modelling for Public Health and Health Services Research. Springer, Cham. doi:10.1007/978-3-030-34801-4_13

Examples

## Not run: 

data(cvd, package = "R2MLwiN")

# Example taken from Leyland and Groenewegen (2020)

F1 <- logit(cvddef) ~ 1 + I(age^3) + I(age^3):I(log(age)) +
  sex + sex:I(age^3) + sex:I(age^3):I(log(age)) +
  (1 | area)

(mod_MQL1 <- runMLwiN(Formula = F1,
                      D = "Binomial",
                      data = cvd))

(mod_PQL2 <- runMLwiN(Formula = F1,
                      D = "Binomial",
                      data = cvd,
                      estoptions = list(
                        nonlinear = c(N = 1, M = 2),
                        startval = list(FP.b = mod_MQL1@FP,
                                        FP.v = mod_MQL1@FP.cov,
                                        RP.b = mod_MQL1@RP,
                                        RP.v = mod_MQL1@RP.cov))))

## End(Not run)

Returns the deviance from "mlwinfitIGLS" objects.

Description

Returns the deviance from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
deviance(object, ...)

Arguments

See Also

deviance

Returns the residual degrees-of-freedom extracted from "mlwinfitIGLS" objects.

Description

Returns the residual degrees-of-freedom extracted from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
df.residual(object, ...)

Arguments

See Also

nobs, coef

Translates a data.frame, formatted for use in multiple membership modelling in MLwiN, to a matrix.

Description

Translates a data.frame, in a form usable by MLwiN for multiple membership models, into a matrix. The data.frame needs to contain (a) columns with membership IDs (e.g. first row of which might be 2, 3, 5, 6, 0, 0) and (b) columns containing weights (e.g. first row of which might be 0.25, 0.25, 0.25, 0.25, 0, 0; in this example the first row of resulting matrix would be 0, 1, 1, 0, 1, 1).

Usage

df2matrix(data, idcols, weightcols)

Arguments

Value

An adjacency matrix as returned by sparseMatrix.

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, U.K.

See Also

matrix2df

Examination dataset

Description

Examination data for 907 students within 18 schools.

Usage

diag1

Format

A data frame with 907 observations on the following 9 variables:

school

School identifier.

sex

Pupil gender.

vrq

Verbal Reasoning quotient.

ilea

O-level/CSE examination results.

type

School type: a factor with levels Comprehensive and Grammar.

pupil

Pupil identifier.

cons

Constant (=1).

n_ilea

O-level/CSE examination results (normal scores).

n_vrq

Verbal Reasoning quotient (normal scores).

Details

The diag1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), originally analysed in Aitkin & Longford (1986), and described further in Rasbash et al. (2012).

Source

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Rasbash, J., Steele, F., Browne, W.J., Goldstein, H. (2012) A User's Guide to MLwiN v2.26. University of Bristol: Centre for Multilevel Modelling.

Aitkin, M. & Longford, N. (1986). Statistical modelling in school effectiveness studies (with discussion). Journal of the Royal Statistical Society, Series A, 149:1-43.

Examples

## Not run: 

data(diag1, package = "R2MLwiN")

(mymodel <- runMLwiN(n_ilea ~ 1 + n_vrq + (1 + n_vrq | school) + (1 | pupil),
  estoptions = list(resi.store = TRUE, resioptions = c("standardised",
  "leverage", "influence", "deletion")), data = diag1))


## End(Not run)

Converts numerical values from double precision to single precision.

Description

This function converts numeric column(s) of a data frame object, matrix or vector from double precision to single precision, e.g. to avoid a warning from MLwiN which currently only stores data in single precision.

Usage

double2singlePrecision(x)

Arguments

Value

An object of numerical values in single precision will be returned.

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.

Extract coefficients and GOF measures from a statistical object (texreg package).

Description

Extract coefficients and GOF measures from a statistical object (texreg package).

Usage

## S4 method for signature 'mlwinfitIGLS'
extract(
  model,
  include.nobs = TRUE,
  include.loglik = TRUE,
  include.deviance = TRUE,
  ...
)

Arguments

See Also

extract

Extract coefficients and GOF measures from a statistical object.

Description

Extract coefficients and GOF measures from a statistical object.

Usage

## S4 method for signature 'mlwinfitMCMC'
extract(
  model,
  include.nobs = TRUE,
  include.dbar = TRUE,
  include.dthetabar = TRUE,
  include.pd = TRUE,
  include.dic = TRUE,
  ...
)

Arguments

See Also

extract

Returns the fitted values from "mlwinfitIGLS" objects.

Description

Returns the fitted values from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
fitted(object, ...)

Arguments

See Also

fitted.values

Returns the fitted values from "mlwinfitMCMC" objects.

Description

Returns the fitted values from "mlwinfitMCMC" objects.

Usage

## S3 method for class 'mlwinfitMCMC'
fitted(object, ...)

Arguments

See Also

fitted.values

"mlwinfitIGLS" model formula

Description

"mlwinfitIGLS" model formula

Usage

## S3 method for class 'mlwinfitIGLS'
formula(x, env = parent.frame(), ...)

Arguments

"mlwinfitMCMC" model formula

Description

"mlwinfitMCMC" model formula

Usage

## S3 method for class 'mlwinfitMCMC'
formula(x, env = parent.frame(), ...)

Arguments

Data on physiotherapy referrals from 100 general practices in the Netherlands, collected in 1987

Description

These data were collected in 1987 as part of a large national survey of general practice (Van der Velden 1999).

Usage

fysio

Format

A data frame with 16700 observations on the following 14 variables:

gpid

GP identifier.

patid

Patient identifier.

patage

Patient age in years.

pagegrp

Patient age group, with ages grouped into 7 categories (ordered factor with levels page<35, 35<=page<45, 45<=page<55, 55<=page<65, 65<=page<75, 75<=page<85, 85<=page).

patsex

Patient gender (factor with levels female, male).

patinsur

Patient insurance indicator (factor with levels privateins (privately insured), publicins (publically insured)).

patedu

Patient education level (ordered factor with levels none (no formal education), primary (primary education), secondary (secondary and lower/middle vocational education), higher (higher vocational and university education)).

diag

Primary diagnosis resulting from care episodes (factor with levels 1 (symptoms/complaints neck), 2 (symptoms/complaints back), 3 (myalgia/fibrositis), 4 (symptoms of multiple muscles), 5 (disabilities related to the locomotive system), 6 (impediments of the cervical spine), 7 (arthrosis cervical spine), 8 (lumbago), 9 (ischialgia), 10 (hernia nuclei pulposi), 11 (impediments of the shoulder), 12 (epicondylitis lateralis), 13 (tendinitis/synovitis)).

gpexper

GP experience (number of years working as a GP divided by ten).

gpworkload

GP workload (number of contacts in the 3-month registration period divided by 1000).

practype

Practice type (factor with levels solo, duo, group, healthcentre).

location

Practice location (factor with levels rural, suburban, urban, bigcity).

gpphysifr

Indicator of whether the GP has physiotherapists in their social network (factor with levels no, yes).

referral

Indicator of whether the patient was referred to a physiotherapist (factor with levels no, yes).

Details

The fysio dataset is one of the example datasets analysed in Leyland and Groenewegen (2020), and provided with the multilevel-modelling software package MLwiN (Charlton et al., 2024).

Source

Charlton, C., Rasbash, J., Browne, W.J., Healy, M. and Cameron, B. (2024) MLwiN Version 3.08 Centre for Multilevel Modelling, University of Bristol.

Leyland, A.H., Groenewegen, P.P. (2020). Multilevel Logistic Regression Using MLwiN: Referrals to Physiotherapy. In: Multilevel Modelling for Public Health and Health Services Research. Springer, Cham. doi:10.1007/978-3-030-34801-4_12

Van der Velden, K. (1999). General practice at work: its contribution to epidemiology and health policy. NIVEL, PhD thesis Erasmus University, Utrecht

Examples

## Not run: 

data(fysio, package = "R2MLwiN")

# Example taken from Leyland and Groenewegen (2020)

# Change contrasts if wish to avoid warning indicating that, by default,
# specified contrasts for ordered predictors will be ignored by runMLwiN
# (they will be fitted as "contr.treatment" regardless of this setting). To
# enable specified contrasts, set allowcontrast to TRUE (this will be the
# default in future package releases).
my_contrasts <- options("contrasts")$contrasts
options(contrasts = c(unordered = "contr.treatment",
                      ordered = "contr.treatment"))

# As an alternative to changing contrasts, can instead use C() to specify
# contrasts for ordered predictors in formula object, e.g.:

# F1 <- logit(referral) ~ 1 + C(pagegrp, "contr.treatment") + patsex + diag +
#   C(patedu, "contr.treatment") + patinsur + gpexper + gpworkload +
#   practype + location + gpphysifr +
#   (1 | gpid)
# 
# (mod_MQL1 <- runMLwiN(Formula = F1,
#                       D = "Binomial",
#                       data = fysio,
#                       allowcontrast = TRUE))

F1 <- logit(referral) ~ 1 + pagegrp + patsex + diag +
  patedu + patinsur + gpexper + gpworkload +
  practype + location + gpphysifr +
  (1 | gpid)

(mod_MQL1 <- runMLwiN(Formula = F1,
                      D = "Binomial",
                      data = fysio))

(mod_PQL2 <- runMLwiN(Formula = F1,
                      estoptions = list(nonlinear = c(N = 1, M = 2),
                                        startval = list(FP.b = mod_MQL1@FP,
                                                        FP.v = mod_MQL1@FP.cov,
                                                        RP.b = mod_MQL1@RP,
                                                        RP.v = mod_MQL1@RP.cov)),
                      D = "Binomial",
                      data = fysio))
                      
# Change contrasts back to pre-existing:
options(contrasts = my_contrasts)

## End(Not run)

Pupils' marks from GCSE exams (UK, 1989); complete cases only.

Description

Pupils' marks from GCSE exams, consisting of 1523 pupils across 73 schools. See Browne (2012) for further details.

Usage

gcsecomp1

Format

A data frame with 1523 observations on the following 6 variables:

school

Identifying code for each school (level 2 unit).

student

Identifying code for each pupil (level 1 unit).

female

Gender of pupil: a factor with levels Male and Female.

written

Exam score.

csework

Coursework score.

cons

Constant (=1).

Details

The gcsecomp1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(gcsecomp1, package="R2MLwiN")

(mymodel <- runMLwiN(c(written, csework) ~ 1 + female + (1 | school) + (1 | student), 
  D = "Multivariate Normal", estoptions = list(EstM = 1), data = gcsecomp1))


## End(Not run)

Pupils' marks from GCSE exams (UK, 1989).

Description

GCSE exam results, taken from 73 schools in England, consisting of 1905 pupils.

Usage

gcsemv1

Format

A data frame with 1905 observations on the following variables:

school

School identification (level 2 unit).

student

Student identification (level 1 unit).

female

Gender: a factor with levels Female and Male.

agemths

Age in months.

written

Score on the written component.

csework

Score on the coursework component.

cons

Constant (= 1).

Details

The gcsemv1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009); for further details see Rasbash et al. (2012).

Source

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

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

See mlmRev package for an alternative format of the same dataset, with fewer variables.

Examples

## Not run: 

data(gcsemv1, package = "R2MLwiN")

(mymodel <- runMLwiN(c(written, csework) ~ 1 + female + (1 | school) + (1 | student), 
  D = "Multivariate Normal", estoptions = list(EstM = 1), data = gcsemv1))


## End(Not run)

Extract coefficients and GOF measures from a statistical object (memisc package).

Description

Extract coefficients and GOF measures from a statistical object (memisc package).

Usage

## S3 method for class 'mlwinfitIGLS'
getSummary(obj, alpha = 0.05, ...)

Arguments

See Also

getSummary

Extract coefficients and GOF measures from a statistical object (memisc package).

Description

Extract coefficients and GOF measures from a statistical object (memisc package).

Usage

## S3 method for class 'mlwinfitMCMC'
getSummary(obj, alpha = 0.05, ...)

Arguments

See Also

getSummary

Extract GOF measures from a statistical object (broom package).

Description

Extract GOF measures from a statistical object (broom package).

Usage

## S3 method for class 'mlwinfitIGLS'
glance(x, ...)

Arguments

See Also

glance

Extract GOF measures from a statistical object (broom package).

Description

Extract GOF measures from a statistical object (broom package).

Usage

## S3 method for class 'mlwinfitMCMC'
glance(x, ...)

Arguments

See Also

glance

Height data.

Description

Height data for 100 adult males.

Usage

height

Format

A data frame with 100 observations on the following variable:

height

Heights of 100 adult males measured in centimetres.

Details

The height dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009); see Rasbash et al. (2012) for further details.

Source

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol. 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.

Examples

## Not run: 
# from demo(UserGuide16)

data(height, package = "R2MLwiN")
summary(height)

hist(height$height)

1 - pnorm((200 - mean(height$height)) / sd(height$height))

heightsim1 <- function() {
  heightsim <- 175.35 + 10.002 * qnorm(runif(100))
  c(pmean = mean(heightsim), pvar = var(heightsim))
}

set.seed(1)

# Note: To obtain estimates as close as possible to the MLwiN manual,
# increase the number of reps to 10000.

simdata1 <- as.data.frame(t(replicate(1000, heightsim1())))
simdata1$iteration <- 1:nrow(simdata1)

plot(simdata1$iteration, simdata1$pmean, type = "l")

plot(density(simdata1$pmean))

quantile(simdata1$pmean, c(0.025, 0.975))

plot(simdata1$iteration, simdata1$pvar, type = "l")

plot(density(simdata1$pvar))

quantile(simdata1$pvar, c(0.025, 0.975))

heightsim2 <- function(variable) {
  samp <- sample(variable, replace = TRUE)
  c(npmean = mean(samp), npvar = var(samp))
}

simdata2 <- as.data.frame(t(replicate(1000, heightsim2(height$height))))
simdata2$iteration <- 1:nrow(simdata2)

plot(simdata2$iteration, simdata2$npmean, type = "l")

plot(density(simdata2$npmean))

quantile(simdata2$npmean, c(0.025, 0.975))

plot(simdata2$iteration, simdata2$npvar, type = "l")

plot(density(simdata2$npvar))

quantile(simdata2$npvar, c(0.025, 0.975))

## End(Not run)

Hungarian component of 2nd International Science Survey, '84; see Goldstein 2003

Description

Hungarian component of 2nd International Science Survey, consisting of 2439 women across 99 districts.

Usage

hungary1

Format

A data frame with 2439 observations on the following 10 variables:

school

Identifying code for each school (level 2 unit).

female

Gender indicator: a factor with levels Male and Female.

es_core

Core Earth Sciences test result.

biol_core

Core Biology test result.

biol_r3

Optional Biology test result.

biol_r4

Optional Biology test result.

phys_core

Core Physics test result.

phys_r2

Optional Physics test result.

cons

Constant(=1).

student

Identifying code for each student (level 1 unit).

Details

The hungary1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009). Originally analysed in Goldstein (2003), further details can also be found in Browne (2012).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Goldstein, H.. (2003) Multilevel Statistical Models. Third Edition. London, Edward Arnold.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(hungary1, package = "R2MLwiN")

(mymodel <- runMLwiN(c(es_core, biol_core, biol_r3, biol_r4, phys_core, phys_r2) ~ 
  1 + female + (1 | school) + (1 | student),
  D = "Multivariate Normal", estoptions = list(EstM = 1), data = hungary1))


## End(Not run)

Dataset of pupils' test scores, a subset of the Junior School Project.

Description

An educational dataset of pupils' test scores, a subset of the Junior School Project (Mortimore et al., 1988).

Usage

jspmix1

Format

A data frame with 1119 observations on the following 8 variables:

school

School identifying code.

id

Pupil identifying code.

sex

Sex of pupil; a factor with levels female and male.

fluent

Fluency in English indicator, where 0 = beginner, 1 = intermediate, 2 = fully fluent; measured in Year 1.

ravens

Test score, out of 40; measured in Year 1.

english

Pupils' English test score, out of 100; measured in Year 3.

behaviour

Pupils' behaviour score, where lowerquarter = pupil rated in bottom 25%, and upper otherwise; measured in Year 3.

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

Details

A subset of the Junior School Project (Mortimore et al., 1988), the jspmix1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and is used in Browne (2012) as an example of modelling mixed responses. It consists of test scores for 1119 pupils across 47 schools. Note that the behaviour variable originally had three categories, and the middle 50% and top 25% have been combined to produce a binary variable.)

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Mortimore, P., Sammons, P., Stoll, L., Lewis, D., Ecob, R. (1988) School Matters. Wells: Open Books.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(jspmix1, package = "R2MLwiN")

jspmix1$denomb <- jspmix1$cons

(mymodel <- runMLwiN(c(english, probit(behaviour, denomb)) ~ 
  1 + sex + ravens + fluent[1] + (1 | school) + (1[1] | id), 
  D = c("Mixed", "Normal", "Binomial"), 
  estoptions = list(EstM = 1, mcmcMeth = list(fixM = 1, residM = 1, Lev1VarM = 1)), 
  data = jspmix1))


## End(Not run)

Lips data

Description

Observed counts of male lip cancer for the 56 regions of Scotland over the period 1975-1980.

Usage

lips1

Format

A data frame with 56 observations on the following 41 variables:

area

Region ID.

cons

Constant (=1).

obs

Observed cases of lip cancer.

exp

Expected count.

perc_aff

Percentage of the region who work in agriculture, fishing and forestry.

offs

Log of the expected count.

pcons

Constant (=1).

denom

Constant (=1).

neigh1

First neighbours.

neigh2

Second neighbours.

neigh3

Third neighbours.

neigh4

Fourth neighbours.

neigh5

Fifth neighbours.

neigh6

Sixth neighbours.

neigh7

Seventh neighbours.

neigh8

Eighth neighbours.

neigh9

Ninth neighbours.

neigh10

Tenth neightbours.

neigh11

Eleventh neightbours.

weight1

First neighbours' weights.

weight2

Second neighbours' weights.

weight3

Third neighbours' weights.

weight4

Fourth neighbours' weights.

weight5

Fifth neighbours' weights.

weight6

Sixth neighbours' weights.

weight7

Seventh neighbours' weights.

weight8

Eighth neighbours' weights.

weight9

Ninth neighbours' weights.

weight10

Tenth neightbours' weights.

weight11

Eleventh neightbours' weights.

wcar1

First neighbours' CAR weights.

wcar2

Second neighbours' CAR weights.

wcar3

Third neighbours' CAR weights.

wcar4

Fourth neighbours' CAR weights.

wcar5

Fifth neighbours' CAR weights.

wcar6

Sixth neighbours' CAR weights.

wcar7

Seventh neighbours' CAR weights.

wcar8

Eighth neighbours' CAR weights.

wcar9

Ninth neighbours' CAR weights.

wcar10

Tenth neightbours' CAR weights.

wcar11

Eleventh neightbours' CAR weights.

Details

The lips1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and was analysed in Clayton & Kaldor (1987); see also Browne (2012) for more details.

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Clayton, D., Kaldor, J. (1987) Empirical Bayes estimates of age-standardized relative risks for use in disease mapping. Biometrics 43: 671-681.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(lips1, package = "R2MLwiN")

(mymodel <- runMLwiN(log(obs) ~ 1 + perc_aff + offset(offs) + (0 | neigh1) + (1 | area),
 D = "Poisson", estoptions = list(EstM = 1), data = lips1))


## End(Not run)

Details of deaths from all causes in England and Wales 1972-1992, taken from the local mortality datapack

Description

This dataset records the annual number of deaths in a given district in England and Wales, covering 14 years (1972-1992) across 403 districts. Note that there are only 5639 observations rather than the 5642 that might be expected (403 districts with an observation for each of 14 years); 3 data points were removed because extreme outlying values made them implausible.

Usage

lmdp

Format

A data frame with 5639 observations on the following 8 variables:

county

County (within region) identifier. There are 54 counties, coded from 1 to 68.

district

District (within county) identifier. There are 403 districts, coded 101 to 6820.

region

Region identifier. There are 10 regions, coded 1 to 10.

year

Year, 1979 (79) to 1992 (92).

deaths

Number of deaths observed

expected

Expected number of deaths, based on the 1992 national age- and sex- specific mortality rates.

smr

Standardised mortality ratio (observed deaths / expected deaths * 100).

family

District classification into one of 6 groups as defined by the UK's Office for National Statistics (factor with levels Inner_London (Inner London), Rural (Rural areas), Prospering (Prospering areas) Maturer (Maturer areas), Urban (Urban areas), Mining_industrial (Mining and industrial areas).

Details

The lmdp dataset is one of the example datasets analysed in Leyland and Groenewegen (2020), and provided with the multilevel-modelling software package MLwiN (Charlton et al., 2024).

Source

Charlton, C., Rasbash, J., Browne, W.J., Healy, M. and Cameron, B. (2024) MLwiN Version 3.08 Centre for Multilevel Modelling, University of Bristol.

Leyland, A.H., Groenewegen, P.P. (2020). Multilevel Linear Regression Using MLwiN: Mortality in England and Wales, 1979-1992. In: Multilevel Modelling for Public Health and Health Services Research. Springer, Cham. doi:10.1007/978-3-030-34801-4_11

Examples

## Not run: 

data(lmdp, package = "R2MLwiN") 

# Example taken from Leyland and Groenewegen (2020)

lmdp$ID <- seq(1:nrow(lmdp))

(mod_1 <- runMLwiN(smr ~ 1 + I(year - 79) +
                      (1 | district) + (1 | ID),
                   data = lmdp))

## End(Not run)

Returns the log-likelihood from "mlwinfitIGLS" objects.

Description

Returns the log-likelihood from "mlwinfitIGLS" objects.

Usage

## S4 method for signature 'mlwinfitIGLS'
logLik(object, ...)

Arguments

See Also

logLik-methods

Returns the log-likelihood from "mlwinfitIGLS" objects.

Description

Returns the log-likelihood from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
logLik(object, ...)

Arguments

See Also

logLik

For multiple membership models, translates matrix into a data.frame formatted for MLwiN Translates a matrix into a form usable by MLwiN for multiple membership models, namely a data.frame with (a) columns containing membership IDs (if first row matrix is 0 1 1 0 1 1, then first row of generated ID vectors would be, say, 2, 3, 5, 6) and (b) columns containing weights (in this example, if standardise = TRUE, then first row of generated weight vectors would be, say, 0.25, 0.25, 0.25, 0.25, otherwise first row of generated weight vectors would be, say, 1, 1, 1, 1).

Description

For multiple membership models, translates matrix into a data.frame formatted for MLwiN

Translates a matrix into a form usable by MLwiN for multiple membership models, namely a data.frame with (a) columns containing membership IDs (if first row matrix is 0 1 1 0 1 1, then first row of generated ID vectors would be, say, 2, 3, 5, 6) and (b) columns containing weights (in this example, if standardise = TRUE, then first row of generated weight vectors would be, say, 0.25, 0.25, 0.25, 0.25, otherwise first row of generated weight vectors would be, say, 1, 1, 1, 1).

Usage

matrix2df(mat, standardise = FALSE, idstub = "id", weightstub = "weight")

Arguments

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, U.K.

See Also

df2matrix

This function captures output files from MLwiN for estimation in WinBUGS/OpenBUGS.

Description

This function allows R to call WinBUGS using the output files from MLwiN. This function uses functionalities in the R2WinBUGS-package package.

Usage

mlwin2bugs(
  D,
  levID,
  datafile,
  initfiles,
  modelfile,
  bugEst,
  fact,
  addmore,
  n.chains,
  n.iter,
  n.burnin,
  n.thin,
  debug = FALSE,
  bugs.directory = bugs.directory,
  bugsWorkingDir = tempdir(),
  OpenBugs = FALSE,
  cleanBugsWorkingDir = FALSE,
  seed = NULL
)

Arguments

Details

A list of objects to specify factor analysis, as used in the argument fact:

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

Value

Returns an mcmc 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.

See Also

runMLwiN,bugs

An S4 class that stores the outputs of the fitted IGLS model.

Description

An MLwiN model run via the IGLS estimation method is represented by an "mlwinfitIGLS" object

Slots

Nobs

Computes the number of complete observations.

DataLength

Total number of cases.

Hierarchy

For each higher level of a multilevel model, returns the number of units at that level, together with the minimum, mean and maximum number of lower-level units nested within units of the current level.

D

A vector specifying the type of distribution to be modelled, which can include 'Normal', 'Binomial' 'Poisson', 'Multinomial', 'Multivariate Normal', or 'Mixed'.

Formula

A formula object (or a character string) specifying a multilevel model.

levID

A character string (vector) of the specified level ID(s).

contrasts

A list of contrast matrices, one for each factor in the model.

xlevels

A list of levels for the factors in the model.

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.

elapsed.time

Calculates the CPU time used for fitting the model.

call

The matched call.

LIKE

The deviance statistic (-2*log(like)).

Converged

Boolean indicating whether the model has converged

Iterations

Number of iterations that the model has run for

Meth

If Meth = 0 estimation method is set to RIGLS. If Meth = 1 estimation method is set to IGLS.

residual

If resi.store is TRUE, then the residual estimates at all levels are returned.

data

The data.frame that was used to fit the model.

nonlinear

A character vector specifying linearisation method used. The first element specifies marginal quasi-likelihood linearization (N = 0) or penalised quasi-likelihood linearization (N = 1); The second element specifies first (M = 1) or second (M = 2) order approximation.

version

The MLwiN version used to fit the model

An instance of the Class

An instance is created by calling function runMLwiN.

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.

See Also

runMLwiN

Examples

## 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/')

## Example: tutorial
data(tutorial, package = "R2MLwiN")

(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
                     data = tutorial))

##summary method
summary(mymodel)

##logLik method
logLik(mymodel)

## End(Not run)

An S4 class that stores the outputs of the fitted MCMC model.

Description

An MLwiN model run via the MCMC estimation method is represented by an "mlwinfitMCMC" object

Slots

Nobs

Computes the number of complete observations.

DataLength

Total number of cases.

Hierarchy

For each higher level of a multilevel model, returns the number of units at that level, together with the minimum, mean and maximum number of lower-level units nested within units of the current level.

burnin

An integer specifying length of the burn-in.

nchains

An integer specifying number of MCMC chains run.

iterations

An integer specifying the number of iterations after burn-in.

D

A vector specifying the type of distribution to be modelled, which can include 'Normal', 'Binomial' 'Poisson', 'Multinomial', 'Multivariate Normal', or 'Mixed'.

Formula

A formula object (or a character string) specifying a multilevel model.

levID

A character string (vector) of the specified level ID(s).

contrasts

A list of contrast matrices, one for each factor in the model.

xlevels

A list of levels for the factors in the model.

merr

A vector which sets-up measurement errors on predictor variables.

fact

A list of objects specified for factor analysis, including nfact, lev.fact, nfactor, factor, loading and constr.

xc

A list of objects specified for cross-classified and/or multiple membership models, including class, N1, weight, id and car.

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.

chains

Captures the MCMC chains from MLwiN for all parameters.

elapsed.time

Calculates the CPU time used for fitting the model.

BDIC

Bayesian Deviance Information Criterion (DIC)

call

The matched call.

LIKE

The deviance statistic (-2*log(like)).

fact.loadings

If fact is not empty, then the factor loadings are returned.

fact.loadings.sd

If fact is not empty, then the factor loading standard deviationss are returned.

fact.cov

If fact is not empty, then factor covariances are returned.

fact.cov.sd

If fact is not empty, then factor covariance standard deviations are returned.

fact.chains

If fact is not empty, then the factor chains are returned.

MIdata

If dami[1] is one then the mean complete response variable y is returned for each chain, if dami[1] is two then the SD is also included.

imputations

If dami[1] is zero, then a list of completed datasets containing complete response variable y is 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.

version

The MLwiN version used to fit the model

data

The data.frame that was used to fit the model.

An instance of the Class

An instance is created by calling function runMLwiN.

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.

See Also

runMLwiN

Examples

## 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/')
  
## Example: tutorial
data(tutorial, package = "R2MLwiN")

(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
                     estoptions = list(EstM = 1), data = tutorial)) 

##summary method
summary(mymodel)

##BDIC slot
mymodel@BDIC

## End(Not run)

EC data on UV radiation exposure & malignant melanoma.

Description

EC data on UV radiation exposure & malignant melanoma, consisting of 354 counties across 79 regions across 9 nations.

Usage

mmmec

Format

A data frame with 354 observations on the following variables:

nation

Nation ID: a factor with levels corresponding to each country.

region

Region (within-nation) ID.

county

County (within-region) ID.

obs

Number of male deaths due to malignant melanoma between 1971 and 1980.

exp

Expected number of deaths - proportional to county population.

cons

Constant (=1).

uvbi

County-level measurement of UV B radiation, centered on the mean.

Details

The mmmec dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009). Further information can be found in Langford et al. (1998) and Browne (2012).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Langford, I. H., Bentham, G., McDonald, A-L. (1998) Multi-level modelling of geographically aggregated health data: a case study on malignant melanoma mortality and UV exposure in the European Community. Statistics in Medicine 17: 41-57.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

See Also

See mlmRev package for an alternative format of the same dataset, with fewer variables.

Examples

## Not run: 

data(mmmec, package = "R2MLwiN")

(mymodel3 <- runMLwiN(log(obs) ~ 1 + uvbi + offset(log(exp)) + (1 | nation) + (1 | region), 
 D = "Poisson", estoptions = list(EstM = 1), data = mmmec))


## End(Not run)

Returns the number of used observations from "mlwinfitIGLS" objects.

Description

Returns the number of used observations from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
nobs(object, ...)

Arguments

See Also

nobs

Returns the number of used observations from "mlwinfitMCMC" objects.

Description

Returns the number of used observations from "mlwinfitMCMC" objects.

Usage

## S3 method for class 'mlwinfitMCMC'
nobs(object, ...)

Arguments

See Also

nobs

Draws predicted curves (lines) using estimates from the fixed part of a fitted model.

Description

This function draws predicted curves (lines) against an explanatory variable for each category of a categorical variable.

Usage

predCurves(
  object,
  indata = NULL,
  xname,
  group = NULL,
  legend = TRUE,
  legend.space = "top",
  legend.ncol = 2,
  ...
)

Arguments

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.

See Also

predLines

Examples

## 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/')

## Read alevchem data
data(alevchem, package = "R2MLwiN")

alevchem$gcseav <- alevchem$gcse_tot/alevchem$gcse_no - 6
# Avoids warning when fitting factor as continuous response:
alevchem$a_point_num <- as.numeric(alevchem$a_point)

## Example: A-level Chemistry
(mymodel <- runMLwiN(a_point_num ~ 1 + gcseav + I(gcseav^2) + I(gcseav^3)
                     + gender + (1 | pupil), estoptions = list(EstM = 1,  resi.store = TRUE),
                     data = alevchem))
                     
predCurves(mymodel, xname = "gcseav", group = "genderfemale")

## End(Not run)

Draws predicted lines using a fitted model object

Description

This function draws predicted lines against an explanatory variable for selected groups at a higher (>=2) level. Note that it uses a lot of contiguous memory, and so we recommend running via 64-bit version R to mititage against any potential problems.

Usage

predLines(
  object,
  indata = NULL,
  xname,
  lev = 2,
  selected = NULL,
  probs = c(0.025, 0.975),
  legend = TRUE,
  legend.space = "top",
  legend.ncol = 4,
  ...
)

Arguments

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.

See Also

predCurves

Examples

## 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/')

## Example: tutorial
data(tutorial, package = "R2MLwiN")
(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
                     estoptions = list(EstM = 1, resi.store.levs = 2), data = tutorial))

predLines(mymodel, xname = "standlrt", lev = 2, selected = c(30, 44, 53, 59),
          probs = c(0.025, 0.975))

## End(Not run)

Returns the predicted data from "mlwinfitIGLS" objects.

Description

Returns the predicted data from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
predict(
  object,
  newdata = NULL,
  params = NULL,
  type = "link",
  se.fit = FALSE,
  terms = NULL,
  ...
)

Arguments

See Also

predict

Returns the predicted data from "mlwinfitMCMC" objects.

Description

Returns the predicted data from "mlwinfitMCMC" objects.

Usage

## S3 method for class 'mlwinfitMCMC'
predict(
  object,
  newdata = NULL,
  params = NULL,
  type = "link",
  se.fit = FALSE,
  terms = NULL,
  ...
)

Arguments

See Also

predict

Summarize "mlwinfitIGLS" objects

Description

Summarize "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
print(
  x,
  digits = max(3, getOption("digits") - 2),
  signif.stars = getOption("show.signif.stars"),
  ...
)

Arguments

See Also

print

Summarize "mlwinfitMCMC" objects

Description

Summarize "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
print(
  x,
  digits = max(3, getOption("digits") - 2),
  signif.stars = getOption("show.signif.stars"),
  z.ratio = TRUE,
  ...
)

Arguments

See Also

print

Translates informative prior information into a concise MLwiN macro.

Description

An internal function which takes an R list object containing informative prior information for a multilevel model and translates it into a concise vector object to be used in an MLwiN macro.

Usage

prior2macro(prior, D, fpart, nrand)

Arguments

Details

The prior list can contain the following:

• 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. The names used in the list should match those in the model output.

• rp<level number>: A list object specifying the Wishart or gamma prior for the covariance matrix or scalar variance at the levels specified, e.g. rp1 for level 1, rp2 for level 2, etc. 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.

Value

A long vector is returned in the format of MLwiN macro language. This includes all the specified prior parameters.

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.

See Also

runMLwiN

Weights of 30 rats, measured weekly over 5 weeks.

Description

Weights of 30 rats, measured weekly over 5 weeks.

Usage

rats

Format

A data frame with 30 observations on the following 7 variables:

y8

Weight on day 8.

y15

Weight on day 15.

y22

Weight on day 22.

y29

Weight on day 29.

y36

Weight on day 36.

cons

Constant(=1).

rat

Rat ID

Details

The rats dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009); see Browne (2012) and Gelfand (1990) for further details.

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Gelfand, A. E., Hills, S.E., Racine-Poon, A., Smith, A.F.M. (1990) Illustration of Bayesian inference in normal data models using Gibbs sampling. Journal of the American Statistical Association 85: 972-985.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(rats, package = "R2MLwiN")

(mymodel <- runMLwiN(c(y8, y15, y22, y29, y36) ~ 1 + (1 | rat), 
  D = "Multivariate Normal", estoptions = list(EstM = 1),
  data = rats))


## End(Not run)

Students' reading attainment in inner London infant schools.

Description

Reading score data for 407 pupils across 6 occasions.

Usage

reading1

Format

A data frame with 407 observations on the following 13 variables:

id

Unique pupil identifying code.

age1

Age at occasion 1.

read1

Reading score at occasion 1.

age2

Age at occasion 2.

read2

Reading score at occasion 2.

age3

Age at occasion 3.

read3

Reading score at occasion 3.

age4

Age at occasion 4.

read4

Reading score at occasion 4.

age5

Age at occasion 5.

read5

Reading score at occasion 5.

age6

Age at occasion 6.

read6

Reading score at occasion 6.

Details

The reading1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and was analysed in Tizard et al. (1988); see also Rasbash et al. (2012) for further details.

Source

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol. Rasbash, J., Steele, F., Browne, W.J., Goldstein, H. (2012) A User's Guide to MLwiN v2.26. University of Bristol: Centre for Multilevel Modelling. Tizard, B., Blatchford, P., Burke, J. & Farquhar, C. (1988). Young children at school in the inner city. Hove, Sussex: Lawrence Erlbaum.

Examples

## Not run: 
# from demo(UserGuide13)

data(reading1, package = "R2MLwiN")
summary(reading1)

reading1[reading1 == -10] <- NA

summary(reading1)

reading <- reshape(reading1, idvar = "student", timevar = "id",
                   varying = c("read1", "age1", "read2", "age2", "read3", "age3",
                   "read4", "age4", "read5", "age5", "read6", "age6"),
                   sep = "", direction = "long")

reading <- reading[c("student", "id", "age", "read")]
reading <- reading[order(reading$student, reading$id), ]

colnames(reading) <- c("student", "occasion", "age", "reading")
rownames(reading) <- NULL

summary(reading)

head(reading, 5)

tab <- aggregate(reading ~ occasion, reading,
                 function(x) c(N = length(x), mean = mean(x), sd = sd(x)))
tab <- rbind(tab, c(NA, NA))
tab$reading[7, ] <- c(length(na.omit(reading$reading)),
                      mean(na.omit(reading$reading)),
                      sd(na.omit(reading$reading)))
rownames(tab)[7] <- "Total"
tab

tab <- aggregate(age ~ occasion, reading,
                 function(x) c(N = length(x), mean = mean(x), sd = sd(x)))
tab <- rbind(tab, c(NA, NA))
tab$age[7, ] <- c(length(na.omit(reading$age)),
                  mean(na.omit(reading$age)),
                  sd(na.omit(reading$age)))
rownames(tab)[7] <- "Total"
tab

(mymodel1 <- runMLwiN(reading ~ 1 + (1 | student) + (1 | occasion),
                      data = reading))

## End(Not run)

Returns the residual data from "mlwinfitIGLS" objects.

Description

Returns the residual data from "mlwinfitIGLS" objects.

Usage

## S3 method for class 'mlwinfitIGLS'
residuals(object, ...)

Arguments

See Also

residuals

Returns the residual data from "mlwinfitMCMC" objects.

Description

Returns the residual data from "mlwinfitMCMC" objects.

Usage

## S3 method for class 'mlwinfitMCMC'
residuals(object, ...)

Arguments

See Also

residuals

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

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.

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)

Show objects of class "mlwinfitIGLS"

Description

Show objects of class "mlwinfitIGLS"

Usage

## S4 method for signature 'mlwinfitIGLS'
show(object)

Arguments

See Also

show-methods

Show objects of class "mlwinfitMCMC"

Description

Show objects of class "mlwinfitMCMC"

Usage

## S4 method for signature 'mlwinfitMCMC'
show(object)

Arguments

See Also

show-methods

Summarize "mlwinfitIGLS" objects

Description

Summarize "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
show(object, ...)

Arguments

See Also

show

Summarize "mlwinfitMCMC" objects

Description

Summarize "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
show(object, ...)

Arguments

See Also

show

Draws a sixway plot of MCMC diagnostics.

Description

This function produces a variety of diagnostic plots and statistics for MCMC chains.

Usage

sixway(chain, name = NULL, acf.maxlag = 100, pacf.maxlag = 10, ...)

Arguments

Details

A variety of plots and statistics are displayed in an R graphic window, including the following:

• a trace plot of the plotted trajectory of an MCMC chain for a model parameter;

• a kernel density plot; kernel density estimates are computed using density;

• a plotted autocorrelation function (uses acf);

• a plotted partial autocorrelation function (uses pacf);

• a plot of the estimated Monte Carlo standard error (MCSE) of the posterior estimate of the mean against the number of iterations. As MCMC is a simulation-based approach this induces (Monte Carlo) uncertainty due to the random numbers it uses. This uncertainty reduces with more iterations, and is measured by the MCSE, and so this graph details how long the chain needs to be run to achieve a specific MCSE;

• a box contains two contrasting accuracy diagnostics. The Raftery-Lewis diagnostic (raftery.diag) is a diagnostic based on a particular quantile of the distribution. The diagnostic Nhat is used to estimate the length of Markov chain required to estimate a particular quantile (e.g. the 2.5% and 97.5% quantiles) to a given accuracy. The Brooks-Draper diagnostic (BD) is a diagnostic based on the mean of the distribution. It is used to estimate the length of Markov chain required to produce a mean estimate to k(=2) significant figures with a given accuracy;

• a box of summary statistics including the posterior mean, sd, mode, quantiles and the effective sample size (ESS) of the chain.

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.

See Also

BD,MCSE,density,acf,pacf,raftery.diag,effectiveSize

Examples

## 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/')

## Example: tutorial
data(tutorial, package = "R2MLwiN")

(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
                     estoptions = list(EstM = 1, resi.store.levs = 2), data = tutorial))

sixway(mymodel@chains[, "FP_standlrt", drop = FALSE], "beta_1")


## End(Not run)

Summarize "mlwinfitIGLS" objects

Description

Summarize "mlwinfitIGLS" objects

Usage

## S4 method for signature 'mlwinfitIGLS'
summary(object, ...)

Arguments

See Also

summary-methods

Summarize "mlwinfitMCMC" objects

Description

Summarize "mlwinfitMCMC" objects

Usage

## S4 method for signature 'mlwinfitMCMC'
summary(object, ...)

Arguments

See Also

summary-methods

Summarize "mlwinfitIGLS" objects

Description

Summarize "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
summary(object, ...)

Arguments

Summarize "mlwinfitMCMC" objects

Description

Summarize "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
summary(object, ...)

Arguments

Summarises information about the components of a model from a statistical object (broom package).

Description

Summarises information about the components of a model from a statistical object (broom package).

Usage

## S3 method for class 'mlwinfitIGLS'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

See Also

tidy

Summarises information about the components of a model from a statistical object (broom package).

Description

Summarises information about the components of a model from a statistical object (broom package).

Usage

## S3 method for class 'mlwinfitMCMC'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

See Also

tidy

Plots MCMC chain trajectories

Description

This function draws trajectories of MCMC chains.

Usage

trajectories(object, Range = c(1, 5000), selected = NULL)

Arguments

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.

See Also

sixway

Examples

## 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/')

## Example: tutorial
data(tutorial, package = "R2MLwiN")

(mymodel <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | student),
                     estoptions = list(EstM = 1), data = tutorial))

trajectories(mymodel, Range = c(4501, 5000))

## End(Not run)

Exam results for six inner London Education Authorities

Description

A subset of data from a much larger dataset of examination results from six inner London Education Authorities (school boards).

Usage

tutorial

Format

A data frame with 4059 observations on the following 10 variables:

school

Numeric school identifier.

student

Numeric student identifier.

normexam

Students' exam score at age 16, normalised to have approximately a standard Normal distribution.

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

standlrt

Students' score at age 11 on the London Reading Test (LRT), standardised using Z-scores.

sex

Sex of pupil; a factor with levels boy, girl.

schgend

Schools' gender; a factor with levels corresponding to mixed school (mixedsch), boys' school (boysch), and girls' school (girlsch).

avslrt

Average LRT score in school.

schav

Average LRT score in school, coded into 3 categories: low = bottom 25%, mid = middle 50%, high = top 25%.

vrband

Students' score in test of verbal reasoning at age 11, a factor with 3 levels: vb1 = top 25%, vb2 = middle 50%, vb3 = bottom 25%.

Details

The tutorial dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), and is a subset of data from a much larger dataset of examination results from six inner London Education Authorities (school boards). The original analysis (Goldstein et al., 1993) sought to establish whether some secondary schools had better student exam performance at 16 than others, after taking account of variations in the characteristics of students when they started secondary school; i.e., the analysis investigated the extent to which schools 'added value' (with regard to exam performance), and then examined what factors might be associated with any such differences. See also Rasbash et al. (2012) and Browne (2012).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Goldstein, H., Rasbash, J., Yang, M., Woodhouse, G., Pan, H., Nuttall, D., Thomas, S. (1993) A multilevel analysis of school examination results. Oxford Review of Education, 19, 425–433.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

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

See mlmRev package for an alternative format of the same dataset.

Examples

## Not run: 

data(tutorial, package = "R2MLwiN")

# Fit 2-level variance components model, using IGLS (default estimation method)
(VarCompModel <- runMLwiN(normexam ~ 1 + (1 | school) + (1 | student), data = tutorial))

# print variance partition coefficient (VPC)
print(VPC <- coef(VarCompModel)[["RP2_var_Intercept"]] /
             (coef(VarCompModel)[["RP1_var_Intercept"]] +
             coef(VarCompModel)[["RP2_var_Intercept"]]))

# Fit same model using MCMC
(VarCompMCMC <- runMLwiN(normexam ~ 1 + (1 | school) + (1 | student),
 estoptions = list(EstM = 1), data = tutorial))

# return diagnostics for VPC
VPC_MCMC <- VarCompMCMC@chains[,"RP2_var_Intercept"] /
            (VarCompMCMC@chains[,"RP1_var_Intercept"] +
            VarCompMCMC@chains[,"RP2_var_Intercept"])
sixway(VPC_MCMC, name = "VPC")

# Adding predictor, allowing its coefficient to vary across groups (i.e. random slopes)
(standlrtRS_MCMC <- runMLwiN(normexam ~ 1 + standlrt + (1 + standlrt | school) + (1 | student),
 estoptions = list(EstM = 1), data = tutorial))

# Example modelling complex level 1 variance
# fit log of precision at level 1 as a function of predictors
(standlrtC1V_MCMC <- runMLwiN(normexam ~ 
  1 + standlrt + (school | 1 + standlrt) + (1 + standlrt | student),
  estoptions = list(EstM = 1, mcmcMeth = list(lclo = 1)),
  data = tutorial))


## End(Not run)

Update "mlwinfitIGLS" objects

Description

Update "mlwinfitIGLS" objects

Usage

## S4 method for signature 'mlwinfitIGLS'
update(
  object,
  Formula.,
  levID.,
  estoptions.,
  ...,
  keep.order = TRUE,
  evaluate = TRUE
)

Arguments

Value

either a new updated mlwinfitIGLS class object, or else an unevaluated expression for creating such an object.

See Also

update-methods

Update "mlwinfitMCMC" objects

Description

Update "mlwinfitMCMC" objects

Usage

## S4 method for signature 'mlwinfitMCMC'
update(
  object,
  Formula.,
  levID.,
  estoptions.,
  ...,
  keep.order = TRUE,
  evaluate = TRUE
)

Arguments

Value

either a new updated mlwinfitMCMC class object, or else an unevaluated expression for creating such an object.

See Also

update-methods

Update "mlwinfitIGLS" objects

Description

Update "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
update(object, ...)

Arguments

Value

either a new updated mlwinfitIGLS class object, or else an unevaluated expression for creating such an object.

See Also

update

Update "mlwinfitMCMC" objects

Description

Update "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
update(object, ...)

Arguments

Value

either a new updated mlwinfitMCMC class object, or else an unevaluated expression for creating such an object.

See Also

update

Extract the approximate variance-covariance matrix from "mlwinfitIGLS" objects

Description

Extract the approximate variance-covariance matrix from "mlwinfitIGLS" objects

Usage

## S4 method for signature 'mlwinfitIGLS'
vcov(object, ...)

Arguments

See Also

vcov-methods

Extract the approximate variance-covariance matrix from "mlwinfitMCMC" objects

Description

Extract the approximate variance-covariance matrix from "mlwinfitMCMC" objects

Usage

## S4 method for signature 'mlwinfitMCMC'
vcov(object, ...)

Arguments

See Also

vcov-methods

Extract the approximate variance-covariance matrix from "mlwinfitIGLS" objects

Description

Extract the approximate variance-covariance matrix from "mlwinfitIGLS" objects

Usage

## S3 method for class 'mlwinfitIGLS'
vcov(object, ...)

Arguments

See Also

vcov

Extract the approximate variance-covariance matrix from "mlwinfitMCMC" objects

Description

Extract the approximate variance-covariance matrix from "mlwinfitMCMC" objects

Usage

## S3 method for class 'mlwinfitMCMC'
vcov(object, ...)

Arguments

See Also

vcov

Simulated dataset of office workers' salary and other employment details.

Description

A simulated dataset of office workers' salary (and associated information) in which workers exhibit multiple membership of companies worked for over past year.

Usage

wage1

Format

A data frame with 3022 observations on the following 21 variables:

id

Unique office worker identifying code.

company

Identifying code for company worked for over the last 12 months.

company2

If worked for >1 company over the last 12 months, identifying code for second company.

company3

If worked for >2 companies over the last 12 months, identifying code for third company.

company4

If worked for >3 companies over the last 12 months, identifying code for fourth company.

age

Age of worker.

parttime

Part or full-time, a factor with levels Fulltime and Parttime.

sex

Sex of worker, a factor with levels male and female.

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

earnings

Workers' earnings over the last financial year.

logearn

Workers' (natural) log-transformed earnings over the last financial year.

numjobs

The number of companies worked for over the last 12 months.

weight1

Proportion of time worked for employer listed in company.

weight2

Proportion of time worked for employer listed in company2.

weight3

Proportion of time worked for employer listed in company3.

weight4

Proportion of time worked for employer listed in company4.

ew1

Alternative (equal) weighting for company (1/numjobs).

ew2

Alternative (equal) weighting for company2 (if numjobs >1 then 1/numjobs, else 0).

ew3

Alternative (equal) weighting for company3 (if numjobs >2 then 1/numjobs, else 0).

ew4

Alternative (equal) weighting for company4 (if numjobs >3 then 1/numjobs, else 0).

age_40

Age of worker, centered on 40 years.

Details

The simulated wage1 dataset is one of the sample datasets provided with the multilevel modelling software package MLwiN (Rasbash et al., 2009), and described in Browne (2012). It consists of salary and associated information for office workers, and is used by Browne (2012) as an example of modelling a multiple membership structure. The dataset exhibits multiple membership in that workers are clustered across the companies employing them over the past year, but some have worked for more than one company during that time.)

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

Examples

## Not run: 

data(wage1, package = "R2MLwiN")

(mymodel <- runMLwiN(logearn ~ 1 + age_40 + numjobs + (1 | company) + (1 | id), 
  estoptions = list(EstM = 1, 
  mm = list(list(mmvar = list("company", "company2", "company3", "company4"),
  weights = list("weight1", "weight2", "weight3", "weight4")), NA)),
  data = wage1))


## End(Not run)

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

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

Writes MLwiN macros to fit models using Markov chain Monte Carlo (MCMC) methods

Description

write.MCMC is an internal function which creates an MLwiN macro file to fit models using MCMC.

Usage

write.MCMC(
  indata,
  dtafile,
  oldsyntax = FALSE,
  resp,
  levID,
  expl,
  rp,
  D = "Normal",
  nonlinear = c(0, 1),
  categ = NULL,
  notation = NULL,
  nonfp = NULL,
  clre = NULL,
  Meth = 1,
  merr = NULL,
  carcentre = FALSE,
  maxiter = 20,
  convtol = 2,
  seed = 1,
  iterations = 5000,
  burnin = 500,
  scale = 5.8,
  thinning = 1,
  priorParam = "default",
  refresh = 50,
  fixM = 1,
  residM = 1,
  Lev1VarM = 1,
  OtherVarM = 1,
  adaption = 1,
  priorcode = c(gamma = 1),
  rate = 50,
  tol = 10,
  lclo = 0,
  mcmcOptions,
  fact = NULL,
  xc = NULL,
  mm = NULL,
  car = NULL,
  BUGO = NULL,
  mem.init = "default",
  optimat = FALSE,
  modelfile,
  initfile,
  datafile,
  macrofile,
  IGLSfile,
  MCMCfile,
  chainfile,
  MIfile,
  resifile,
  resi.store = FALSE,
  resioptions,
  resichains,
  FACTchainfile,
  resi.store.levs = NULL,
  debugmode = FALSE,
  startval = NULL,
  dami = NULL,
  namemap = sapply(colnames(indata), as.character),
  saveworksheet = NULL,
  rng.version = 10
)

Arguments

Details

A list of other MCMC options as used in the argument mcmcOptions:

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

A list of objects specified for cross-classified and/or multiple membership models, as used in the argument xclass:

• class: An integer (vector) of the specified class(es).

• N1: This defines a multiple membership across N1 units at level class. N1>1 if there is multiple membership.

• weight: If there is multiple membership then the column number weight, which is the length of the dataset, will contain the first set of weights for the multiple membership. Note that there should be N1 weight columns and they should be sequential in the worksheet starting from weight.

• id: If the response is multivariate then the column number id must be input and this contains the first set of identifiers for the classification. Note that for a p-variate model each lowest level unit contains p records and the identifiers (sequence numbers) for each response variate need to be extracted into id and following columns. There should be N1 of these identifier columns and they should be sequential starting from id in the multivariate case.

• car: car = TRUE indicates the spatial CAR model; FALSE otherwise. car = FALSE if ignored.

A list of objects specified for factor analysis, as used in the argument fact:

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

Value

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

Note

Note that for FixM, residM, Lev1VarM and

OtherVarM, not all combinations of methods are available for all sets of parameters and all models.

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

Converts data from one format to another within MLwiN

Description

This function converts data from one format to another within MLwiN, via MLwiN macro language. The foreign package allows R to read data files for most of these formats.

Usage

ws2foreign(wsfile, foreignfile, MLwiNPath = NULL, x64 = NULL)

Arguments

Details

MLwiN supports conversion between MLwiN (*.wsz, *.ws), Minitab (*.mtw), SAS (*.xpt), SPSS (*.sav), and Stata (*.dta) files.

The converted data file (with a specific extension) will be saved to the file specified by foreignfile.

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.

See Also

read.dta

Examples

## 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/')

wsfile = normalizePath(file.path(getOption("MLwiN_path"), "samples/tutorial.ws"), winslash = "/")
## the tutorial.dta file will be saved in the temporary folder
inputfile = normalizePath(file.path(tempdir(), "tutorial.dta"), winslash = "/", mustWork = FALSE)
ws2foreign(wsfile, foreignfile = inputfile)
library(foreign)
indata = read.dta(inputfile)
str(indata)
unlink(inputfile)

## End(Not run)

Examination scores of 16-year olds in Fife, Scotland.

Description

A dataset of examination scores of 16-year olds in Fife, Scotland, in which the secondary school the pupil attended is cross-classified by the primary school the pupil attended.

Usage

xc

Format

A data frame with 3435 observations on the following 11 variables:

vrq

A verbal reasoning score resulting from tests pupils took when they entered secondary school.

attain

Attainment score of pupils at age sixteen.

pid

Primary school identifying code.

sex

Pupils' gender: a factor with levels Male and Female.

sc

Pupils' social class (scaled from low to high).

sid

Secondary school identifying code.

fed

Fathers' education.

choice

Choice number of secondary school attended (where 1 is first choice, etc.)

med

Mothers' education.

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

pupil

Pupil identifying code.

Details

The xc dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), analysed by Paterson (1991). The data are cross-classified in that not all children who attended the same primary school subsequently entered the same secondary school. See also Rasbash et al. (2012).

Source

Paterson, L. (1991) Socio economic status and educational attainment: a multidimensional and multilevel study. Evaluation and Research in Education, 5, 97-121. Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol. Rasbash, J., Steele, F., Browne, W.J., Goldstein, H. (2012) A User's Guide to MLwiN v2.26. University of Bristol: Centre for Multilevel Modelling.

See Also

See mlmRev package for an alternative format of the same dataset.

Examples

## Not run: 

data(xc, package = "R2MLwiN")

(mymodel <- runMLwiN(attain ~ 1 + (1 | sid) + (1 | pid) + (1 | pupil),
 estoptions = list(xc = TRUE, EstM = 1), data = xc))


## End(Not run)

Examination scores of 16-year olds in Fife, Scotland.

Description

A dataset of examination scores of 16-year olds in Fife, Scotland, in which the secondary school the pupil attended is cross-classified by the primary school the pupil attended.

Usage

xc1

Format

A data frame with 3435 observations on the following 11 variables:

vrq

A verbal reasoning score resulting from tests pupils took when they entered secondary school.

attain

Attainment score of pupils at age sixteen.

pid

Primary school identifying code.

sex

Pupils' gender: a factor with levels Male and Female.

sc

Pupils' social class (scaled from low to high).

sid

Secondary school identifying code.

fed

Fathers' education.

choice

Choice number of secondary school attended (where 1 is first choice, etc.)

med

Mothers' education.

cons

A column of ones. If included as an explanatory variable in a regression model (e.g. in MLwiN), its coefficient is the intercept.

pupil

Pupil identifying code.

Details

The xc1 dataset is one of the sample datasets provided with the multilevel-modelling software package MLwiN (Rasbash et al., 2009), analysed by Paterson (1991). The data are cross-classified in that not all children who attended the same primary school subsequently entered the same secondary school. See also Browne (2012).

Source

Browne, W. J. (2012) MCMC Estimation in MLwiN Version 2.26. University of Bristol: Centre for Multilevel Modelling.

Paterson, L. (1991) Socio economic status and educational attainment: a multidimensional and multilevel study. Evaluation and Research in Education, 5, 97-121.

Rasbash, J., Charlton, C., Browne, W.J., Healy, M. and Cameron, B. (2009) MLwiN Version 2.1. Centre for Multilevel Modelling, University of Bristol.

See Also

See mlmRev package for an alternative format of the same dataset.

Examples

## Not run: 

data(xc1, package = "R2MLwiN")

(mymodel <- runMLwiN(attain ~ 1 + (1 | sid) + (1 | pid) + (1 | pupil),
 estoptions = list(xc = TRUE, EstM = 1), data = xc1))


## End(Not run)