elom: Multi-player Elo Based Rating System
In PlayerRatings: Dynamic Updating Methods for Player Ratings Estimation

Description Usage Arguments Details Value References See Also Examples

Implements the Elo based rating system for for multi-player games where the result is a placing or a score. This includes zero-sum games such as poker and mahjong. The default arguments used here are those used by Tenhou for riichi mahjong.

1
2
3

elom(x, nn = 4, exact = TRUE, base = c(30,10,-10,-30), status = NULL, 
    init = 1500, kfac = kriichi, history = FALSE, sort = TRUE, ...,
	placing = FALSE)

`x`	A data frame containing `2nn+1` variables, where `nn` is the number of players in a single game: (col `1`) a numeric vector denoting the time period in which the game took place, (cols `2` to `nn+1`) numeric or character identifiers for each of the `nn` players, (cols `nn+2` to `2nn+1`) the result of the game expressed as a number, typically a score for each player (e.g. the number of remaining chips in poker). Negative numbers are allowed. Alternatively, the result can be a placing (e.g. 1 for first place, 2 for second place), in which case the `placing` argument MUST be set to `TRUE`. Placings must be integers: in the event of a tie, multiple players can be given the same placing.
`nn`	Number of players in a single game. If the number of players varies, then this argument should be set to the maximum number of players in any game, and the `exact` argument should be set to `FALSE`. Unused player identifiers in `x` must then be set to the missing value `NA`. The game score for `NA` player identifiers is ignored and therefore can also be set to `NA`.
`exact`	If `TRUE` (the default), then every game always has exactly `nn` players. If `TRUE`, then `x` cannot have missing values.
`base`	The base values used for the rating. Can be a numeric vector of length equal to `nn`, a numeric matrix with `nrow(x)` rows and `nn` columns, or a vectorized function of the game score. If a numeric vector, then the person with the highest score gets `base[1]`, the person with the second highest score gets `base[2]`, and so on. In the event of a tie on the game score, tied players are given the largest available `base` value. For games with less than `nn` players, see Details. If `base` is a matrix, then the ith row is used for the ith game in `x`. If `base` is a vectorized function, then each player gets the result of the function applied to the game score. In Riichi mahjong, where players start with 25000 points, a typical example might be `function(x) (x-25000)/250`.
`status`	A data frame with the current status of the system. If not `NULL`, this needs to be a data frame in the form of the `ratings` component of the returned list, containing variables named `Player`, `Rating`, and optionally `Games`, `1st`, `2nd`, `3rd` and so on, and finally `Lag`, which are all set to zero if not given.
`init`	The rating at which to initialize a new player not appearing in `status`. Must be a single number. If different initializations for different players are required, this can be done using `status`.
`kfac`	The K factor parameter. Can be a single number or a vectorized function of two arguments, the first being the ratings and the second being the number of games played. See `kriichi` for an example.
`history`	If `TRUE` returns the entire history for each period in the component `history` of the returned list.
`sort`	If `TRUE` sort the results by rating (highest to lowest). If `FALSE` sort the results by player.
`...`	Passed to the function `kfac`.
`placing`	If the results are given as placings (e.g. 1 for first place, 2 for second place) then this argument MUST be set to `TRUE`, otherwise the placings will be interpreted as game scores.

For multi-player games there is no player one advantage parameter (e.g. a home advantage in football or a white advantage in chess).

If the sum of the vector base is not zero, or if base is a function which is not zero when evaluated at the starting chip/points value, then you may observe unusual behaviour and/or substantial ratings inflation/deflation.

The two-player Elo system is based on game outcomes in the interval [0,1] and therefore uses a different scaling. As a result, the K factors here should be smaller. The default (as used by Tenhou) is a K factor of 0.2 for players that have played a large number of games (see kriichi).

If the number of players varies and base is a vector (of length nn), then if the game has less than nn players, the vector is reduced by successively removing the centre value (for odd lengths) or by averaging both centre values (for even lengths). For example, if the x data frame contains both four-player and three-player mahjong games, then under the default values the three-player base vector becomes c(30,0,-30), which is consistent with the vector that Tenhou uses for three-player mahjong.

A numeric matrix can be used to allocate different base vectors to different games. For example, in Riichi mahjong, games can be Tonpuusen (East round only) or Hanchan (East and South rounds), and you may wish to allocate different base vectors to each type.

A list object of class "rating" with the following components

`ratings`	A data frame of the results at the end of the final time period. The variables are self explanatory except for `Lag`, which represents the number of time periods since the player last played a game. This is equal to zero for players who played in the latest time period, and is also zero for players who have not yet played any games.
`history`	A three dimensional array, or `NULL` if `history` is `FALSE`. The row dimension is the players, the column dimension is the time periods. The third dimension gives different parameters.
`nn`	The number of players for a single game.
`kfac`	The K factor or K factor function.
`type`	The character string `"EloM"`.

Elo, Arpad (1978) The Rating of Chessplayers, Past and Present. Arco. ISBN 0-668-04721-6.

elo, fide, glicko, kriichi

robj <- elom(riichi)
robj

ut <- unique(riichi$Time)
robj <- elom(riichi[riichi$Time == ut[1],])
for(i in 2:length(ut)) {
  robj <- elom(riichi[riichi$Time == ut[i],], status = robj$ratings)
}
robj