Version: 0.71.6
Title: Functions and Data Supporting 'Linear Mixed-Effects Models: A Step-by-Step Approach'
Description: Provides functions and datasets to support the book by Galecki and Burzykowski (2013), 'Linear Mixed-Effects Models: A Step-by-Step Approach', Springer. Includes functions for power calculations, log-likelihood contributions, and data simulation for linear mixed-effects models.
Imports: nlme, stats
Suggests: reshape, WWGbook, lattice, ellipse, roxygen2, testthat
Encoding: UTF-8
RoxygenNote: 7.3.2
License: GPL-2
URL: https://github.com/agalecki/nlmeU
Depends: R (≥ 3.5.0)
NeedsCompilation: no
Packaged: 2025-08-07 15:43:26 UTC; agalecki
Author: Andrzej Galecki ORCID iD [aut, cre], Tomasz Burzykowski ORCID iD [aut]
Maintainer: Andrzej Galecki <agalecki@umich.edu>
Repository: CRAN
Date/Publication: 2025-08-25 13:00:02 UTC

nlmeU: Datasets and Utility Functions Enhancing Functionality of 'nlme' Package

Description

Provides functions and datasets to support the book by Galecki and Burzykowski (2013), "Linear Mixed-Effects Models Using R: A Step-by-Step Approach", Springer. Package includes functions for power calculations, log-likelihood contributions, and data simulation for linear mixed-effects models.

Details

This package provides datasets and utility functions to complement the nlme package, including functions like logLik1, Pwr, and simulateY. It also includes datasets such as armd, armd0, armd.wide, fcat, prt.fiber, prt, prt.subjects, and SIIdata.

Author(s)

Maintainer: Andrzej Galecki agalecki@umich.edu (ORCID)

Authors:

See Also

Useful links:

Calculates power based on a model fit

Description

This function is generic; method functions can be written to handle specific classes of objects.

Usage

Pwr(object, ...)

Arguments

object

an object containing the results returned by a model fitting function (e.g., lme).

...

some methods for this generic function may require additional arguments.

Value

Numeric scalar value.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

References

Galecki, A., & Burzykowski, T. (2013). *Linear Mixed-Effects Models: A Step-by-Step Approach*. Springer.

See Also

Pwr.lme

Examples

## Not run: 
  library(nlme)
  fm1 <- lme(distance ~ age, data = Orthodont)
  Pwr(fm1)

## End(Not run)

Performs power calculations for an lme object

Description

This is a method for the Pwr generic function. It works for the example given in Galecki and Burzykowski (2013) but may require additional testing, especially for post-hoc power analysis.

Usage

## S3 method for class 'lme'
Pwr(
  object,
  ...,
  type = c("sequential", "marginal"),
  Terms,
  L,
  verbose = FALSE,
  ddf = numeric(0),
  alpha = 0.05,
  altB = NULL,
  tol = 1e-10
)

Arguments

object

an lme object containing a model fit, which provides information needed for power calculations.

...

some additional arguments may be required.

type

an optional character string specifying the type of sum of squares to be used in F-tests needed for power calculations. Syntax is the same as for anova.lme in the nlme package.

Terms

an optional integer or character vector specifying which terms in the model should be jointly tested to be zero using a Wald F-test. See anova.lme in the nlme package for details.

L

an optional numeric vector or array specifying linear combinations of the coefficients in the model that should be tested to be zero. See anova.lme in the nlme package for details.

verbose

logical. If TRUE, additional information is provided. See anova.lme in the nlme package for details.

ddf

numeric scalar value. Redefines the default number of denominator degrees of freedom.

alpha

numeric scalar value. By default, 0.05.

altB

matrix or vector containing alternative values for beta parameters.

tol

numeric scalar value for numerical tolerance.

Value

A data frame inheriting from class Pwr.lme.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

References

Galecki, A., & Burzykowski, T. (2013). *Linear Mixed-Effects Models: A Step-by-Step Approach*. Springer.

See Also

anova.lme

SIIdata Data (1190 x 12)

Description

Data from Study of Instructional Improvement Project

Usage

SIIdata

Format

A data frame with 1190 rows and 12 columns:

sex

A factor with 2 levels: M, F, i.e., males and females, respectively

minority

A factor with 2 levels: Mnrt=No, Mnrt=Yes. An indicator variable for the minority status

mathkind

An integer vector with values from 290 to 629. This is pupil's math score in the spring of the kindergarten year

mathgain

An integer vector with values from -110 to 253. Number represents pupil's gain in the math achievement score from the spring of kindergarten to the spring of first grade

ses

A numeric vector with values from -1.61 to 3.21. Value represents socioeconomic status

yearstea

A numeric vector with values from 0 to 40. It is number of years of teacher's experience in teaching in the first grade

mathknow

A numeric vector with values from -2.5 to 2.61. Number represents teacher's knowledge of the first-grade math contents (higher values indicate a higher knowledge of the contents)

housepov

A numeric vector containing proportion of households in the neighborhood of the school below the poverty level with values ranging from 0.012 to 0.564

mathprep

A numeric vector with values from 1 to 6. Contains the number of preparatory courses on the first-grade math contents and methods followed by the teacher

classid

A factor with 312 levels: 1, 2, 3, 4, 5, ..., 312. Classroom's id

schoolid

A factor with 107 levels: 1, 2, 3, 4, 5, ..., 107. School's id

childid

A factor with 1190 levels: 1, 2, 3, 4, 5, ..., 1190. Pupil's id

Details

The SII Project was carried out to assess the math achievement scores of first- and third-grade pupils in randomly selected classrooms from a national US sample of elementary schools (Hill et al, 2005). Data were also analyzed in West et al, 2007. The outcome of interest is mathgain variable. Data were created based on classroom data from WWGbook package.

Source

Hill, H., Rowan, B., and Ball, D. (2005). Effect of teachers' mathematical knowledge for teaching on student achievement. American Educational Research Journal, 42, 371-406. West, B. T., Welch, K. B., and Galecki, A. T. (2007). Linear Mixed Models: A Practical Guide Using Statistical Software. Chapman and Hall/CRC.

Examples

data(SIIdata, package = "nlmeU")
summary(SIIdata)

armd Data (867 x 8)

Description

Data from Age-Related Macular Degeneration (ARMD) clinical trial

Usage

armd

Format

A data frame with 867 rows and 8 columns:

subject

A factor with 234 levels: 1, 2, 3, 4, 6, ..., 240

treat.f

A factor with 2 levels: Placebo, Active

visual0

An integer vector with values ranging from 20 to 85

miss.pat

A factor with 8 levels: ----, ---X, --X-, --XX, -XX-, ..., X-XX

time.f

A factor with 4 levels: 4wks, 12wks, 24wks, 52wks

time

A numeric vector with values 4, 12, 24, 52

visual

An integer vector with values ranging from 3 to 85

tp

A numeric vector with values 1, 2, 3, 4 corresponding to time points 4, 12, 24, 52, respectively

Details

The ARMD data arise from a randomized multi-center clinical trial comparing an experimental treatment (interferon-alpha) versus placebo for patients diagnosed with ARMD.

Source

Pharmacological Therapy for Macular Degeneration Study Group (1997). Interferon alpha-IIA is ineffective for patients with choroidal neovascularization secondary to age-related macular degeneration. Results of a prospective randomized placebo-controlled clinical trial. Archives of Ophthalmology, 115, 865-872.

See Also

armd0, armd.wide

Examples

library(nlmeU)
data(armd)
summary(armd)

armd.wide Data (240 x 10)

Description

Data from Age-Related Macular Degeneration (ARMD) clinical trial

Usage

armd.wide

Format

A data frame with 240 rows and 10 columns:

subject

A factor with 240 levels: 1, 2, 3, 4, 5, ..., 240

lesion

An integer vector with values 1, 2, 3, 4

line0

An integer vector with values ranging from 5 to 17

visual0

An integer vector with values of visual acuity measured at baseline ranging from 20 to 85

visual4

An integer vector with values of visual acuity measured at 4 weeks ranging from 12 to 84

visual12

An integer vector with values of visual acuity measured at 12 weeks ranging from 3 to 85

visual24

An integer vector with values of visual acuity measured at 24 weeks ranging from 5 to 85

visual52

An integer vector with values of visual acuity measured at 52 weeks from 4 to 85

treat.f

A factor with 2 levels: Placebo, Active

miss.pat

A factor with 9 levels: ----, ---X, --X-, --XX, -XX-, ..., XXXX

Details

The ARMD data arise from a randomized multi-center clinical trial comparing an experimental treatment (interferon-alpha) versus placebo for patients diagnosed with ARMD.

Source

Pharmacological Therapy for Macular Degeneration Study Group (1997). Interferon alpha-IIA is ineffective for patients with choroidal neovascularization secondary to age-related macular degeneration. Results of a prospective randomized placebo-controlled clinical trial. Archives of Ophthalmology, 115, 865-872.

See Also

armd, armd0

Examples

data(armd.wide, package = "nlmeU")
summary(armd.wide)

armd0 Data (1107 x 8)

Description

Data from Age-Related Macular Degeneration (ARMD) clinical trial

Usage

armd0

Format

A data frame with 1107 rows and 8 columns:

subject

A factor with 240 levels: 1, 2, 3, 4, 5, ...

treat.f

A factor with 2 levels: Placebo, Active

visual0

An integer vector with values from 20 to 85

miss.pat

A factor with 9 levels: ----, ---X, --X-, --XX, -XX-, ...

time.f

A factor with 5 levels: Baseline, 4wks, 12wks, 24wks, 52wks

time

A numeric vector with values from 0 to 52

visual

An integer vector with values from 3 to 85

tp

A numeric vector with values from 0 to 4

Details

The ARMD data arise from a randomized multi-center clinical trial comparing an experimental treatment (interferon-alpha) versus placebo for patients diagnosed with ARMD.

Source

Pharmacological Therapy for Macular Degeneration Study Group (1997). Interferon alpha-IIA is ineffective for patients with choroidal neovascularization secondary to age-related macular degeneration. Results of a prospective randomized placebo-controlled clinical trial. Archives of Ophthalmology, 115, 865-872.

See Also

armd, armd.wide

Examples

data(armd0, package = "nlmeU")
summary(armd0)

fcat Data (4851 x 3)

Description

Data from Flemish Community Attainment-Targets (FCAT) Study

Usage

fcat

Format

A data frame with 4851 rows and 3 columns:

target

A factor with 9 levels: T1(4), T2(6), T3(8), T4(5), T5(9), ..., T9(5)

id

A factor with 539 levels: 1, 2, 3, 4, 5, ..., 539

scorec

An integer vector with values from 0 to 9

Details

An educational study, in which elementary school graduates were evaluated with respect to reading comprehension in Dutch. Pupils from randomly selected schools were assessed for a set of nine attainment targets. The dataset is an example of grouped data, for which the grouping factors are crossed.

Source

Janssen, R., Tuerlinckx, F., Meulders, M., & De Boeck, P. (2000). A hierarchical IRT model for criterion-referenced measurement. Journal of Educational and Behavioral Statistics, 25(3), 285.

Examples

data(fcat, package = "nlmeU")
summary(fcat)

Calculates contribution of one subject to the log-likelihood

Description

This function is generic; method functions can be written to handle specific classes of objects.

Usage

logLik1(modfit, dt1, dtInit)

Arguments

modfit

an object representing a model fitted to data using maximum likelihood estimation.

dt1

a data frame with data for one subject, for whom the log-likelihood function is to be evaluated.

dtInit

an optional auxiliary data frame.

Details

Calculates contribution of one subject to the log-likelihood

This function is generic; method functions can be written to handle specific classes of objects.

Value

Numeric scalar value representing the contribution of a given subject to the overall log-likelihood returned by logLik.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

References

Galecki, A., & Burzykowski, T. (2013). *Linear Mixed-Effects Models: A Step-by-Step Approach*. Springer.

Examples

  library(nlme)
  logLik(fm1 <- lme(distance ~ age, data = Orthodont)) # random is ~ age
  dt1 <- subset(Orthodont, Subject == "M01")
  logLik1(fm1, dt1)

Calculates contribution of one subject to the log-likelihood for an lme object

Description

This is a method for the logLik1 generic function.

Usage

## S3 method for class 'lme'
logLik1(modfit, dt1, dtInit)

Arguments

modfit

an lme object representing a model fitted using maximum likelihood.

dt1

a data frame with data for one subject, for whom the log-likelihood function is to be evaluated.

dtInit

an optional auxiliary data frame.

Details

Calculates the profile likelihood (with beta profiled out) for one subject. Data with one level of grouping only. The correlation component in modelStruct is not implemented.

Value

Numeric scalar value representing the contribution of a given subject to the overall log-likelihood returned by logLik applied to an lme object defined by the modfit argument.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

Examples


library(nlme)
data(armd, package = "nlmeU")
lm3.form <- visual ~ visual0 + time + treat.f 
fm16.5ml <- lme(lm3.form,                         
                random = list(subject = pdDiag(~time)), 
                weights = varPower(form = ~time),
                data = armd, method = "ML") # M16.5
df1 <- subset(armd, subject = "1")          # Panel R20.7
logLik1(fm16.5ml, df1)

Extract pattern of missing data

Description

This function compactly presents the pattern of missing data in a given vector, matrix, or data frame.

Usage

missPat(..., symbols = c("X", "-"), collapse = "", missData = FALSE)

Arguments

...

one or more vectors, matrices, or data frames, compatible for column-wise binding.

symbols

vector containing two single characters used to indicate NA and non-NA values. By default, c("X", "-").

collapse

an optional character string used in the internal call to paste() to separate results. By default, "".

missData

logical. If TRUE, a data frame with the pattern of missing values is saved in the missData attribute of the returned vector. By default, FALSE.

Value

Character vector with as many elements as the length of vector(s) or number of rows in matrices/data frames in .... Attribute cnames contains names of vectors/columns/variables. Optional attribute missData contains a data frame with the missing pattern.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

See Also

armd.wide

Examples

## Not run: 
  data(armd.wide, package = "nlmeU")
  dtf <- armd.wide[ , c("visual12", "visual24", "visual52")]
  missPat(dtf, symbols = c("?", "+"))

## End(Not run)

Print method for Pwr objects

Description

Prints the results of power calculations for objects of class Pwr.lme.

Usage

## S3 method for class 'Pwr'
print(x, verbose = attr(x, "verbose"), ...)

Arguments

x

an object of class Pwr.lme.

verbose

logical. If TRUE, additional information is printed. By default, uses the verbose attribute of x.

...

additional arguments passed to the method.

Value

Prints the power calculation results and returns NULL invisibly.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

prt Data (2471 x 9)

Description

Data from a Progressive Resistance Randomized Trial.

Usage

prt

Format

A data frame with 2471 rows and 9 columns:

id

A factor with 63 levels: 5, 10, 15, 20, 25, ..., 520 (subject id)

prt.f

A factor with 2 levels: High, Low, i.e., training (intervention) intensity

age.f

A factor with 2 levels: Young, Old (stratifying variable)

sex.f

A factor with 2 levels: Female, Male (stratifying variable)

bmi

A numeric vector with values of BMI at baseline ranging from 18.36 to 32.29

iso.fo

A numeric vector with values of isometric force ranging from 0.16 to 2.565

spec.fo

A numeric vector with values of specific force ranging from 80.5 to 290

occ.f

A factor with 2 levels: Pre, Pos, i.e., pre- and post-intervention

fiber.f

A factor with 2 levels: Type 1, Type 2, i.e., Type 1 and Type 2 muscle fiber

Details

Data frame prt was obtained by merging prt.subjects and prt.fiber.

Source

Claflin, D.R., Larkin, L.M., Cederna, P.S., Horowitz, J.F., Alexander, N.B., Cole, N.M., Galecki, A.T., Chen, S., Nyquist, L.V., Carlson, B.M., Faulkner, J.A., & Ashton-Miller, J.A. (2011). Effects of high- and low-velocity resistance training on the contractile properties of skeletal muscle fibers from young and older humans. Journal of Applied Physiology, 111, 1021-1030.

See Also

prt.fiber, prt.subjects

Examples

data(prt, package = "nlmeU")
summary(prt)

prt.fiber Data (2471 x 5)

Description

Data from a Progressive Resistance Randomized Trial.

Usage

prt.fiber

Format

A data frame with 2471 rows and 5 columns:

id

A factor with 63 levels: 5, 10, 15, 20, 25, ..., 520

iso.fo

A numeric vector with values of isometric force ranging from 0.16 to 2.565

spec.fo

A numeric vector with values of specific force ranging from 80.5 to 290

occ.f

A factor with 2 levels: Pre, Pos, i.e., pre- and post-intervention

fiber.f

A factor with 2 levels: Type 1, Type 2, i.e., Type 1 and Type 2 muscle fiber

Details

PRT trial was aimed for devising evidence-based methods for improving and measuring the mobility and muscle power of elderly men and women.

Source

Claflin, D.R., Larkin, L.M., Cederna, P.S., Horowitz, J.F., Alexander, N.B., Cole, N.M., Galecki, A.T., Chen, S., Nyquist, L.V., Carlson, B.M., Faulkner, J.A., & Ashton-Miller, J.A. (2011). Effects of high- and low-velocity resistance training on the contractile properties of skeletal muscle fibers from young and older humans. Journal of Applied Physiology, 111, 1021-1030.

See Also

prt, prt.subjects

Examples

data(prt.fiber, package = "nlmeU")
summary(prt.fiber)

prt.subjects Data (63 x 5)

Description

Data from a Progressive Resistance Randomized Trial.

Usage

prt.subjects

Format

A data frame with 63 rows and 5 columns:

id

A factor with 63 levels: 5, 10, 15, 20, 25, ...

prt.f

A factor with 2 levels: High, Low

age.f

A factor with 2 levels: Young, Old

sex.f

A factor with 2 levels: Female, Male

bmi

A numeric vector with values from 18.4 to 32.3

Details

The working hypothesis was that a 12-week program of PRT would increase: (a) the power output of the overall musculature associated with movements of the ankles, knees, and hips; (b) the cross-sectional area and the force and power of permeabilized single fibers obtained from the vastus lateralis muscle; and (c) the ability of young and elderly men and women to safely arrest standardized falls. The training consisted of repeated leg extensions by shortening contractions of the leg extensor muscles against a resistance that was increased as the subject trained using a specially designed apparatus.

Source

Claflin, D.R., Larkin, L.M., Cederna, P.S., Horowitz, J.F., Alexander, N.B., Cole, N.M., Galecki, A.T., Chen, S., Nyquist, L.V., Carlson, B.M., Faulkner, J.A., & Ashton-Miller, J.A. (2011). Effects of high- and low-velocity resistance training on the contractile properties of skeletal muscle fibers from young and older humans. Journal of Applied Physiology, 111, 1021-1030.

Examples

data(prt.subjects, package = "nlmeU")
summary(prt.subjects)

Execute scripts from Galecki and Burzykowski (2013)

Description

Executes scripts from the book by Galecki and Burzykowski (2013). If called without arguments, it prints a list of available scripts.

Usage

runScript(
  script = NA,
  package = "nlmeU",
  subdir = "scriptsR4.5.1",
  echo = TRUE
)

Arguments

script

character string containing the name of the script to be executed. By default, NA.

package

character string containing the package name. By default, "nlmeU".

subdir

subdirectory containing scripts. By default, "scriptsR2.15.0".

echo

logical. If TRUE, the script is executed with output printed. Used by source(). By default, TRUE.

Value

The script is executed, and results are printed. If script is NA, a list of available scripts is printed.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

References

Galecki, A., & Burzykowski, T. (2013). *Linear Mixed-Effects Models: A Step-by-Step Approach*. Springer.

Examples

runScript()

Simulates values of the dependent variable based on a model fit

Description

This function is generic; method functions can be written to handle specific classes of objects.

Usage

simulateY(object, nsim = 1, seed = NULL, ..., verbose = FALSE, sigma)

Arguments

object

an object with a model fit for which the dependent variable is to be simulated.

nsim

number of simulations. By default, nsim = 1.

seed

integer scalar used to initiate the random number generator.

...

some methods for this generic function may require additional arguments.

verbose

logical. If TRUE, basic information about arguments is provided. By default set to FALSE.

sigma

numeric scalar. Allows simulations employing an alternative value of the scale parameter.

Value

Numeric matrix with the number of columns determined by the nsim argument.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

Examples


## Not run: 
  library(nlme)
  fm1 <- lme(distance ~ age, data = Orthodont)
  simulateY(fm1)

## End(Not run)

Simulates values for an lme object

Description

This is a method for the simulateY generic function.

Usage

## S3 method for class 'lme'
simulateY(
  object,
  nsim = 1,
  seed = as.integer(runif(1, 0, .Machine$integer.max)),
  ...,
  verbose = FALSE,
  sigma
)

Arguments

object

an lme object with a model fit for which the dependent variable is to be simulated.

nsim

number of simulations. By default, nsim = 1.

seed

integer scalar used to initiate the random number generator.

...

some methods for this generic function may require additional arguments.

verbose

logical. If TRUE, basic information about arguments is provided. By default set to FALSE.

sigma

numeric scalar. Allows simulations employing an alternative value of the scale parameter.

Details

Simulates values of the dependent variable for a fitted lme model. Data with one level of grouping only.

Value

Numeric matrix with the number of columns determined by the nsim argument.

Author(s)

Andrzej Galecki and Tomasz Burzykowski

Examples


## Not run: 
  library(nlme)
  fm1 <- lme(distance ~ age, data = Orthodont)
  simulateY(fm1)

## End(Not run)