elo.seq: calculate Elo ratings
In EloRating: Animal Dominance Hierarchies by Elo Rating

Description Usage Arguments Details Value Author(s) References Examples

calculate Elo ratings from a sequence of dominance interactions

elo.seq(winner, loser, Date, draw = NULL, presence = NULL, startvalue = 1000,
               k = 100, normprob = TRUE, init = "average", intensity = NULL,
               iterate = 0, runcheck = TRUE, progressbar = FALSE)
fastelo(WINNER, LOSER, ALLIDS, KVALS, STARTVALUES, NORMPROB = TRUE, ROUND = TRUE)

`winner`	either a factor or character vector with winner IDs of dyadic dominance interactions
`loser`	either a factor or character vector with loser IDs of dyadic dominance interactions
`Date`	character vector of form "YYYY-MM-DD" with the date of the respective interaction
`draw`	logical, which interactions ended undecided (i.e. drawn or tied)? By default all `FALSE`, i.e. no undecided interactions occurred. Note that in this case, `winner`/`loser` values can be interchanged
`presence`	optional data.frame, to supply data about presence and absence of individuals for part of the time the data collection covered. see details
`startvalue`	the value of Elo ratings of the two individuals that are involved in the first interaction of the overall sequence prior to this interaction. By default set to 1000. See also `init`
`k`	factor k that determines the maximum change in ratings. By default `k=100`
`normprob`	logical (by default `TRUE`). Should a normal curve be assumed for calculating the winning/losing probablities, or a logistic curve. See `winprob` for details
`init`	character, what Elo rating does an individual have prior to its first interaction. Three options are available: `average`: individuals always start with the value specified in `startvalue`. Given stable composition of the group, this also reflects the average Elo rating on each day in that group, `bottom`: subjects entering at the current lowest Elo value if the lowest value getting lower its getting lower for all subjects which had this lowest values before, it is reflecting that in some species new subjects entering a group at the bottom level "bottom entry" `bottom_low`: same as `bottom` but additionally the start values getting after the first interaction lower for all non-interacting subjects and, reflecting that we have at start no knowledge about the subjects this option offers for "bottom entry" species the possibility to consider that in a way that those subjects which are not interacting getting lower from start on
`intensity`	a character vector or factor describing intensity of interaction, to be matched with custom k values if specified
`iterate`	not yet implemented
`runcheck`	logical, should several checks regarding data integrety be performed, by default `TRUE`. See `seqcheck`
`progressbar`	logical, should progress bars be displayed, by default `progressbar=TRUE`
`WINNER`	same as `winner` for use in `fastelo()`
`LOSER`	same as `loser` for use in `fastelo()`
`ALLIDS`	character vector, contains all the indivuals IDS
`KVALS`	numeric vector of the same length `WINNER`, i.e. one k value for each interaction
`STARTVALUES`	numeric vector of the same length as `ALLIDS`, i.e. one start value for each individual
`NORMPROB`	logical, by default `TRUE`: same as `normprob` for use in `fastelo()`
`ROUND`	logical, by default `TRUE`: should ratings be rounded to integers. For use in `fastelo()`

The presence 'matrix' is actually an object of class data.frame containing information about wether an individual was present on a given day or not. The first column represents the dates, running at least from the date of the earliest interaction until at least the date of the last interaction with one line per day (regardless of whether there were actually interactions observed on each day). Further, each individual is represented as a column in which "1" indicates an individual was present on the row-date and a "0" indicates the individuals absence on this date. NAs are not allowed. See advpres for an example.

The function fastelo() is a stripped-down version of elo.seq(), which performs only the most basic calculations while ignoring anything that is date and presence related. Neither does it perform data checks. In other words, it just calculates ratings based on the sequence. It's most useful in simulations, for example when estimating optimal k parameters. Its main advantage is its speed, which is substantially faster than elo.seq(). Note that currently there is no support for tied interactions. The main difference to note is that both, start values and k values have to be supplied as vectors with one value for each individual and interaction respectively.

An object of class elo, which is list with 10 items that serves as basis to extract relevant information:

`mat`	a date by ID-`matrix` with raw Elo ratings
`lmat`	a date by ID-`matrix` with raw Elo ratings
`cmat`	a date by ID-`matrix` with raw Elo ratings
`pmat`	a date by ID-`matrix` with with presence data
`nmat`	a date by ID-`matrix` containing the number of interactions a given ID was involved in on a given day
`logtable`	details on each single interaction
`stability`	a `data.frame` containing information about stability (see `stab_elo`)
`truedates`	vector of class `Date` covering the ranges of dates in the dataset
`misc`	various
`allids`	a (sorted) character vector with all IDs that occur in the dataset

fastelo() returns a list with ten items:

`$ratings`	numeric vector of the final ratings in the same order as `ALLIDS`
`$winprobs`	numeric vector with winning probabilities in the same order as the interactions were supplied
`$rtype`	character of length 1, as a marker that the result comes from `fastelo()`
`$startvalues`	numeric vector with start values
`$kvalues`	numeric vector with k values
`$winner`	character vector with winners
`$loser`	character vector with losers
`$allids`	character vector with all IDs that occur in the sequence
`$normprob`	logical, was normal probability used for winning expectations
`$round`	logical, was rounding to integers used during the calculation of ratings

Christof Neumann and Lars Kulik

\insertRef

elo1978EloRating

\insertRef

albers2001EloRating

\insertRef

neumann2011EloRating

\insertRef

newton-fisher2017aEloRating

data(adv)
res <- elo.seq(winner = adv$winner, loser = adv$loser, Date = adv$Date)
summary(res)

# with custom k
data(adv2)
table(adv2$intensity)

myks <- list(displace = 20, fight = 200)
res <- elo.seq(winner = adv2$winner, loser = adv2$loser, Date = adv2$Date,
               k = myks, intensity = adv2$intensity)
extract_elo(res)
summary(res)

# with custom start values
# if we know prior ranks:
myranks <- 1:7
names(myranks) <- letters[1:7]
mypriors <- createstartvalues(myranks, shape = 0.3)
res <- elo.seq(winner = adv2$winner, loser = adv2$loser, Date = adv2$Date,
               k = myks, intensity = adv2$intensity, startvalue = mypriors$res)
extract_elo(res)

# compare elo.seq and fastelo
xdata <- randomsequence(10, 500)
allids <- colnames(xdata$pres)[2:ncol(xdata$pres)]
winner <- xdata$seqdat$winner
loser <- xdata$seqdat$loser
Date <- xdata$seqdat$Date
k <- rep(100, length(winner))
svals <- rep(1000, length(allids))

res1 <- fastelo(WINNER = winner, LOSER = loser, ALLIDS = allids, KVALS = k,
                STARTVALUES = svals, NORMPROB = TRUE)$ratings
names(res1) <- allids
res1 <- sort(res1, decreasing = TRUE)
res2 <- extract_elo(elo.seq(winner = winner, loser = loser, Date = Date,
                            startvalue = 1000, k = 100, normprob = TRUE,
                            runcheck = FALSE))
res1
res2