Description Usage Arguments Details Value Examples

Conducts **optimized** elo rating analyses as per Foerster, Franz et al
and outputs raw, normalized, cardinal, and categorical ranks as a list object in
R or in an output file. For non-optimized Elo score calculation, use
`eloratingfixed`

.

1 2 | ```
eloratingopt(agon_data, pres_data, fit_init_elo = FALSE, outputfile = NULL,
returnR = TRUE)
``` |

`agon_data` |
Input data frame with dominance interactions, should only contain Date, Winner, Loser. Date should be formatted as MONTH/DAY/YEAR, or already as Date class. |

`pres_data` |
Input data frame with columns "id", "start_date" and "end_date". Date columns should be formatted as MONTH/DAY/YEAR, or already as Date class. If all IDs are present the whole time, you can ignore this and a pres_data table will be automatically generated. |

`fit_init_elo` |
If FALSE (the default), fits only the K parameter, with a default
starting Elo score of 1000 for each individual. If TRUE, fits K and starting Elo for
each individual. The latter option is |

`outputfile` |
Name of csv file to save ranks to. Default is NULL, in which case the function will only return a table in R. If you supply an output file name the function will save the results as a csv file in your working directory. |

`returnR` |
whether to return an R object from the function call. Default is TRUE |

This function accepts a data frame of date-stamped dominance interactions and
(optionally) a data frame of start and end dates for each individual to be ranked,
and outputs daily Elo scores with K parameter, and optionally initial elo scores, fitted using
a maximum likelihood approach. The optimization procedure uses the `optim()`

function,
with a burn in period of 100 interactions. We use the "Brent" method when fitting only the K
parameter, and the "BFGS" method for fitting both K and initial Elo scores. See
`optim`

for more details. Future package development will add additional
user control of the optimization procedure, allowing for specification of the burn in period,
optimization algorithm, and initial values for optimization.

Note also that the fitting procedure requires each individual to have at least one win and one loss, so any individual that doesn't meet those criteria is automatically removed. Additionally, any instance of an individual winning against itself is cleaned from the data, and several other checks of the data are performed before the optimization procedure is run.

A detailed description of the function output is given in the **Value** section of
this help file:

Returns a list with five or six elements (depending on input):

**elo**Data frame with all IDs and dates they were present, with the following columns:Date: Dates of study period

Individual: the names of each ranked individual, for each date they were present

Elo: fitted Elo scores for each individual on each day

EloOrdinal: Daily ordinal rank based on Elo scores

EloScaled: Daily Elo scores rescaled between 0 and 1 according to

`([individual Elo] - min([daily Elo scores])/(max([daily Elo scores]) - min([daily Elo scores]))`

ExpNumBeaten: expected number of individuals in the group beaten, which is the sum of winning probabilities based on relative Elo scores of an individual and all others, following equation (4) in Foerster, Franz et al. 2016

EloCardinal: ExpNumBeaten values rescaled as a percentage of the total number of ranked individuals present in the group on the day of ranking. We encourage the use of this measure.

JenksEloCardinal: Categorical rank (high, mid, or low) using the Jenks natural breaks classification method implemented in the R package BAMMtools. See

`getJenksBreaks`

**k**The maximum-likelihood fitted k parameter value**pred_accuracy**Proportion of correctly predicted interactions**maxLogL**The overall log-likelihood of the observed data given the fitted parameter values based on winning probabilities (as calculated in equation (1) of Foerster, Franz et al 2016) for all interactions**AIC**Akaike's Information Criterion value as a measure of model fit**init_elo**(*Only returned if you fit initial Elo scores*) initial Elo for each individual

1 2 3 | ```
nbadata = EloOptimized::nba #nba wins and losses from the 1995-96 season
nbaelo = eloratingopt(agon_data = nbadata, fit_init_elo = FALSE)
# generates optimized elo scores (optimizing only K) and saves them as "nbaelo"
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.