Help for package mvglmmRank

Type:

Package

Title:

Multivariate Generalized Linear Mixed Models for Ranking Sports Teams

Version:

1.2-5

Depends:

R (≥ 3.2.0), Matrix

Imports:

numDeriv, methods, stats, utils, MASS

Date:

2026-06-08

Description:

Maximum likelihood estimates are obtained via an EM algorithm with either a first-order or a fully exponential Laplace approximation as documented by Broatch and Karl (2018) <doi:10.48550/arXiv.1710.05284>, Karl, Yang, and Lohr (2014) <doi:10.1016/j.csda.2013.11.019>, and by Karl (2012) <doi:10.1515/1559-0410.1471>. Karl and Zimmerman <doi:10.1016/j.jspi.2020.06.004> use this package to illustrate how the home field effect estimator from a mixed model can be biased under nonrandom scheduling.

ByteCompile:

yes

LazyLoad:

yes

LazyData:

yes

License:

GPL-2

Encoding:

UTF-8

NeedsCompilation:

Author:

Andrew T. Karl

[cre, aut], Jennifer Broatch [aut]

Maintainer:

Andrew T. Karl <akarl@asu.edu>

Config/roxygen2/version:

8.0.0

Packaged:

2026-06-09 01:48:22 UTC; andre

Repository:

CRAN

Date/Publication:

2026-06-09 09:40:10 UTC

mvglmmRank: Multivariate generalized linear mixed models for ranking sports teams

Description

The package fits multivariate generalized linear mixed models for team scores, win/loss indicators, and margin-of-victory responses. Maximum likelihood estimates are obtained by an EM algorithm using either a first-order or fully exponential Laplace approximation.

Details

See mvglmmRank for the fitting interface and game.pred for printed game predictions from fitted models.

Author(s)

Maintainer: Andrew T. Karl akarl@asu.edu (ORCID)

Authors:

Andrew T. Karl akarl@asu.edu (ORCID)
Jennifer Broatch

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. doi:10.1016/j.jspi.2020.06.004.

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. 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). doi:10.1515/1559-0410.1471.

Internal Function for Normal-Binary Model

Description

Internal Function for Normal-Binary Model

Usage

NB_cre(Z_mat = Z_mat, first.order = first.order, 
   home.field = home.field, control = control)

Arguments

Z_mat

data frame

first.order

logical

home.field

logical

control

list

Internal Function for Normal-Binary Model

Description

Internal Function for Normal-Binary Model

Usage

NB_mov(Z_mat = Z_mat, first.order = first.order, 
   home.field = home.field, control = control)

Arguments

Z_mat

data frame

first.order

logical

home.field

logical

control

list

Internal Function for Normal MOV model

Description

Internal Function for Normal MOV model

Usage

N_mov(Z_mat = Z_mat, first.order = TRUE, 
   home.field = home.field, control = control)

Arguments

Z_mat

data frame

first.order

logical

home.field

logical

control

list

Internal Function for Poisson-binary Model

Description

Internal Function for Poisson-binary Model

Usage

PB_cre(Z_mat = Z_mat, first.order = first.order,
   home.field = home.field, control = control, 
   game.effect = game.effect)

Arguments

Z_mat

data frame

first.order

logical

home.field

logical

control

list

game.effect

logical

Internal function for binary model.

Description

An internal function.

Usage

binary_cre(Z_mat = Z_mat, first.order = first.order, 
          home.field, control = control)

Arguments

Z_mat

data frame.

first.order

logical

home.field

logical

control

list

2008 FBS College Football Regular Season Data

Description

2008 FBS College Football Regular Season Data

Usage

data(f2008)

Format

A data frame with 772 observations on the following 9 variables.

home: a factor
Game.Date: a POSIXlt date variable
away: a factor
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
neutral.site: a numeric vector
partition: a numeric vector

Source

http://web1.ncaa.org/mfb/download.jsp?year=2008&div=IA

Examples

data(f2008)
## maybe str(f2008) ; plot(f2008) ...

2009 FBS College Football Regular Season Data

Description

2009 FBS College Football Regular Season Data

Usage

data(f2009)

Format

A data frame with 772 observations on the following 7 variables.

home: a factor
Game.Date: a POSIXlt date variable
away: a factor
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
neutral.site: a numeric vector
partition: a numeric vector

Source

http://web1.ncaa.org/mfb/download.jsp?year=2009&div=IA

Examples

data(f2009)
## maybe str(f2009) ; plot(f2009) ...

2010 FBS College Football Regular Season Data

Description

2010 FBS College Football Regular Season Data

Usage

data(f2010)

Format

A data frame with 770 observations on the following 9 variables.

home: a factor
Game.Date: a POSIXlt
away: a factor
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
neutral.site: a numeric vector
partition: a numeric vector

Source

http://web1.ncaa.org/mfb/download.jsp?year=2010&div=IA

Examples

data(f2010)
## maybe str(f2010) ; plot(f2010) ...

2011 FBS College Football Regular Season Data

Description

2011 FBS College Football Regular Season Data

Usage

data(f2011)

Format

A data frame with 781 observations on the following 9 variables.

home: a factor
Game.Date: a POSIXlt
away: a factor
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
neutral.site: a numeric vector
partition: a numeric vector

Source

http://web1.ncaa.org/mfb/download.jsp?year=2011&div=IA

Examples

data(f2011)
## maybe str(f2011) ; plot(f2011) ...

2012 FBS College Football Regular Season Data

Description

2012 FBS College Football Regular Season Data

Usage

data(f2012)

Format

A data frame with 809 observations on the following 9 variables.

home: a factor
Game.Date: a POSIXlt
away: a factor
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
neutral.site: a numeric vector
partition: a numeric vector

Source

http://web1.ncaa.org/mfb/download.jsp?year=2012&div=IA

Examples

data(f2012)
## maybe str(f2012) ; plot(f2012) ...

Print predictions for a future game

Description

Uses a fitted mvglmmRank object to print predicted scores, win probability, and/or margin of victory for a specified matchup.

Usage

game.pred(res, home, away, neutral.site = FALSE)

Arguments

res

An object of class "mvglmmRank" returned by mvglmmRank.

home

Character string naming the home team. The name should match a team name in the fitted object.

away

Character string naming the away team. The name should match a team name in the fitted object.

neutral.site

Logical. If TRUE and res was fit with home.field = TRUE using data that included neutral-site games, use the neutral-site score mean and omit the binary home-field effect in the printed prediction. If res was fit with home.field = FALSE, this argument has no additional effect because no home-field fixed effect was modeled.

Details

Neutral-site predictions require the training data supplied to mvglmmRank to contain neutral.site = 1 games. If a fitted score model has no neutral-site mean, neutral-site score predictions may be unavailable.

Value

Prints predictions and returns NULL invisibly.

References

Karl, A.T. (2012). The Sensitivity of College Football Rankings to Several Modeling Choices. Journal of Quantitative Analysis in Sports, 8(3). 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")

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

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. (2012). The Sensitivity of College Football Rankings to Several Modeling Choices. Journal of Quantitative Analysis in Sports, 8(3). 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")

2013 NBA Data

Description

2013 NBA Data

Usage

data(nba2013)

Format

A data frame with 1229 observations on the following 11 variables.

Date: a factor
away: a factor
home: a factor
OT: a factor
partition: a numeric vector
neutral.site: a numeric vector
ot.count: a numeric vector
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector

Source

http://masseyratings.com/data.php

Examples

data(nba2013)
## maybe str(nba2013) ; plot(nba2013) ...

2012 NCAA Division I Basketball Results

Description

2012 NCAA Division I Basketball Results

Usage

data(ncaab2012)

Format

A data frame with 5253 observations on the following 10 variables.

date: a factor
away: a factor
home: a factor
neutral.site: a numeric vector
partition: a numeric vector
home_win: a numeric vector
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector

Source

http://masseyratings.com/data.php

Examples

data(ncaab2012)
## maybe str(ncaab2012) ; plot(ncaab2012) ...

2012 NFL Regular Season Data

Description

2012 NFL Regular Season Data

Usage

data(nfl2012)

Format

A data frame with 256 observations on the following 9 variables.

Date: a factor
away: a factor
home: a factor
neutral.site: a numeric vector
home.response: a numeric vector
home.score: a numeric vector
away.response: a numeric vector
away.score: a numeric vector
partition: a numeric vector

Source

http://masseyratings.com/data.php

Examples

data(nfl2012)
## maybe str(nfl2012) ; plot(nfl2012) ...

Internal Function for Normal Model

Description

Internal Function for Normal Model

Usage

normal_cre(Z_mat = Z_mat, first.order = first.order, 
   home.field = home.field, control = control)

Arguments

Z_mat

data frame

first.order

logical

home.field

logical

control

list

Internal Function for Poisson Model

Description

Internal Function for Poisson Model

Usage

poisson_cre(Z_mat = Z_mat, first.order = first.order, 
   control = control, game.effect = game.effect, 
   home.field = home.field)

Arguments

Z_mat

data frame

first.order

logical

control

logical

game.effect

logical

home.field

logical

Package {mvglmmRank}

mvglmmRank: Multivariate generalized linear mixed models for ranking sports teams

Description

Details

Author(s)

References

Internal Function for Normal-Binary Model

Description

Usage

Arguments

Internal Function for Normal-Binary Model

Description

Usage

Arguments

Internal Function for Normal MOV model

Description

Usage

Arguments

Internal Function for Poisson-binary Model

Description

Usage

Arguments

Internal function for binary model.

Description

Usage

Arguments

2008 FBS College Football Regular Season Data

Description

Usage

Format

Source

Examples

2009 FBS College Football Regular Season Data

Description

Usage

Format

Source

Examples

2010 FBS College Football Regular Season Data

Description

Usage

Format

Source

Examples

2011 FBS College Football Regular Season Data

Description

Usage

Format

Source

Examples

2012 FBS College Football Regular Season Data

Description

Usage

Format

Source

Examples

Print predictions for a future game

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Fit multivariate generalized linear mixed models for sports rankings

Description

Usage

Arguments

Details

Value

References

See Also

Examples

2013 NBA Data

Description

Usage

Format

Source

Examples