GPvam: Fit a Generalized or Variable Persistence Model

View source: R/GPvam.R

GPvamR Documentation

Fit a Generalized or Variable Persistence Model

Description

Fit a multiple-membership linear mixed model by an EM algorithm. Teacher effects may persist into future years, and dependence among a student's observations is represented by a residual covariance matrix or a random student effect. See Karl, Yang and Lohr (2013) and Mariano et al. (2010).

Usage

GPvam(
  vam_data,
  fixed_effects = formula(~as.factor(year) + 0),
  student.side = "R",
  persistence = "GP",
  max.iter.EM = 1000,
  tol1 = 1e-07,
  hessian = FALSE,
  hes.method = "simple",
  REML = TRUE,
  verbose = TRUE
)

Arguments

vam_data

A data frame containing y (numeric student score), student (student identifier), teacher (teacher identifier), and year (numeric year or other ordered time period), together with any fixed-effect covariates. There must be at most one row per student and year. Student identifiers and years must not be missing. Scores and teacher identifiers may be NA; fixed-effect covariates must be complete on rows with observed scores. Unused columns are ignored. See ‘Missing data’ below.

fixed_effects

A one-sided formula specifying fixed effects. The default estimates a separate mean for each year, or an intercept if there is only one year. Use factors for categorical covariates; for example, ~ as.factor(year) + cont_var + 0 also includes a continuous covariate. Offsets and the reserved variable names mis, pat, and r are not supported in this formula.

student.side

Character string, either "R" for an unstructured within-student residual covariance or "G" for a random student intercept and year-specific residual variances. A G-side model requires repeated observed scores for at least one student.

persistence

Character string selecting "GP", "rGP", "VP", "CP", or "ZP". Only "GP" is supported with student.side = "G". See ‘Persistence models’ below.

max.iter.EM

Positive integer giving the maximum number of EM iterations. A fit that reaches this limit without convergence is returned with a warning and converged = FALSE.

tol1

Positive finite convergence tolerance for the relative change in log likelihood. The default is 1e-7.

hessian

Logical; calculate the observed information for covariance parameters and, for persistence = "VP", persistence parameters. This supplies their standard errors. Fixed-effect standard errors and teacher prediction-error standard deviations are computed regardless. Covariance/persistence standard errors are NA when the information matrix cannot be computed or is not positive definite.

hes.method

Numerical differentiation method for the information matrix: "simple" or "richardson".

REML

Logical; use restricted maximum likelihood (the default) rather than maximum likelihood. Supported for every available persistence/student-side combination.

verbose

Logical; print model information and iteration progress.

Details

The model is fitted by an EM algorithm based on Karl, Yang and Lohr (2013). Covariance updates use conditional random-effect moments for ML and prediction-error covariance adjustments for REML; see Karl (2026). With incomplete observation patterns, the unstructured residual covariance update uses a Cholesky parameterization to retain positive definiteness. Setting hessian = TRUE adds numerical differentiation after fitting and can substantially increase runtime. Historical timings are available in GPvam.benchmark.

Fixed-effect standard errors and teacher prediction-error standard deviations use the inverse mixed-model coefficient matrix with estimated covariance parameters treated as known. They do not include an additional adjustment for uncertainty in those covariance estimates.

Value

An object of class GPvam, a list that includes:

loglik

Log likelihood (restricted log likelihood for REML) at the returned fit. Meeting the relative-change convergence criterion does not guarantee a global maximum.

converged

Whether the convergence criterion was met.

iter, loglik_history

Number of evaluated iterations and the corresponding sequence of log likelihoods.

teach.effects

Data frame containing teacher identifiers, originating and effect years, predicted effects (EBLUP), and prediction-error standard deviations (std_error).

parameters

Matrix of fixed-effect, covariance, and applicable persistence estimates with their standard errors. Covariance and persistence standard errors are NA unless hessian = TRUE.

Hessian

Observed information matrix for covariance and persistence parameters when requested, otherwise NA.

R_i

Within-student residual covariance for R-side models; NA for G-side models.

teach.cov

List of teacher covariance blocks, one per originating year.

stu.cov

Student random-effect variance for a G-side model; NA for an R-side model.

mresid, cresid, sresid

Marginal residuals, conditional residuals, and conditional residuals scaled using the residual precision matrix.

y, yhat, yhat.m, yhat.s

Observed responses, conditional fitted values, marginal fitted values, and scaled conditional fitted values, in the internal fitting order.

X, Z, G, R.inv, vinv

Fixed- and random-effects design matrices, random-effects covariance, residual precision, and marginal precision.

ybetas, eta.hat

Unrounded fixed-effect estimates and random-effect predictions.

num.obs, num.student, num.year, num.teach

Observation, student, year, and per-year teacher counts.

persistence, student.side, REML

The fitted model and estimation options.

key

Mapping between original year values and internal year indices.

observation

Input-row indices in the internal fitting order.

simulation_spec

Original student/year/teacher row keys, observed-score pattern, collation locale, and resolved numerical controls used by simulate_bias. These keys are private input metadata, not an aggregate summary.

call, fixed_effects

Original model call and fixed-effects formula.

Use the standard GPvam-methods to extract full-precision fixed-effect estimates and covariances, fitted values, residuals, likelihood, and observation count. The fitted-value and residual methods return observations in input order with missing responses omitted.

Persistence models

The generalized persistence model ("GP") assigns each teacher correlated current-year and future-year effects. The reduced model ("rGP") combines a teacher's future-year effects into one shared effect. The variable persistence model ("VP") makes a teacher's future-year effects multiples of the current-year effect and estimates those multipliers. Complete ("CP") and zero ("ZP") persistence fix the multipliers at one and zero, respectively.

With student.side = "R", an unstructured covariance matrix models within-student dependence. With student.side = "G", a random student intercept represents that dependence and the remaining errors are independent, with a separate variance for each year. The latter formulation assumes that scores across years use a common scale and can have substantial memory requirements for large numbers of random effects.

Missing data

A missing score is omitted from the response used for fitting. A known teacher assignment on that row is retained in the student's teaching history and can contribute persistent effects to later observed scores. A missing teacher identifier represents an unknown assignment, not a teacher named "NA"; no teacher effect is attached to that assignment.

Note

Each teacher-year is a separate unit. If the same teacher identifier appears in different years, the corresponding effects are modeled independently. Internally, a year suffix is added to each known teacher identifier, and the original year labels are retained in the output. Before evaluating fixed_effects, years are recoded to consecutive numeric indices in increasing order. Thus ~ year specifies a linear trend across those indices. To use the original numerical spacing, copy the original years into a separate covariate and use that covariate in the formula.

The fixed-effects design must have full column rank. Use ~ as.factor(year) * cont_var + 0 to include year-specific slopes; see formula for formula syntax.

Author(s)

Andrew Karl akarl@asu.edu, Yan Yang and Sharon Lohr.

References

Karl, A. T. (2026). Motivating REML via Prediction-Error Covariances in EM Updates for Linear Mixed Models. arXiv:2602.09247v1. https://arxiv.org/abs/2602.09247.

Karl, A., Yang, Y. and Lohr, S. (2013). Efficient Maximum Likelihood Estimation of Multiple Membership Linear Mixed Models, with an Application to Educational Value-Added Assessments. Computational Statistics & Data Analysis 59, 13–27. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.csda.2012.10.004")}.

Karl, A., Yang, Y. and Lohr, S. (2014). Computation of Maximum Likelihood Estimates for Multiresponse Generalized Linear Mixed Models with Non-nested, Correlated Random Effects. Computational Statistics & Data Analysis 73, 146–162.

Karl, A., Yang, Y. and Lohr, S. (2013). A Correlated Random Effects Model for Nonignorable Missing Data in Value-Added Assessment of Teacher Effects. Journal of Educational and Behavioral Statistics 38, 577–603. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3102/1076998613494819")}.

Karl, A. and Zimmerman, D. (2021). A diagnostic for bias in linear mixed model estimators induced by dependence between the random effects and the corresponding model matrix. Journal of Statistical Planning and Inference 211, 107–118. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.jspi.2020.06.004")}.

Lockwood, J., McCaffrey, D., Mariano, L. and Setodji, C. (2007). Bayesian Methods for Scalable Multivariate Value-Added Assessment. Journal of Educational and Behavioral Statistics 32, 125–150.

Mariano, L., McCaffrey, D. and Lockwood, J. (2010). A Model for Teacher Effects From Longitudinal Data Without Assuming Vertical Scaling. Journal of Educational and Behavioral Statistics 35, 253–279. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3102/1076998609346967")}.

McCaffrey, D. and Lockwood, J. (2011). Missing Data in Value-Added Modeling of Teacher Effects. Annals of Applied Statistics 5, 773–797.

See Also

plot.GPvam, summary.GPvam, bias.test.custom, vam_data

Examples

data(vam_data)

result <- GPvam(vam_data, persistence = "CP",
                fixed_effects = ~ as.factor(year) + cont_var + 0,
                verbose = FALSE)
summary(result)
plot(result, ask = FALSE)


GPvam documentation built on Oct. 23, 2026, 1:06 a.m.