Movatterモバイル変換

The Elo Package

Description

An implementation of Elo ratings for general use in 'R'.

Functions

Listed below are the most useful functions available inelo:

elo.prob: Calculate the probability that team A beats team B.

elo.update: Calculate the update value for a given Elo matchup.

elo.calc: Calculate post-update Elo values.

elo.run: Calculate Elos for a series of matches.

score: Create a 1/0/0.5 win "indicator" based on two teams' scores.

Data

tournament: Mock data for examples.

References

Elo, A. E. 1978. The Rating of Chess Players, Past and Present. New York: Arco.

Examples

library(elo)

Calculate AUC on anelo.run object

Description

Calculate AUC on anelo.run object

Usage

## S3 method for class 'elo.run'auc(object, ..., subset = TRUE)## S3 method for class 'elo.glm'auc(object, ..., subset = TRUE)## S3 method for class 'elo.running'auc(object, running = TRUE, discard.skipped = FALSE, ..., subset = TRUE)## S3 method for class 'elo.markovchain'auc(object, ..., subset = TRUE)## S3 method for class 'elo.winpct'auc(object, ..., subset = TRUE)## S3 method for class 'elo.colley'auc(object, ..., subset = TRUE)

Arguments

Value

The AUC of the predicted Elo probabilities and the actual win results.

References

Adapted from code here:https://stat.ethz.ch/pipermail/r-help/2005-September/079872.html

See Also

pROC::auc,elo.run.

Post-update Elo values

Description

Calculate post-update Elo values. This is vectorized.

Usage

elo.calc(wins.A, ...)## Default S3 method:elo.calc(wins.A, elo.A, elo.B, k, ..., adjust.A = 0, adjust.B = 0)## S3 method for class 'formula'elo.calc(formula, data, na.action, subset, k = NULL, ...)

Arguments

Value

A data.frame with two columns, giving the new Elo values after each update.

See Also

elo.prob,elo.update,elo.model.frame

Examples

elo.calc(c(1, 0), c(1500, 1500), c(1500, 1600), k = 20)dat <- data.frame(wins.A = c(1, 0), elo.A = c(1500, 1500),                  elo.B = c(1500, 1600), k = c(20, 20))elo.calc(wins.A ~ elo.A + elo.B + k(k), data = dat)

Compute a Colley matrix model for a matchup.

Description

Compute a Colley matrix model for a matchup.

Usage

elo.colley(  formula,  data,  family = "binomial",  weights,  na.action,  subset,  k = 1,  ...,  running = FALSE,  skip = 0)

Arguments

Details

See the vignette for details on this method.The differences in assigned scores (from the coefficients of the Colley matrix regression) are fed into a logisticregression model to predict wins or (usually) a linear model to predict margin of victory.In this setting, 'k' indicates the fraction of a win to be assigned to the winning team(and the fraction of a loss to be assigned to the losing team); settingk = 1 (the default)emits the "Bias Free" ranking method presented by Colley.It is also possible to adjust the regression by setting the second argument ofadjust(). As inelo.glm,the intercept represents the home-field advantage. Neutral fields can be indicatedusing theneutral() function, which sets the intercept to 0.

References

Colley W.N. Colley's Bias Free College Football Ranking Method: The Colley Matrix Explained. 2002.

See Also

glm,summary.elo.colley,score,mov,elo.model.frame

Examples

elo.colley(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  subset = points.Home != points.Visitor)

Compute a (usually logistic) regression model for a series of matches.

Description

Compute a (usually logistic) regression model for a series of matches.

Usage

elo.glm(  formula,  data,  family = "binomial",  weights,  na.action,  subset,  ...,  running = FALSE,  skip = 0)

Arguments

Details

The formula syntax is the same as otherelo functions. A data.frameof indicator variables is built, where an entry is 1 if a team is home, 0 ifa team didn't play, and -1 if a team is a visitor. Anything passed toadjust() informula is also put in the data.frame. Aglm model is thenrun to predict wins or margin of victory.

With this setup, the intercept represents the home-field advantage. Neutral fields can be indicatedusing theneutral() function, which sets the intercept to 0.

Note that any weights specified inplayers() will be ignored.

This is essentially the Bradley-Terry model.

Value

An object of classc("elo.glm", "glm"). Ifrunning==TRUE, the class"elo.glm.running"is prepended.

References

https://en.wikipedia.org/wiki/Bradley

See Also

glm,summary.elo.glm,score,mov,elo.model.frame

Examples

data(tournament)elo.glm(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  subset = points.Home != points.Visitor)elo.glm(mov(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  family = "gaussian")

Compute a Markov chain model for a series of matches.

Description

Compute a Markov chain model for a series of matches.

Usage

elo.markovchain(  formula,  data,  family = "binomial",  weights,  na.action,  subset,  k = NULL,  ...,  running = FALSE,  skip = 0)

Arguments

Details

See the vignette for details on this method. The probabilities we call 'k' purely for convenience.The differences in assigned scores (from the stationary distribution pi) are fed into a logisticregression model to predict wins or (usually) a linear model to predict margin of victory.It is also possible to adjust the regression by setting the second argument ofadjust(). As inelo.glm,the intercept represents the home-field advantage. Neutral fields can be indicatedusing theneutral() function, which sets the intercept to 0.

Note that by assigning probabilities in the right way, this function emits theLogistic Regression Markov Chain model (LRMC).

References

Kvam, P. and Sokol, J.S. A logistic regression/Markov chain model for NCAA basketball.Naval Research Logistics. 2006. 53; 788-803.

See Also

glm,summary.elo.markovchain,score,mov,elo.model.frame

Examples

elo.markovchain(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  subset = points.Home != points.Visitor, k = 0.7)elo.markovchain(mov(points.Home, points.Visitor) ~ team.Home + team.Visitor, family = "gaussian",  data = tournament, k = 0.7)

Interpret formulas inelo functions

Description

A helper function to create themodel.frame for manyelo functions.

Usage

elo.model.frame(  formula,  data,  na.action,  subset,  k = NULL,  ...,  required.vars = "elos",  warn.k = TRUE,  ncol.k = 1,  ncol.elos = 2)

Arguments

See Also

elo.run,elo.calc,elo.update,elo.prob

Create a "margin of victory" column

Description

Create a "margin of victory" based on two teams' scores

Usage

mov(score.A, score.B = 0)

Arguments

Value

An object with class"elo.mov", denotingscore.A =score.B.

See Also

score

Examples

mov(12, 10)mov(10, 10)mov(10, 12)

Calculate the mean square error

Description

Calculate the mean square error (Brier score) for a model.

Usage

mse(object, ..., subset = TRUE)brier(object, ..., subset = TRUE)## S3 method for class 'elo.run'mse(object, ..., subset = TRUE)## S3 method for class 'elo.glm'mse(object, ..., subset = TRUE)## S3 method for class 'elo.running'mse(object, running = TRUE, discard.skipped = FALSE, ..., subset = TRUE)## S3 method for class 'elo.markovchain'mse(object, ..., subset = TRUE)## S3 method for class 'elo.winpct'mse(object, ..., subset = TRUE)## S3 method for class 'elo.colley'mse(object, ..., subset = TRUE)

Arguments

Details

Even though logistic regressions don't use the MSE on the y=0/1 scale, it can still be informative.Note that the S3 method ismse.

Elo probability

Description

Calculate the probability that team A beats team B. This is vectorized.

Usage

elo.prob(elo.A, ...)## Default S3 method:elo.prob(elo.A, elo.B, ..., elos = NULL, adjust.A = 0, adjust.B = 0)## S3 method for class 'formula'elo.prob(formula, data, na.action, subset, ..., elos = NULL)## S3 method for class 'elo.multiteam.matrix'elo.prob(elo.A, ..., elos = NULL)

Arguments

Details

Note thatformula can be missing thewins.A component. Ifpresent, it's ignored byelo.model.frame.

Value

A vector of Elo probabilities.

See Also

elo.update,elo.calc,elo.model.frame

Examples

elo.prob(1500, 1500)elo.prob(c(1500, 1500), c(1500, 1600))dat <- data.frame(wins.A = c(1, 0), elo.A = c(1500, 1500),                  elo.B = c(1500, 1600), k = c(20, 20))elo.prob(~ elo.A + elo.B, data = dat)## Also works to include the wins and k:elo.prob(wins.A ~ elo.A + elo.B + k(k), data = dat)## Also allows teamselo.prob(c("A", "B"), c("C", "C"), elos = c(A = 1500, B = 1600, C = 1500))

Calculate running Elos for a series of matches.

Description

Calculate running Elos for a series of matches.

Usage

elo.run(  formula,  data,  na.action,  subset,  k = NULL,  initial.elos = NULL,  ...,  prob.fun = elo.prob,  update.fun = elo.update,  verbose = TRUE)

Arguments

Details

elo.run is run two different ways: the first (default) uses C++ and may be up to 50 times faster,while the second (whenprob.fun orupdate.fun are specified) uses R but also supports custom update functions.Prefer the first unless you really need a custom update function.

Value

An object of class"elo.run" or class"elo.run.regressed".

See Also

score,elo.run.helperselo.run helpers,elo.calc,elo.update,elo.prob,elo.model.frame.

Examples

data(tournament)elo.run(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,        data = tournament, k = 20)# Create non-constant 'k'elo.run(score(points.Home, points.Visitor) ~ team.Home + team.Visitor +        k(20*log(abs(points.Home - points.Visitor) + 1)), data = tournament)# Adjust Elo for, e.g., home-field advantageelo.run(score(points.Home, points.Visitor) ~ adjust(team.Home, 30) + team.Visitor,        data = tournament, k = 20)tournament$home.field <- 30elo.run(score(points.Home, points.Visitor) ~ adjust(team.Home, home.field) + team.Visitor,        data = tournament, k = 20)# Regress the Elos back toward 1500 at the end of the half-seasonelo.run(score(points.Home, points.Visitor) ~ adjust(team.Home, 30) +        team.Visitor + regress(half, 1500, 0.2), data = tournament, k = 20)

Helper functions forelo.run

Description

as.matrix converts an Elo object into a matrix of running Elos. These are the Elos at the time of grouping,but before any regression takes place.

Usage

## S3 method for class 'elo.run'as.matrix(x, ...)## S3 method for class 'elo.run.regressed'as.matrix(x, ...)## S3 method for class 'elo.run'as.data.frame(x, ...)final.elos(x, ...)## S3 method for class 'elo.run'final.elos(x, ...)## S3 method for class 'elo.run.regressed'final.elos(x, regressed = FALSE, ...)

Arguments

Details

as.data.frame converts the"elos" component of an objectfromelo.run into a data.frame.

final.elos is a generic function to extract the last Elo per team.

Value

A matrix, a data.frame, or a named vector.

See Also

elo.run

Examples

e <- elo.run(score(points.Home, points.Visitor) ~ team.Home + team.Visitor + group(week),             data = tournament, k = 20)head(as.matrix(e))str(as.data.frame(e))final.elos(e)

Calculate running Elos for a series of multi-team matches.

Description

Calculate running Elos for a series of multi-team matches.

Usage

elo.run.multiteam(  formula,  data,  na.action,  subset,  k = NULL,  initial.elos = NULL,  ...)

Arguments

Details

This is likeelo.run (and in fact it runselo.run in the background).The formula takes amultiteam() object, which assumes that teams "win"in a well-ordered ranking. It assumes that the first place team beats all other teams,that the second place team loses to the first but beats the others, etc. In that regard,elo.run.multiteam reduces toelo.run when the number of teams (ncol(multiteam())) is 2

However, this is less flexible thanelo.run, because (1) there cannot be ties; (2) it does not acceptadjustments; and (3) k is constant within a "game"

Examples

data(tournament.multiteam)elo.run.multiteam(~ multiteam(Place_1, Place_2, Place_3, Place_4),                  data = tournament.multiteam, subset = -28, k = 20)

Elo updates

Description

Calculate the update value for a given Elo matchup. This is used inelo.calc, which reports the post-update Elo values. This is vectorized.

Usage

elo.update(wins.A, ...)## Default S3 method:elo.update(wins.A, elo.A, elo.B, k, ..., adjust.A = 0, adjust.B = 0)## S3 method for class 'formula'elo.update(formula, data, na.action, subset, k = NULL, ...)

Arguments

Value

A vector of Elo updates.

See Also

elo.prob,elo.calc,elo.model.frame

Examples

elo.update(c(1, 0), c(1500, 1500), c(1500, 1600), k = 20)dat <- data.frame(wins.A = c(1, 0), elo.A = c(1500, 1500),                  elo.B = c(1500, 1600), k = c(20, 20))elo.update(wins.A ~ elo.A + elo.B + k(k), data = dat)

Compute a (usually logistic) regression based on win percentage for a series of matches.

Description

Compute a (usually logistic) regression based on win percentage for a series of matches.

Usage

elo.winpct(  formula,  data,  family = "binomial",  weights,  na.action,  subset,  ...,  running = FALSE,  skip = 0)

Arguments

Details

Win percentages are first calculated. Anything passed toadjust() informula is also put in the data.frame. Aglm model is thenrun to predict wins or margin of victory.

With this setup, the intercept represents the home-field advantage. Neutral fields can be indicatedusing theneutral() function, which sets the intercept to 0.

See Also

glm,summary.elo.winpct,score,mov,elo.model.frame

Examples

elo.winpct(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  subset = points.Home != points.Visitor)elo.winpct(mov(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = tournament,  family = "gaussian")

Classify teams that are favored to win

Description

Classify teams that are favored to win

Usage

favored(x, ..., subset = TRUE)## S3 method for class 'elo.run'favored(x, ..., subset = TRUE)## S3 method for class 'elo.glm'favored(x, ..., subset = TRUE)## S3 method for class 'elo.running'favored(x, running = TRUE, discard.skipped = FALSE, ..., subset = TRUE)## S3 method for class 'elo.markovchain'favored(x, ..., subset = TRUE)## S3 method for class 'elo.winpct'favored(x, ..., subset = TRUE)## S3 method for class 'elo.colley'favored(x, ..., subset = TRUE)## Default S3 method:favored(x, p.A, ...)

Arguments

Extract model values

Description

Extract model values fromelo functions.

Usage

## S3 method for class 'elo.run'fitted(object, ...)## S3 method for class 'elo.run'residuals(object, ...)## S3 method for class 'elo.running'fitted(object, running = TRUE, ...)## S3 method for class 'elo.glm'fitted(object, ...)## S3 method for class 'elo.markovchain'fitted(object, ...)## S3 method for class 'elo.winpct'fitted(object, ...)## S3 method for class 'elo.colley'fitted(object, ...)

Arguments

Value

A vector of fitted values. For running values, it has an additional attribute denoting to whichgroup (i.e., which model) the prediction belongs

Details onelo formulas and the specials therein

Description

Details onelo functions and the special functions allowed in them to change functions' behaviors.

Usage

players(..., weights = NULL)multiteam(...)k(x, y = NULL)adjust(x, adjustment)regress(x, to, by, regress.unused = TRUE)group(x)neutral(x)

Arguments

Details

In the functions in this package,formula is usually of the formwins.A ~ elo.A + elo.B,whereelo.A andelo.B are vectors of Elos, andwins.A is between 0 and 1,denoting whether team A (Elo A) won or lost (or something between).elo.prob also allowselo.A andelo.B to be character or factors, denoting which team(s) played.elo.runrequireselo.A to be a vector of teams or a players matrix fromplayers()(sometimes denoted by"team.A"), butelo.B can be either a vector of teams orplayers matrix ("team.B") or else a numeric column (denoting a fixed-Elo opponent).elo.glm requires both to be a vector of teams or players matrix.elo.markovchainrequires both to be a vector of teams.

formula accepts six special functions in it:

k() allows for complicated Elo updates. Forconstant Elo updates, use thek = argument instead of this special function.Note thatelo.markovchain uses this function (or argument) as a convenientway of specifying transition probabilities.elo.colley uses this to indicatethe fraction of a win to be assigned to the winning team.

adjust() allows for Elos to be adjusted for, e.g., home-field advantage. The second argumentto this function can be a scalar or vector of appropriate length. This can also be used inelo.glm andelo.markovchain as an adjuster to the logistic regressions.

regress() can be used to regress Elos back to a fixed valueafter certain matches. Giving a logical vector identifies these matches after which toregress back to the mean. Giving any other kind of vector regresses after the appropriategroupings (see, e.g.,duplicated(..., fromLast = TRUE)). The other three arguments determinewhat Elo to regress to (to =), by how much to regress toward that value(by =), and whether to continue regressing teams which have stopped playing (regress.unused,default =TRUE).

group() is used to group matches (by, e.g., week). Forelo.run, Elos are not updated untilthe group changes. It is also fed toas.matrix.elo.run, giving the number of rows to return.to produce only certain rows of matrix output. It also determines how many models to run (and on what data)forelo.glm andelo.markovchain whenrunning=TRUE.

neutral() is used inelo.glm andelo.markovchain to determine the intercept.In short, the intercept is1 - neutral(), denoting home-field advantage. Therefore, the columnpassed should be 0 (denoting home-field advantange) or 1 (denoting a neutral game). If omitted, all matchesare assumed to have home field advantage.

players() is used for multiple players on a team contributing to an overall Elo. The Elo updatesare then assigned based on the specified weights. The weights are ignored inelo.glm.

multiteam() is used for matchups consisting of multiple teams and is only valid inelo.run.multiteam.

Make Predictions on anelo Object

Description

Make Predictions on anelo Object

Usage

## S3 method for class 'elo.run'predict(object, newdata, ...)## S3 method for class 'elo.run.regressed'predict(object, newdata, regressed = FALSE, ...)## S3 method for class 'elo.run.multiteam'predict(object, newdata, ...)## S3 method for class 'elo.glm'predict(object, newdata, type = "response", ...)## S3 method for class 'elo.running'predict(object, newdata, running = TRUE, ...)## S3 method for class 'elo.markovchain'predict(object, newdata, ...)## S3 method for class 'elo.colley'predict(object, newdata, ...)## S3 method for class 'elo.winpct'predict(object, newdata, ...)

Arguments

Details

Note that the"elo.glm.running" objects will use a model fit on all the data to predict.

Value

A vector of win probabilities.

Examples

data(tournament)t1 <- head(tournament, -3)t2 <- tail(tournament, 3)results <- elo.run(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,                   data = t1, k = 20)predict(results)predict(results, newdata = t2)results <- elo.glm(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = t1,  subset = points.Home != points.Visitor)predict(results)predict(results, newdata = t2)results <- elo.markovchain(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = t1,  subset = points.Home != points.Visitor, k = 0.7)predict(results)predict(results, newdata = t2)results <- elo.colley(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = t1,  subset = points.Home != points.Visitor)predict(results)predict(results, newdata = t2)results <- elo.winpct(score(points.Home, points.Visitor) ~ team.Home + team.Visitor, data = t1,  subset = points.Home != points.Visitor, k = 0.7)predict(results)predict(results, newdata = t2)

Rank teams

Description

Extract the rankings from Elo objects.

Usage

rank.teams(object, ties.method = "min", ...)## S3 method for class 'elo.run'rank.teams(object, ties.method = "min", ...)## S3 method for class 'elo.run.regressed'rank.teams(object, ties.method = "min", regressed = FALSE, ...)## S3 method for class 'elo.glm'rank.teams(object, ties.method = "min", ...)## S3 method for class 'elo.markovchain'rank.teams(object, ties.method = "min", ...)## S3 method for class 'elo.winpct'rank.teams(object, ties.method = "min", ...)## S3 method for class 'elo.colley'rank.teams(object, ties.method = "min", ...)

Arguments

Create a 1/0/0.5 win "indicator"

Description

Create a 1/0/0.5 win "indicator" based on two teams' scores, and test for "score-ness".

Usage

score(score.A, score.B)is.score(x)

Arguments

Value

Forscore, a vector containing 0, 1, and 0.5 (for ties). Foris.score,TRUE orFALSE depending on whether all values ofx are between 0 and 1 (inclusive).

See Also

score

Examples

score(12, 10)score(10, 10)score(10, 12)

Summarize anelo Object

Description

Summarize anelo Object

Usage

## S3 method for class 'elo.run'summary(object, ...)## S3 method for class 'elo.glm'summary(object, ...)## S3 method for class 'elo.markovchain'summary(object, ...)## S3 method for class 'elo.colley'summary(object, ...)## S3 method for class 'elo.winpct'summary(object, ...)

Arguments

Value

A summary ofobject.

See Also

favored,auc.elo.run,mse

Examples

summary(elo.run(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,  data = tournament, k = 20))summary(elo.glm(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,  data = tournament))mc <- elo.markovchain(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,  data = tournament, subset = points.Home != points.Visitor, k = 0.7)summary(mc)co <- elo.colley(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,  data = tournament, subset = points.Home != points.Visitor)summary(co)wp <- elo.winpct(score(points.Home, points.Visitor) ~ team.Home + team.Visitor,  data = tournament, subset = points.Home != points.Visitor, k = 0.7)summary(wp)

tournament: Mock data for examples

Description

A fake dataset containing results from "animal-ball" matches.

Format

A data frame with 56 observations on the following 4 variables:

team.Home

The home team for the match

team.Visitor

The visiting team for the match

points.Home

Number of points scored by the home team

points.Visitor

Number of points scored by the visiting team

week

Week Number

half

The half of the season in which the match was played

Examples

data(tournament)str(tournament)

tournament.multiteam: Mock data for examples

Description

A fake dataset containing results from "animal-ball" matches.

Format

A data frame with 56 observations on the following 4 variables:

week

Week Number

half

The half of the season in which the match was played

Place_1

The first-place team

Place_2

The second-place team

Place_3

The third-place team

Place_4

The fourth-place team