gobbios/elosteepness

EloSteepness is a package that allows estimating steepness of dominance hierarchies from interaction networks. It does so by estimating Bayesian Elo-ratings, from which the steepness metric can be calculated. The major difference from classic approaches is that we obtain posterior steepness distributions, not point estimates. More details on the theoretical background can be found in the accompanying paper (preprint is here).

Below are the instructions to install EloSteepness.

Installation

In order to get the package up and running you need a fairly recent version of R (I'd recommend at least v4.0). You also need a working installation of rstan. Since the package is on CRAN now, installation should be easy with a simple call to:

install.packages("EloSteepness")

This also should take care of installing all necessary dependencies, including Stan. If you run the following code and it results in a figure, you are good to go.

library("EloSteepness")
data(dommats, package = "EloRating")
# using small numbers for iterations etc to speed up running time
set.seed(123)
res <- elo_steepness_from_matrix(dommats$elephants, n_rand = 3, cores = 2,
                                 iter = 1000, warmup = 500, 
                                 refresh = 0, chains = 2, seed = 1)
plot_steepness(res)
summary(res)

If this failed, you can try the following: The easiest way of installing Stan is to install the brms package. (brms is not actually required for EloSteepness to work, but it handles the installation of rstan and friends very conveniently.) If you don't want to deal with brms, you can also try to install rstan by itself (see here for instructions). If you already have brms (or rstan) then you are probably good to go. If not, then execute the following command and if asked for whether you want to install packages from source select 'no' (unless you know what you are doing of course).

install.packages("brms")

The only other thing you need are two more packages, EloRating and aniDom, which are easy to install:

install.packages("EloRating")

install.packages("aniDom")

For good measure, it might be good idea to restart R (or RStudio if you work with it) at this point. If you want to be on the safe side, you'd even restart your computer at this point, but this shouldn't be necessary in most cases.

With this done, you can install EloSteepness. There are two ways of doing that. Depending on the level of experience with R, I would recommend option 1 only to more advanced users and option 2 to novices.

1) directly from GitHub

For this to work you'll need the devtools package (which you can get via install.packages("devtools")). Also required is a working package building tool chain. To check whether this is available run:

devtools::has_devel()

If that gives positive feedback then you are set. If not, you need to install more stuff (on MacOS you need the Xcode command line tools (e.g. here), and on Windows the Rtools here).

I've also seen cases where problems arose because the version of devtools was outdated, so even if you have it installed already it might be a good idea to update the package (also with install.packages("devtools")).

Next, you need to decide whether or not you want to build the vignettes alongside installing the package.

1a) directly from GitHub - with vignettes

In order to make the tutorial accessible from within R, you need two more things: $\LaTeX$ and pandoc. The easiest way of getting the former done (unless you have it already) is to use:

install.packages("tinytex")
tinytex::install_tinytex()
tinytex:::install_yihui_pkgs()

Next, install pandoc. If you are using RStudio you can skip this latter step (pandoc comes with RStudio), and proceed directly to:

devtools::install_github("gobbios/EloSteepness", build_vignettes = TRUE, dependencies = TRUE)

This will take several minutes.

To check whether the installation worked, restart R/RStudio and try to open the tutorial that comes with the package.

vignette("tutorial", package = "EloSteepness")

1b) directly from GitHub - without vignettes

If you are happy with downloading the tutorial manually here, things should be a little simpler:

devtools::install_github("gobbios/EloSteepness", build_vignettes = FALSE)

This still might take several minutes to complete.

2) from local file

Here you download the package as a single file and then install it from there. Start by downloading the package file from here.

If you are on Windows, download the EloSteepness_0.4.6.zip file and run (and don't forget to change the path and use the correct file name):

install.packages("C:/Users/myname/Downloads/EloSteepness_0.4.6.zip", 
                 dependencies = TRUE, 
                 repos = NULL, type = "win.binary")

If you are on MacOS, download the EloSteepness_0.4.6.tgz file and run (and don't forget to change the path and use the correct file name):

install.packages("~/Downloads/EloSteepness_0.4.6.tgz", 
                 dependencies = TRUE, 
                 repos = NULL, type = "mac.binary")

Depending on your hardware, this can take up to several minutes to complete. After this is done, I would again recommend to restart R.

To check whether the installation worked, try to open the tutorial.

vignette("tutorial", package = "EloSteepness")

If this didn't work or you feel a bit more adventurous, choose the file EloSteepness_0.4.6.tar.gz for download (don't unpack it!), and remember the path you saved it to... Then depending on what OS you use, adapt to your needs and run one of the following code chunks (don't forget to change the path and use the correct file name):

# something like this on MacOS or Linux
install.packages("~/Downloads/EloSteepness_0.4.6.tar.gz",  
                 repos = NULL, type = "source")

# something like this on Windows
install.packages("C:/Users/myname/Downloads/EloSteepness_0.4.6.tar.gz",  
                 repos = NULL, type = "source")

And finally, if you are just interested in the tutorial, you can find it here.

First steps

Please refer to the tutorial to go through some examples. Either download it here or use vignette("tutorial", package = "EloSteepness") to launch it directly from R.

elosteepness's Issues

R CMD check failures due to probabilistic unit tests

R CMD check will occasionally result in errors because two tests fail (remove_dyads and generate_interaction_probs). These failures occur because the tests are not deterministic but probabilistic, i.e. they pass in the majority of runs, but crucially not always.

new function for numeric summaries of individual scores

Write a function that allows extraction of numeric summaries for individual scores, either cumulative winning probabilities or Bayesian David's scores.

allow setting specific colours in plotting functions

This is mostly useful for the paper/vignette when multiple plots should have the same colours for the same individuals.

create summary function

for the results of the modelling functions. Which probably will entail assigning the results of the modelling function S3 classes.

test failure test-remove_dyads

From CRAN:

  ── Failure ('test-remove_dyads.R:16'): multiplication works ────────────────────
  rev(r0$summary$prunk)[1] <= rem is not TRUE
  
  `actual`: FALSE
  `expected`: TRUE
  
  [ FAIL 1 | WARN 0 | SKIP 0 | PASS 54 ]
  Error: Test failures
  Execution halted

make 'fixed_sd' the default for the Elo steepness function