| GPvam | R Documentation |
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).
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
)
vam_data |
A data frame containing |
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,
|
student.side |
Character string, either |
persistence |
Character string selecting |
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 |
tol1 |
Positive finite convergence tolerance for the relative change
in log likelihood. The default is |
hessian |
Logical; calculate the observed information for covariance
parameters and, for |
hes.method |
Numerical differentiation method for the information
matrix: |
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. |
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.
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 ( |
parameters |
Matrix of fixed-effect, covariance, and applicable
persistence estimates with their standard errors. Covariance and
persistence standard errors are |
Hessian |
Observed information matrix for covariance and persistence
parameters when requested, otherwise |
R_i |
Within-student residual covariance for R-side models;
|
teach.cov |
List of teacher covariance blocks, one per originating year. |
stu.cov |
Student random-effect variance for a G-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 |
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.
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.
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.
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.
Andrew Karl akarl@asu.edu, Yan Yang and Sharon Lohr.
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.
plot.GPvam, summary.GPvam,
bias.test.custom, vam_data
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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.