EloSteepness (version 0.5.0)

elo_steepness_from_matrix: steepness based on Bayesian Elo-rating

Description

for interaction data with unknown sequence of observations

Usage

elo_steepness_from_matrix(
  mat,
  algo = c("fixed_sd", "original", "fixed_k"),
  n_rand = NULL,
  silent = FALSE,
  k = NULL,
  ...
)

Value

a list with results of the modelling fitting, containing the following list items:

steepness

a matrix with the posterior samples for steepness. Each column corresponds to one randomization (as set via n_rand). Each row is one iteration.

cumwinprobs

an array with posterior cumulative winning probabilities for each individual.

k

an array with posterior k values.

ids

a character vector with individual ID codes as supplied in mat

diagnostics

a list with information regarding sampling problems

stanfit

the actual stanfit object

mat

the input matrix

algo

character, describing whether the original fitting algorithm was used ("original") or the one with fixed SD of start ratings ("fixed_sd")

sequence_supplied

logical, were data supplied as matrix (FALSE) or as sequence via winner/loser vector (TRUE)

Arguments

mat

square interaction matrix

algo

character, either "fixed_sd", "original", or "fixed_k".This determines which algorithm to estimate Elo-ratings is used. Default is "fixed_sd", which is a slight modification from Goffe et al's original code. "fixed_k" fixes the k parameter ('shift coefficient' in Goffe et al) to the set value rather than estimating it from the data.

n_rand

numeric, number of randomized sequences. Default is NULL, which uses a rule of thumb to determine the number (see below for more details).

silent

logical, suppress warnings (default is FALSE)

k

numeric, provides a fixed k parameter. This only has effects if algo = "fixed_k". At its default NULL a value of 0.4 is used.

...

additional arguments for sampling()

Details

The number of randomizations is set in the following way, unless a specific number is provided. If there are more than 500 observed interactions, n_rand = 5. If there are less than 100 interactions, n_rand = 50. In the remaining cases, n_rand = 20.

If the function call produces warnings about divergent transitions, large Rhat values or low effective sample sizes, increase the number of iterations (via iter=) and/or adjust the sampling controls (e.g. via control = list(adapt_delta = 0.9)).

If the argument seed = is supplied, its value will be passed to sampling() to ensure reproducibility of the MCMC sampling, but the same seed will then also apply to the randomization of the interaction sequence order(s).

Examples

data(dommats, package = "EloRating")
# using small numbers for iterations etc to speed up running time
res <- elo_steepness_from_matrix(dommats$elephants, n_rand = 1, cores = 2,
                                 iter = 800, warmup = 300, 
                                 refresh = 0, chains = 2, seed = 1)
plot_steepness(res)

# \donttest{
# use the original underlying algorithm by Goffe et al 2018
# will warn about divergent iterations and low effective sample sizes
# but warnings can be caught/suppressed by setting silent = TRUE

res <- elo_steepness_from_matrix(dommats$elephants, n_rand = 1,
                                 algo = "original", silent = TRUE,
                                 iter = 1000, warmup = 500, refresh = 0)
res$diagnostics

# or the sampling can be tweaked to achieve better convergence:
# (this still might produce some divergent transitions on occasion)
# (and the number of iterations should be set higher)
res <- elo_steepness_from_matrix(dommats$elephants, n_rand = 1, chains = 2,
                                 algo = "original", silent = TRUE, seed = 1,
                                 iter = 1000, warmup = 500, refresh = 0,
                                 control = list(adapt_delta = 0.99))
res$diagnostics
# }