1 dispRity

This is a package for measuring disparity in R. It allows users to summarise matrices as representations as multidimensional spaces into a single value or distribution describing a specific aspect of this multidimensional space (the disparity). Multidimensional spaces can be ordinated matrices from MDS, PCA, PCO, PCoA but the package is not restricted to any type of matrices! This manual is based on the version 1.3.

1.1 What is dispRity?

This is a modular package for measuring disparity in R. It allows users to summarise ordinated matrices (e.g. MDS, PCA, PCO, PCoA) to perform some multidimensional analysis. Typically, these analysis are used in palaeobiology and evolutionary biology to study the changes in morphology through time. However, there are many more applications in ecology, evolution and beyond.

1.1.1 Modular?

Because their exist a multitude of ways to measure disparity, each adapted to every specific question, this package uses an easy to modify modular architecture. In coding, each module is simply a function or a modification of a function that can be passed to the main functions of the package to tweak it to your proper needs! In practice, you will notice throughout this manual that some function can take other functions as arguments: the modular architecture of this package allows you to use any function for these arguments (with some restrictions explained for each specific cases). This will allow you to finely tune your multidimensional analysis to the needs of your specific question!

1.2 Installing and running the package

You can install this package easily, directly from the CRAN:

Alternatively, for the most up to data version and some functionalities not compatible with the CRAN, you can use the package through GitHub using devtool (see to CRAN or not to CRAN? for more details):

Note this uses the release branch (1.3). For the piping-hot (but potentially unstable) version, you can change the argument ref = release to ref = master. dispRity depends mainly on the ape package and uses functions from several other packages (ade4, geometry, grDevices, hypervolume, paleotree, snow, Claddis, geomorph and RCurl).

1.3 To CRAN or not to CRAN?

This package can be installed via the CRAN or via GitHub.

  • The CRAN version is a more “strict” version of the package that does not include some functionalities such as this gitbook vignette because of compatibility issues with the CRAN requirement.
  • The GitHub version is a more “reactive” version (fed by user’s suggestions and comments) and can contain more functionalities (see list below). This version exists on a "release" branch which is tested as strictly as the CRAN version with Travis and codecov. The "master" branch contains always the latest “piping hot”, not yet release version. It might (though rarely) be bugged.

Note however, that apart from the functions listed below, both versions of the package have the same tested and implemented functions.

1.3.1 So which version do I choose?

There are always three version of the package available:

  • The CRAN one
  • The GitHub release one
  • The GitHub master one

The differences between the CRAN one and the GitHub release or master ones is explained just above. For the the GitHub version, the differences are that the release one is more stable (i.e. more rarely modified) and the master one is more live one (i.e. bug fixes and new functionalities are added as they come).

If you want the latest-latest version of the package I suggest using the GitHub master one, especially if you recently emailed me reporting a minor bug or wanting a new functionality! Note however that it can happen that the master version can sometimes be bugged (especially when there are major R and R packages updates), however, the status of the package state on both the release and the master version is constantly displayed on the README page of the package with the nice badges displaying these different (and constantly tested) information.

1.4 Help

If you need help with the package, hopefully the following manual will be useful. However, parts of this package are still in development and some other parts are probably not covered. Thus if you have suggestions or comments on on what has already been developed or will be developed, please send me an email (guillert@tcd.ie) or if you are a GitHub user, directly create an issue on the GitHub page.

1.5 Citations

To cite the package, this manual or some specific functionalities, you can use the following references:

The package main paper:

Guillerme T. dispRity: A modular R package for measuring disparity. Methods Ecol Evol. 2018;9:1755–1763. doi.org/10.1111/2041-210X.13022.

The package manual (regularly updated!):

Guillerme, T. & Cooper, N. (2018): dispRity manual. figshare. Preprint. 10.6084/m9.figshare.6187337.v1.

The time-slicing method implemented in chrono.subsets (unfortunately not Open Access, but you can still get a free copy from here):

Guillerme, T. and Cooper, N. (2018), Time for a rethink: time sub-sampling methods in disparity-through-time analyses. Palaeontology, 61: 481-493. doi:10.1111/pala.12364.