elo.run: 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
)

Value

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

Arguments

formula: A formula. See the help page for formulas for details.
data: A data.frame in which to look for objects in formula.
na.action: A function which indicates what should happen when the data contain NAs.
subset: An optional vector specifying a subset of observations.
k: A constant k-value (or a vector, where appropriate).
initial.elos: An optional named vector containing initial Elo ratings for all teams in formula. If a single (unnamed) value is supplied, that value is applied to all teams. NULL (the default) sets all Elos to 1500.
...: Other arguments (not used at this time).
prob.fun: A function with at least 4 arguments: elo.A, elo.B, adjust.A, and adjust.B. It should return a predicted probability that team A wins. The values passed in will be scalars, and a scalar is expected as output.
update.fun: A function with at least 6 arguments: the same as elo.update.default. The function takes in the Elos, the win indicator, k, and any adjustments, and returns a value by which to update the Elos. The values passed in will be scalars, and a scalar is expected as output.
verbose: Should a message be issued when R is used (over C++)?

Details

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

Examples

Run this code

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 advantage
elo.run(score(points.Home, points.Visitor) ~ adjust(team.Home, 30) + team.Visitor,
        data = tournament, k = 20)

tournament$home.field <- 30
elo.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-season
elo.run(score(points.Home, points.Visitor) ~ adjust(team.Home, 30) +
        team.Visitor + regress(half, 1500, 0.2), data = tournament, k = 20)