mvglmmRank: Fit multivariate generalized linear mixed models for sports...
In mvglmmRank: Multivariate Generalized Linear Mixed Models for Ranking Sports Teams

mvglmmRank

R Documentation

Fit multivariate generalized linear mixed models for sports rankings

Description

Fits one of several generalized linear mixed models for team scores, win/loss indicators, or margin of victory. The fitted random effects are used as team ratings.

Usage

mvglmmRank(
  game.data,
  method = "PB0",
  first.order = FALSE,
  home.field = TRUE,
  max.iter.EM = 1000,
  tol1 = 1e-04,
  tol2 = 1e-04,
  tolFE = 0,
  tol.n = 1e-07,
  verbose = TRUE,
  OT.flag = FALSE,
  Hessian = FALSE,
  REML.N = TRUE
)

Arguments

`game.data`	A data frame with columns `home`, `away`, `home.response`, and `away.response`. The optional column `binary.response` should contain binary home-team outcomes; if it is omitted, `mvglmmRank()` creates a home-win indicator from the score columns. The optional column `neutral.site` should be `1` for neutral-site games and `0` otherwise; if omitted, all games are treated as non-neutral. If `OT.flag = TRUE`, `game.data` should also contain a numeric `OT` column with no missing values.
`method`	Character string naming the model to fit. Choices are `"B"`, `"P0"`, `"P1"`, `"N"`, `"NB"`, `"PB0"`, `"PB1"`, `"NB.mov"`, and `"N.mov"`.
`first.order`	Logical. If `TRUE`, use only the first-order Laplace approximation. If `FALSE`, continue to the fully exponential Laplace approximation where supported.
`home.field`	Logical. If `TRUE`, include home-field fixed effects: score models use separate home and away mean scores, plus a neutral-site mean score when neutral-site games are present, and binary models include a home-field effect. If `FALSE`, score models use a single mean score and binary models use no fixed home-field effect. For margin-of-victory methods, `home.field = FALSE` omits the fixed home margin effect.
`max.iter.EM`	Maximum number of EM iterations.
`tol1`	Convergence tolerance for the first-order Laplace approximation, based on the maximum relative parameter change.
`tol2`	Convergence tolerance for the fully exponential Laplace approximation. Not used when `first.order = TRUE`.
`tolFE`	Intermediate convergence tolerance for the fully exponential approximation. Corrections to the random-effects covariance matrix begin after this tolerance is reached.
`tol.n`	Convergence tolerance for the normal models. Convergence is declared when `(l_k-l_{k-1})/l_k < tol.n`, where `l_k` is the log-likelihood at iteration `k`.
`verbose`	Logical. If `TRUE`, print iteration information.
`OT.flag`	Logical. If `TRUE`, include the numeric `OT` column as a score-model fixed effect. Use `0` for games without overtime.
`Hessian`	Logical. If `TRUE`, approximate the Hessian of the model parameters by central differences.
`REML.N`	Logical. If `TRUE`, use REML estimation for `method = "N"` and `method = "N.mov"`.

Details

The available methods are:

"B": Binary/probit model for home win/loss indicators.
"P0": Poisson score model without a game-level random effect.
"P1": Poisson score model with a game-level random effect.
"N": Normal score model with an unstructured within-game error covariance matrix.
"NB": Joint normal score and binary/probit win/loss model.
"PB0": Joint Poisson score and binary/probit win/loss model without a game-level random effect.
"PB1": Joint Poisson score and binary/probit win/loss model with a game-level random effect.
"NB.mov": Joint normal margin-of-victory and binary/probit win/loss model.
"N.mov": Normal margin-of-victory model.

Neutral-site games are represented in game.data$neutral.site. Use 1 for neutral-site games and 0 otherwise. For neutral-site games, the teams may be assigned to the home and away columns arbitrarily. With home.field = TRUE, score models estimate a neutral-site mean score when neutral-site games are present. With home.field = FALSE, the home/away and neutral-site mean structure is suppressed.

Setting first.order = TRUE yields the first-order Laplace approximation. A partial fully exponential Laplace approximation can be obtained by setting tol1 > tol2 and tolFE = 0. This applies fully exponential corrections to the vector of team ratings, but not to the covariance matrix of this vector. Karl, Yang, and Lohr (2014) show that this approach produces a large portion of the benefit of the fully exponential Laplace approximation in only a fraction of the time.

The "PB1" method is the least scalable, as its memory and computational requirements are at least quadratic in the number of teams plus the number of games.

Value

An object of class "mvglmmRank". The object is a list whose components depend on method and may include:

n.ratings.offense, n.ratings.defense: Normal-model offensive and defensive ratings, or NULL.
p.ratings.offense, p.ratings.defense: Poisson-model offensive and defensive ratings, or NULL.
b.ratings: Binary/probit win-propensity ratings, or NULL.
n.ratings.mov: Normal margin-of-victory ratings, or NULL.
n.mean, p.mean, b.mean: Estimated fixed-effect means or home-field effects for the fitted model components.
G, G.cor: Random-effects covariance and correlation matrices.
R, R.cor: Normal-model error covariance and correlation matrices, or NULL.
home.field: Logical indicating whether a home-field effect was modeled.
Hessian: Numerical Hessian if requested, otherwise NULL.
parameters: Vector of fitted model parameters.
actual, pred, sresid: Observed values, fitted values, and scaled residuals where available.
N.output: Additional normal-model matrices and covariance output for method = "N" and method = "N.mov".
fixed.effect.model.output: Additional fixed-effect margin-of-victory output for method = "N.mov".
method: The model method supplied by the user.

References

Broatch, J.E. and Karl, A.T. (2018). Multivariate Generalized Linear Mixed Models for Joint Estimation of Sporting Outcomes. Italian Journal of Applied Statistics, 30(2), 189-211. Also available from https://arxiv.org/abs/1710.05284.

Karl, A.T. and Zimmerman, D.L. (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")}.

Karl, A.T., 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 and Data Analysis, 59, 13-27.

Karl, A.T., 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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.csda.2013.11.019")}.

Karl, A.T. (2012). The Sensitivity of College Football Rankings to Several Modeling Choices. Journal of Quantitative Analysis in Sports, 8(3). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1515/1559-0410.1471")}.

Examples

data(nfl2012)
fit <- mvglmmRank(nfl2012, method = "PB0", first.order = TRUE,
                  max.iter.EM = 1, verbose = FALSE)
game.pred(fit, home = "Denver Broncos", away = "Green Bay Packers")


result <- mvglmmRank(nfl2012, method = "PB0", first.order = TRUE,
                     verbose = FALSE)
print(result)
game.pred(result, home = "Denver Broncos", away = "Green Bay Packers")

mvglmmRank documentation built on June 9, 2026, 5:08 p.m.