| Title: | Inferring Dominance Hierarchies and Estimating Uncertainty |
|---|---|
| Description: | Provides: (1) Tools to infer dominance hierarchies based on calculating Elo scores, but with custom functions to improve estimates in animals with relatively stable dominance ranks. (2) Tools to plot the shape of the dominance hierarchy and estimate the uncertainty of a given data set. |
| Authors: | Damien R. Farine and Alfredo Sanchez-Tojar |
| Maintainer: | Damien R. Farine <[email protected]> |
| License: | GPL-2 |
| Version: | 0.1.5 |
| Built: | 2024-06-28 06:17:34 UTC |
| Source: | CRAN |
Provides (1) Tools to infer dominance hierarchies based on calculating Elo scores, but with custom functions to improve estimates in animals with relatively stable dominance ranks. (2) Tools to plot the shape of the dominance hierarchy and estimate the uncertainty of a given data set.
| Package: | aniDom |
| Type: | Package |
| Version: | 0.1.5 |
| Date: | 2021-03-06 |
| License: | GPL-2 |
Written by Damien R. Farine and Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Generate data data <- generate_interactions(N.inds=10,N.obs=20,a=5,b=3) # Extract interactions winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate Elo scores with randomised order scores <- elo_scores(winners=winners,losers=losers,randomise=TRUE,n.rands=1000) # Plot ranks plot_ranks(scores,plot.CIs=TRUE) # Plot hierachy shape plot_hierarchy_shape(identity=1:nrow(scores),rank=1:nrow(scores), winners=winners,losers=losers,fitted=TRUE)# Generate data data <- generate_interactions(N.inds=10,N.obs=20,a=5,b=3) # Extract interactions winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate Elo scores with randomised order scores <- elo_scores(winners=winners,losers=losers,randomise=TRUE,n.rands=1000) # Plot ranks plot_ranks(scores,plot.CIs=TRUE) # Plot hierachy shape plot_hierarchy_shape(identity=1:nrow(scores),rank=1:nrow(scores), winners=winners,losers=losers,fitted=TRUE)
Function that takes winners and losers from dominance interactions and returns either their Elo score or their ranks. The function can generate replicated datasets by randomising the order (time) of the interactions, which can be used to generate 95% confidence intervals.
elo_scores(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, randomise = FALSE, n.rands = 1000, return.as.ranks = FALSE, return.trajectories = FALSE, dates = NULL)elo_scores(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, randomise = FALSE, n.rands = 1000, return.as.ranks = FALSE, return.trajectories = FALSE, dates = NULL)
winners |
Vector containing the identity of the winners. This can be integers or strings. |
losers |
Vector containing the identity of the losers. This can be integers or strings. These should be in the same order as the winners (i.e. winners[1] should be the winner and losers[1] should be the loser from the same contest). |
identities |
Optional vector containing the identity of all individuals. This is useful if not all individuals are represented in the winners and losers. |
sigmoid.param |
A parameter of the Elo function that determines the steepness of the sigmoid function (i.e how much the scores change for small differences in rank). Smaller values flatten the shape (more linear), whereas larger values create a stronger threshold function (more change for small differences in rank). |
K |
K is a parameter of the Elo function that determines the speed at which scores change after an encounter (default K=200). |
init.score |
Parameter of the Elo function that determines the starting score (does not have an effect on relative differences in score). |
randomise |
Boolean (TRUE/FALSE) describing whether to create replicated datasets by randomising the order of the observed interactions (see details). |
n.rands |
The number of randomisations to perform (ignored if randomise=FALSE). |
return.as.ranks |
Boolean (TRUE/FALSE) describing whether to convert scores into ranks before returning the data. |
return.trajectories |
Boolean (TRUE/FALSE) describing whether to return trajectories (the scores after each interaction T) or only the final scores. |
dates |
Optional vector containing a timestamp identifier (in any format) for each observation (see details). |
This function calculates Elo scores using a sigmoidal function. Because animal groups often have relatively stable hierarchies during a study period, this implementation allows the order of interactions to be randomised (randomise=TRUE) to create K replicated datasets (where K=n.rands). This method can improve the estimate of the ranks for each individual, and allow 95% range of values to be computed. If randomise=FALSE, the scores will be calculated only once and maintain the original ordering of winners and losers for each context.
The date option can be used to return timestamped trajectories. Note that because the function assumes that interactions are ordered temporally, the function simply returns each unique timestamp in the order they are encountered. Thus, the aggregation of observations into dates will be determined by the resolution of the timestamp (e.g. minutes, days, months).
The function returns different values depending on the input parameters.
If randomise=FALSE and return.trajectories=FALSE, then the function returns a vector of size N giving final score for each individual from the original ordering of interactions (where N is the number of individuals in the data or in the identities variable if given). If randomise=TRUE and return.trajectories=FALSE, then the function returns a NxK matrix giving the final scores for each individual (rows) after each randomisation of the orders. If randomise=FALSE and return.trajcetories=TRUE, then the function returns an Nx(T+1) matrix giving the starting score (init.score) in the first column followed by the score after each of the T interactions. If randomise=TRUE and return.trajcetories=TRUE, then the function returns an NxTxK array.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate Elo scores scores <- elo_scores(winners,losers) # Plot ranks plot_ranks(scores) #### return timestamped data # simulating 10 dominance interactions # in a group of 5 individuals output <- generate_interactions(5, 10, a=10, b=5, id.biased=FALSE, rank.biased=FALSE) # adding some random dates, this could be, in principle, # of any format, e.g. (character, numeric, etc). output$interactions$date <- c("date01", "date01", "date02","date02","date03","date04", "date04","date05","date06","date06") dated.trajectories <- elo_scores( output$interactions$Winner, output$interactions$Loser, dates=output$interactions$date, identities=c(1:5), randomise=FALSE, return.as.ranks=FALSE, return.trajectories=TRUE)# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate Elo scores scores <- elo_scores(winners,losers) # Plot ranks plot_ranks(scores) #### return timestamped data # simulating 10 dominance interactions # in a group of 5 individuals output <- generate_interactions(5, 10, a=10, b=5, id.biased=FALSE, rank.biased=FALSE) # adding some random dates, this could be, in principle, # of any format, e.g. (character, numeric, etc). output$interactions$date <- c("date01", "date01", "date02","date02","date03","date04", "date04","date05","date06","date06") dated.trajectories <- elo_scores( output$interactions$Winner, output$interactions$Loser, dates=output$interactions$date, identities=c(1:5), randomise=FALSE, return.as.ranks=FALSE, return.trajectories=TRUE)
Calculates the Intraclass Correlation Coefficient for each individual after randomising the order of interactions in the given dataset.
estimate_uncertainty_by_repeatability(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, n.rands = 1000)estimate_uncertainty_by_repeatability(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, n.rands = 1000)
winners |
Vector containing the identity of the winners. This can be integers or strings. |
losers |
Vector containing the identity of the losers. This can be integers or strings. These should be in the same order as the winners (i.e. winners[1] should be the winner and losers[1] should be the loser from the same contest). |
identities |
Optional vector containing the identity of all individuals. This is useful if not all individuals are represented in the winners and losers. |
sigmoid.param |
A parameter of the Elo function that determines the steepness of the sigmoid function (i.e how much the scores change for small differences in rank). Smaller values flatten the shape (more linear), whereas larger values create a stronger threshold function (more change for small differences in rank). |
K |
K is a parameter of the Elo function that determines the speed at which scores change after an encounter (default K=200). |
init.score |
Parameter of the Elo function that determines the starting score (does not have an effect on relative differences in score). |
n.rands |
The number of randomisations to perform. |
Each ordering of winners and losers will yield slightly different Elo scores. This function takes the Elo scores from n.rands randomisations of the order of interactions. It then computes the repeatability score. This repeatability score can provide some insight into the level of certainty (or robustness) of the input data. Our simulations suggest that a repeatability score above 0.8 suggests a reasonably robust hierarchy, given a large input dataset (can be unreliable for small datasets, i.e. < 10 observations per indiviudal), or for extremely flat hierarchies.
Returns an object of class rpt from the rptR library. This object contains all of the information required to estimate repeatability.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate repeatability r <- estimate_uncertainty_by_repeatability(winners,losers)# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate repeatability r <- estimate_uncertainty_by_repeatability(winners,losers)
Calculates the correlation of the Elo scores for individuals across to exclusive halves of the data.
estimate_uncertainty_by_splitting(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, randomise = FALSE, n.rands = 1000)estimate_uncertainty_by_splitting(winners, losers, identities = NULL, sigmoid.param = 1/100, K = 200, init.score = 0, randomise = FALSE, n.rands = 1000)
winners |
Vector containing the identity of the winners. This can be integers or strings. |
losers |
Vector containing the identity of the losers. This can be integers or strings. These should be in the same order as the winners (i.e. winners[1] should be the winner and losers[1] should be the loser from the same contest). |
identities |
Optional vector containing the identity of all individuals. This is useful if not all individuals are represented in the winners and losers. |
sigmoid.param |
A parameter of the Elo function that determines the steepness of the sigmoid function (i.e how much the scores change for small differences in rank). Smaller values flatten the shape (more linear), whereas larger values create a stronger threshold function (more change for small differences in rank). |
K |
K is a parameter of the Elo function that determines the speed at which scores change after an encounter (default K=200). |
init.score |
Parameter of the Elo function that determines the starting score (does not have an effect on relative differences in score). |
randomise |
Boolean (TRUE/FALSE) describing whether to create replicated datasets by randomising the order of the observed interactions (see details). |
n.rands |
The number of randomisations to perform. |
By calculating the correlation of the Elo scores calculated separately for two halves of the data, this function provides some insights into the uncertainty and robustness of the data collected. If randomise=FALSE, the data are split in half and the correlation between the two halves is returned. If randomise=TRUE, then the ordering of the interactions is randomised n.rands times and the correlation is calculated each time in the same way. The function then returns the mean and 95% range of the correlation values. Our simulations suggest that correlations above 0.5 suggests a robust dominance hierarchy (or low uncertainty).
If randomise=FALSE: the Spearman rank correlation coefficient of the first half and second half of the data. If randomise=TRUE: the mean and 95% range of the Spearkman rank correlation coefficients from two halves of the data with the ordering randomised each time.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate repeatability r <- estimate_uncertainty_by_splitting(winners,losers,randomise=TRUE)# Generate some input data data <- generate_interactions(10,20,5,2) # Extract winners and losers winners <- data$interactions$Winner losers <- data$interactions$Loser # Calculate repeatability r <- estimate_uncertainty_by_splitting(winners,losers,randomise=TRUE)
Generates simulated winners and losers. The function can generate data for different population sizes, with differently-shaped hierarchies, and with varying biases. The output is the hierarchy, and the winner and loser for each interaction.
generate_interactions(N.inds, N.obs, a, b, id.biased = FALSE, rank.biased = FALSE)generate_interactions(N.inds, N.obs, a, b, id.biased = FALSE, rank.biased = FALSE)
N.inds |
The number of individuals |
N.obs |
The number of observed interactions (in total). |
a |
Parameter to control the steepness of the hierarchy (flatter or more sigmoidal) |
b |
Parameter to control the intercept of the hierachy (moves the sigmoid left or right) |
id.biased |
Boolean (TRUE/FALSE) describing whether to introduce an individual bias in the observations (some individuals interact more often than others). |
rank.biased |
Boolean (TRUE/FALSE) describing whether to introduce a rank difference bias in the observations (closely-ranked individuals interact more often). |
This function is useful for generating input data with a known hierarchy. The shape of the hierarchy can be controlled using two parameters, though is by default a sigmoidal shape. Higher values of a typically create a greater probability of a dominant winning (turn the function into more of a threshold). Higher values of b typically decrease the probability of a dominant winning when ranks are very similar. The plot_winner_prob function allows visualisation of the hierarchy function (see examples below).
Returns a list with two elements: hierarchy: A dataframe containing three columns, the ID of the individual, its Rank, and its Probability of interacting (varies if id.biased=TRUE). interactions: A dataframe containing two columns, the Winner and the Loser for each interaction. Each row represents one interaction.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
par(mfrow=c(2,2)) # Set population size N <- 20 # Set shape parameters a = 15 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE) # Set new shape parameters a = 3 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE)par(mfrow=c(2,2)) # Set population size N <- 20 # Set shape parameters a = 15 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE) # Set new shape parameters a = 3 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE)
This function takes a set of winners and losers from observed interactions and plots the probability of the dominant individual in an interaction winning given the difference in rank to the subordinate in the same interaction.
plot_hierarchy_shape(identity, rank, winners, losers, fitted = FALSE)plot_hierarchy_shape(identity, rank, winners, losers, fitted = FALSE)
identity |
A vector containing the identities of all individuals in the data. |
rank |
A vector giving the ranks for each individual (in the same order as the identities). |
winners |
A vector giving the identity of the winner for each interaction. |
losers |
A vector giving the identity of the loser for each interaction in the same order as the winners. |
fitted |
A Boolean (TRUE/FALSE) describing whether to add a fitted line to the plot |
This function is useful for examining how the probability of winning is shaped by the difference in rank. The shape of this graph provides information about the shape of the dominance hierarchy.
This function will return the data for x (difference in rank) and y (probability of dominant winning) coordinates of the plot as a data frame.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
par(mfrow=c(1,2)) # Set population size N <- 20 # Set shape parameters a = 15 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank shape <- plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE) # Data is contained in shape shapepar(mfrow=c(1,2)) # Set population size N <- 20 # Set shape parameters a = 15 b = 3 # See what this looks like plot_winner_prob(1:N,a,b) # Generate some input data data <- generate_interactions(N,400,a,b) # See what the hierarchy looks like from the output data winners <- data$interactions$Winner losers <- data$interactions$Loser identities <- data$hierarchy$ID ranks <- data$hierarchy$Rank shape <- plot_hierarchy_shape(identities,ranks,winners,losers,fitted=TRUE) # Data is contained in shape shape
Function to plot the ranking of individuals in different ways.
plot_ranks(ranks, plot.CIs = FALSE, ordered.by.rank = TRUE, identities = NULL, plot.identities = TRUE, colors = NULL)plot_ranks(ranks, plot.CIs = FALSE, ordered.by.rank = TRUE, identities = NULL, plot.identities = TRUE, colors = NULL)
ranks |
Either a vector containing the score or rank of each individual, or an NxK matrix containing the results of K randomisations of the data. |
plot.CIs |
Boolean (TRUE/FALSE): if providing an NxK matrix, then setting plot.CIs to TRUE will plot the 95% range of the scores or ranks given for each individual. |
ordered.by.rank |
Boolean (TRUE/FALSE) describing whether to order individuals by rank or not. |
identities |
A vector containing the identity (name) of each individual to be plotted along the X axis. |
plot.identities |
Boolean (TRUE/FALSE) describing whether to plot the identity of each individual along the X axis. |
colors |
A vector containing the colour for each individual (default="black"). This is useful for example to colour individuals by sex. |
A simple function that plots individuals' ranks, with options to colour individuals or order them. Here the y axis is reverse, so that rank=1 occurs at the top.
Generates a plot. No data is returned.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Generate data data <- generate_interactions(N,100,a,b) # Extract data (and turn IDs into letters for this example) winners <- letters[data$interactions$Winner] losers <- letters[data$interactions$Loser] identities <- letters[data$hierarchy$ID] # Calculate Elo scores scores <- elo_scores(winners,losers,identities=identities,randomise=TRUE) # Plot results plot_ranks(scores, plot.CIs=TRUE,identities=TRUE,colors=rainbow(N))# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Generate data data <- generate_interactions(N,100,a,b) # Extract data (and turn IDs into letters for this example) winners <- letters[data$interactions$Winner] losers <- letters[data$interactions$Loser] identities <- letters[data$hierarchy$ID] # Calculate Elo scores scores <- elo_scores(winners,losers,identities=identities,randomise=TRUE) # Plot results plot_ranks(scores, plot.CIs=TRUE,identities=TRUE,colors=rainbow(N))
Plot the trajectories of Elo scores after each interaction
plot_trajectories(trajectories, colors = NULL)plot_trajectories(trajectories, colors = NULL)
trajectories |
The output of |
colors |
An optional vector of colours for each line (default = "black"). |
Plots one set of trajectories. If the randomise option in elo_scores is set to TRUE, then the resulting matrices should be passed one at a time.
Generates a plot. No data is returned.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Generate data data <- generate_interactions(N,100,a,b) # Extract data (and turn IDs into letters for this example) winners <- letters[data$interactions$Winner] losers <- letters[data$interactions$Loser] identities <- letters[data$hierarchy$ID] # Calculate Elo scores scores <- elo_scores(winners,losers,identities=identities, randomise=FALSE,return.trajectories=TRUE) # Plot results plot_trajectories(scores, colors=rainbow(N))# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Generate data data <- generate_interactions(N,100,a,b) # Extract data (and turn IDs into letters for this example) winners <- letters[data$interactions$Winner] losers <- letters[data$interactions$Loser] identities <- letters[data$hierarchy$ID] # Calculate Elo scores scores <- elo_scores(winners,losers,identities=identities, randomise=FALSE,return.trajectories=TRUE) # Plot results plot_trajectories(scores, colors=rainbow(N))
A simple function that provides visualisations of the shape of the hierarchy given parameters a and b in the generate_interactions function
plot_winner_prob(diff.rank, a, b)plot_winner_prob(diff.rank, a, b)
diff.rank |
A vector containing the x values of the plot (i.e. differences in rank). |
a |
Parameter a (see |
b |
Parameter b (see |
A simple plotting function to visualise the shapes of curves in the generate_interactions function.
Generates a plot. No data is returned.
Written by Damien R. Farine & Alfredo Sanchez-Tojar
Maintainer: Damien R. Farine <[email protected]>
Sanchez-Tojar, A., Schroeder, J., Farine, D.R. (in prep) Methods for inferring dominance hierarchies and estimating their uncertainty.
# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Plot the shape plot_winner_prob(1:10,a,b)# Set population size N <- 10 # Set shape parameters a = 15 b = 3 # Plot the shape plot_winner_prob(1:10,a,b)