optimizek: optimize the k parameter
In EloRating: Animal Dominance Hierarchies by Elo Rating

Description Usage Arguments Details Value References Examples

optimize the k parameter

optimizek(
  eloobject,
  krange = c(2, 400),
  optimode = "loop",
  resolution = 100,
  itype = NULL,
  daterange = NULL,
  burnin = 0,
  doplot = FALSE,
  progbar = FALSE,
  ...
)

`eloobject`	output from `elo.seq` or from `fastelo`
`krange`	either a vector of length 2, giving the range of k values to be tested, or a named list with vectors of length 2, in which each list item is named according to different interaction types (see the `intensity=` argument in `elo.seq`)
`optimode`	character, either `"loop"` or `"optimize"`. See details.
`resolution`	numeric, the number of steps between the range of k values to be tested. Currently only a single value can be supplied here and in case `krange` is a list this value will be applied to all items in this list
`itype`	character or factor containing the different interaction types, which is only relevant if `krange` is a list. The content of `itype` and the names of `krange` have to match!
`daterange`	character or Date of length 2, provides a date range for optimization. Only relevant in case `eloobject` is the result of `elo.seq()`
`burnin`	numeric, the number of interactions to be excluded from the calculation of the (log) likelihood. This parameter is ignored if a date range is supplied. By default `burnin = 0`, i.e. all interactions are considered.
`doplot`	logical, should a plot be returned. Works only if `optimode = "loop"`, and only if there are maximally two different interaction types
`progbar`	logical, should a progress bar be displayed, not yet implemented
`...`	additional arguments for the plot and text functions, e.g. for setting `cex` or `lwd`

this function attempts to find the objectively best k parameter. This is done by a maximum likelihood approach in which the likelihood is represented by the individual winning probabilities. In a perfect situation, in each interaction the winner would have a winning probability of 1, whereas in the worst case, in each interaction the winner would have a winning probability of 0.

There are two major approaches to find the best k. One does it 'by hand', i.e. by means of a loop trying many different k values (specified by resolution), recalculating the ratings (and associated winning probabilities) and return the likelihood for each k value. The second approach uses the optimize function, but this is not yet implemented.

One thing to note is that you can use interaction-level k values, i.e. if you have interactions of different types (e.g. fights vs. displacements) you can try to find the optimal k for each interaction type. This is achieved in the ("loop" approach by trying different combinations of k values. Because of the combinatorial nature of this approach, the number of individual sequences to be fitted increases sharply with higher resolutions: if you have two different interaction types and use a resolution of 5, the function will need to run 25 (= 5 * 5) iterations. If you use a more reasonable resolution of 100 the number of iterations will be already 10000. Also note that in that case the actual plotting of the results might take a lot of time in such cases. Just try with low values first to see whether it works as expected and the potentially increase the resolution.

a list with two items: (1) $best, a data frame with one line, in which the maximal log likelihood is returned alongside the one or several corresponding k values, and (2) $complete, a data frame with all the values tested and their log likelihoods

\insertRef

franz2015aEloRating

\insertRef

mcmahan1984EloRating

data(adv2)
res <- elo.seq(winner = adv2$winner, loser = adv2$loser, Date = adv2$Date)
optimizek(eloobject = res, krange = c(50, 400), resolution = 200, doplot = TRUE)$best

# with a burnin value set:
optimizek(eloobject = res, krange = c(50, 400), resolution = 200, burnin = 15, doplot = TRUE)$best

# using different interaction intensities
myks <- list(displace = 20, fight = 200)
res <- elo.seq(winner = adv2$winner, loser = adv2$loser, Date = adv2$Date,
               k = myks, intensity = adv2$intensity)
optimizek(eloobject = res, optimode = "loop",
          krange = list(fight = c(50, 600), displace = c(20, 200)),
          resolution = 100, itype = adv2$intensity, main = 'bla')$best