Package 'R2MLwiN'

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

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

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)

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

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

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)

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)

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

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)

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)

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)

Description

Extract the coefficient vector from "mlwinfitIGLS" objects

Usage

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

Arguments

See Also

coef-methods

Description

Extract the coefficient vector from "mlwinfitMCMC" objects

Usage

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

Arguments

See Also

coef-methods

Description

Extract the coefficient vector from "mlwinfitIGLS" objects

Usage

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

Arguments

See Also

coef

Description

Extract the coefficient vector from "mlwinfitMCMC" objects

Usage

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

Arguments

See Also

coef

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)

Description

Returns the deviance from "mlwinfitIGLS" objects.

Usage

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

Arguments

See Also

deviance

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

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

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)

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.

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

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

Description

Returns the fitted values from "mlwinfitIGLS" objects.

Usage

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

Arguments

See Also

fitted.values

Description

Returns the fitted values from "mlwinfitMCMC" objects.

Usage

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

Arguments

See Also

fitted.values

Description

"mlwinfitIGLS" model formula

Usage

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

Arguments

Description

"mlwinfitMCMC" model formula

Usage

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

Arguments

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)

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

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)

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)

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)

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

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

Description

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

Usage

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

Arguments

See Also

glance

Description

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

Usage

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

Arguments

See Also

glance

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)

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)

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)

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)

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)

Description

Returns the log-likelihood from "mlwinfitIGLS" objects.

Usage

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

Arguments

See Also

logLik-methods

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

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

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(
  datafile,
  initfiles,
  modelfile,
  parameters = NULL,
  n.chains = 1,
  n.iter = 5500,
  n.burnin = 500,
  n.thin = 1,
  debug = FALSE,
  bugs.directory = NULL,
  bugsWorkingDir = tempdir(),
  OpenBugs = FALSE,
  cleanBugsWorkingDir = FALSE,
  seed = NULL
)

Arguments

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

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)

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)

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)

Description

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

Usage

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

Arguments

See Also

nobs

Description

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

Usage

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

Arguments

See Also

nobs

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)

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

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

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)

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

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

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

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)

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)

Description

Returns the residual data from "mlwinfitIGLS" objects.

Usage

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

Arguments

See Also

residuals

Description

Returns the residual data from "mlwinfitMCMC" objects.

Usage

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

Arguments

See Also

residuals

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:
## https://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)

Description

Show objects of class "mlwinfitIGLS"

Usage

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

Arguments

See Also

show-methods

Description

Show objects of class "mlwinfitMCMC"

Usage

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

Arguments

See Also

show-methods

Description

Summarize "mlwinfitIGLS" objects

Usage

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

Arguments

See Also

show

Description

Summarize "mlwinfitMCMC" objects

Usage

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

Arguments

See Also

show

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)

Description

Summarize "mlwinfitIGLS" objects

Usage

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

Arguments

See Also

summary-methods

Description

Summarize "mlwinfitMCMC" objects

Usage

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

Arguments

See Also

summary-methods

Description

Summarize "mlwinfitIGLS" objects

Usage

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

Arguments

Description

Summarize "mlwinfitMCMC" objects

Usage

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

Arguments

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

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

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)

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)

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)

Description

Update "mlwinfitIGLS" objects

Usage

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

Arguments