Release:

Development (master):

CRAN:

dispRity is a R modular package for measuring disparity in multidimensional spaces.

Check out the paper associated with the first version of this package.

Check out the presentation or the video of some of the package's features.

Installing dispRity

install.packages("dispRity")
library(dispRity)

The package is also available in the phylotastic r-universe or through the phylogenetics or paleontology CRAN Task Views.

You can also install the piping hot development version (not always recommended!) by installing the package directly through github:

if(!require(devtools)) install.packages("devtools")
library(devtools)
install_github("TGuillerme/dispRity")
library(dispRity)

See the patch notes for the latest developments.

Vignettes and manuals

A detailed vignette is available online or as a pdf:

Otherwise, each functions has a detailed associated manual with examples in R (?which.function).

Additionally, you can learn more about the structure of dispRity objects here.

Workshop

You can download the workshop follow-along sheet here (use right click > save link as...) or visualise it in html here.

Disparity/dissimilarity metrics/indices?

Not sure what disparity metric to use?
Not sure what a disparity metric is in the first place?
Check out this paper on selecting the best metric for your specific question in Ecology and Evolution or the moms shiny app.
You can also find more information in the dispRity manual.

You can also check this lecture on how to choose disparity metrics.

Latest major patch highlights

dispRity v1.9 (2024-11-12) distant update

Read the full patch note here.

• dispRity has been not greatly optimised for using distance matrices: 1) it's now much faster thanks to the dist.helper new optional argument (storing the distance matrix in the cache) and 2) it now allows direct analyses of distance matrices in a dispRity pipeline.
• boot.matrix function has now been generalised to be able to bootstrap any elements of a matrix. Previously it only allowed to bootstrap elements (rows) but now can work on dimensions (columns) or both (distances).
• Redesigned multi.ace to be more modular and better handle both continuous and/or discrete characters. This is secretly a pre-release for a future version that will greatly improve pipelines with ancestral state estimations ;).
• New utility functions (set.root.time to add root times to trees; remove.dispRity to cleanly remove parts of dispRity objects) and metrics (count.neigbhours).
• Loads of minor improvements and couple of bug fixes! Yay!

Previous patch notes and notes for the next version can be seen here.

Authors

• Thomas Guillerme
• Natalie Cooper
• Mark Puttick
• Jack Hatfield

Contributors (bug fixes, pull requests and suggestions)

Dave Bapst, Mario Corio, Armin Elsler, Graeme Lloyd (Request #104), Jari Oksanen (Request #85), Emmanuel Paradis, Abigail Pastore, Ashley Reaney, Gavin Thomas.

Citations

If you are using this package, please cite the paper:

• Guillerme, T. (2018) dispRity: a modular R package for measuring disparity. Methods in Ecology and Evolution. doi:10.1111/2041-210X.13022

  Export citation

Also don't forget to cite R and consider citing the ape package since dispRity heavily relies on it (and, generally, cite all the R packages you use!):

• Paradis E. & Schliep K. (2019). ape 5.0: an environment for modern phylogenetics and evolutionary analyses in R. Bioinformatics 35: 526-528.
• R Core Team (2020). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. URL https://www.R-project.org/.

  or use citation() and citation("ape") in R to get the latest citation format

To cite the dispRity manual, please use:

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

  BibTex, EndNote, RefWorks, DataCite, more...

To cite the time slicing method from the chrono.subsets function, please use:

• Guillerme, T. & 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

  Export citation

Acknowledgments

I have been developping this package while being hired succesively by these people (thanks a lot for supporting me develop this package, sometimes as a side project): Natalie Cooper, Martin Brazeau, Vera Weisbecker and Gavin Thomas.

If you use the dispRity pacakge for morphological disparity analyses, you should also check the excellent Claddis package!

Examples of papers using the dispRity package

The dispRity package was cited in these papers. Below is a list of specific papers using specific functionalities. These papers do not only use the functionalities highlighted here (and the author do much more awesome science!) but this is just a list of references if you want an independent guide on how to use these functions:

Measuring disparity with dispRity (using multiple metrics!)

• 
  Ezcurra MD, Montefeltro FC, Pinheiro FL, Trotteyn MJ, Gentil AR, Lehmann OE, Pradelli LA. The stem-archosaur evolutionary radiation in South America. Journal of South American Earth Sciences. 2020 Oct 7:102935. Journal of South American Earth Sciences. 2020 DOI: 10.1016/j.jsames.2020.102935

Using different time binning with chrono.subsets

• 
  Godoy PL. Crocodylomorph cranial shape evolution and its relationship with body size and ecology. Journal of Evolutionary Biology. 2020 DOI: 10.1111/jeb.13540

Simulating discrete morphological data with sim.morpho:

• 
  Schaeffer J, Benton MJ, Rayfield EJ, Stubbs TL. Morphological disparity in theropod jaws: comparing discrete characters and geometric morphometrics. Palaeontology. 2020. DOI: 10.1111/pala.12455

Calculating the Bhattacharrya Coefficient with bhatt.coeff:

• 
  Heggli OA, Cabral J, Konvalinka I, Vuust P, Kringelbach ML. A Kuramoto model of self-other integration across interpersonal synchronization strategies. PLoS computational biology. 2019 DOI:10.1371/journal.pcbi.1007422

Comparisons between groups using custom.subsets and test.dispRity:

• 
  Esquerré D, Donnellan S, Brennan IG, Lemmon AR, Lemmon EM, Zaher H, Grazziotin FG, Keogh JS. Phylogenomics, biogeography and morphometrics reveal rapid phenotypic evolution in pythons after crossing Wallace’s line. Systematic Biology. 2019 DOI: 10.1093/sysbio/syaa024

Bootstrapping data and comparing groups in ecospace using boot.matrix:

• 
  de Oca-Aguilar AC, De Luna E, Rebollar-Téllez EA, Piermarini PM, Ibáñez-Bernal S. Morphological discontinuous variation and disparity in Lutzomyia (Tricholateralis) cruciata Coquillett, 1907 are not related to contrasting environmental factors in two biogeographical provinces. Zoomorphology. 2019 DOI:10.1007/s00435-019-00450-8

Simulating disparity through time using dtt.dispRity:

• 
  Skeels A, Dinnage R, Medina I, Cardillo M. Ecological interactions shape the evolution of flower color in communities across a temperate biodiversity hotspot Evolution Letters 2021 10.1002/evl3.225

Using the wrapper disparity.per.group function:

• 
  Taverne M, Fabre AC, King‐Gillies N, Krajnović M, Lisičić D, Martin L, Michal L, Petricioli D, Štambuk A, Tadić Z, Vigliotti C. Diet variability among insular populations of Podarcis lizards reveals diverse strategies to face resource‐limited environments. Ecology and Evolution. 2019 DOI:10.1002/ece3.5626.

Disparity analyses jointly using the dispRity and Claddis packages

• 
  Wang M, Lloyd GT, Zhang C, Zhou Z. The patterns and modes of the evolution of disparity in Mesozoic birds. Proceedings of the Royal Society B. 2021 DOI:10;288(1944):20203105