informed_elo {DynaRankR}

Elo-rating method informed by prior information

Description

Use Elo-rating method to infer a dominance hierarchy over multiple study periods. New contestants are added according to the convention specified by the user. Full description of the addition of new individuals is described in Strauss & Holekamp (in revision). To run the original Elo-rating procedure, use convention flag 'none'.

Usage

informed_elo(
  contestants,
  convention,
  K = 200,
  lambda = 100,
  initial.ranks = NULL,
  interactions
)

Arguments

contestants

A dataframe with the identities of the contestants for each study period along with the relevant data for adding them to the hierarchy. There should be one row per contestant per study period. Periods should appear in chronological order. The dataframe should contain the following columns:

period

Study period.

id

Identity of contestant.

convention1

The primary convention by which new individuals are added to the hierarchy. Interpretation of this column varies depending on the value of the convention argument. If convention = none, this column is optional.

convention2

Optional. The secondary data for resolving ties in convention1. Interpretation of this column varies depending on the value of the convention argument.

convention

A flag determining how new individuals are added to the hierarchy. The value of this flag influences how the convention1 and convention2 columns of the contestants argument are interpreted. Currently this function supports five options:

none

The standard Elo-rating procedure is run. Individuals joining the hierarchy receive a score equal to the mean of other group members.

mri

New contestants are added to the hierarchy according to maternal rank inheritance with youngest ascendancy. convention1 should be a vector of mother identities for each contestant. convention2 should be an optional vector of intra-litter ranks (lower numbers = higher rank) for resolving the order of contestants from the same mother joining the hierarchy in the same study period.

tenure

New contestants are added to the hierarchy according their tenure in the group. convention1 should be a vector of dates on which each contestant joined the group. convention2 should be an optional vector of numerical data for resolving ties in convention1 (e.g., body size). Higher values are considered higher rank.

age

New contestants are added to the hierarchy according their age (older = higher rank). convention1 should be a vector of birthdates or numerical age classes. convention2 should be an optional vector of numerical data for resolving ties in convention1 (e.g., body size). Higher values are considered higher rank.

phys_attr

New contestants are added to the hierarchy according to some physical attribute (larger value = higher rank). convention1 should be a vector of numerical attribute measurements. convention2 should be an optional vector of numerical data for resolving ties in convention1. Higher values are considered higher rank.

K

Parameter influencing the magnitude of score changes after each outcome.

lambda

Parameter influencing the shape of the logistic function linking the difference in score between winner and loser to the expected probability of each contestant winning.

initial.ranks

The initial ordering of individuals for the first study period. Required if using maternal rank inheritance as the convention. For other conventions, if initial.ranks is not specified, the order determined by convention1 is used to create the initial order.

interactions

A dataframe of interaction data with the following columns:

winner

Identities of winners.

loser

Identities of losers.

period

Study period in which interactions occurred.

Value

Produces a dataframe with the following columns:

period

Study period.

id

Identity of contestant.

score

Elo-rating score of contestant.

rank

Ordinal rank of contestant in study period. Lower numbers equal higher rank.

stan.rank

Rank of contestant standardized for group size. Values range from 1 (highest rank) to -1 (lowest rank).

old.order

Identity of contestants arranged in the previous order (the order they were in before updating the order based on observations from current study period).

References

Strauss ED & Holekamp KE (in revision). Journal of Animal Ecology.

Albers PCH & de Vries H (2000). Animal Behavior.

Examples

##Informed elo
female.ranks <- informed_elo(contestants = C.crocuta.female$contestants, convention = 'mri',
initial.ranks = C.crocuta.female$initial.ranks,
interactions = C.crocuta.female$interactions)

##Standard elo
female.ranks <- informed_elo(contestants = C.crocuta.female$contestants, convention = 'none',
interactions = C.crocuta.female$interactions)