Release:

Development (master):

CRAN:

dispRity is a R modular package for measuring disparity from multidimensional matrices.

Check out the paper associated with this package.

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

Installing dispRity

if(!require(devtools)) install.packages("devtools")
library(devtools)
install_github("TGuillerme/dispRity", ref = "release")
library(dispRity)

The following installs the latest release of dispRity (see patch notes below). For the piping hot development version (not recommended), replace the ref = "release" option with ref = "master". If you're using the master branch, see the patch notes for the latest developments.

The package is available in the CRAN Task Views in Phylogenetics.

Can't install the latest version of dispRity from the CRAN?

The latest dispRity package version 1.5 requires R 4.0 to run. If you don't have your R version updated to 4.0 you can either:

• 1. update your R version to the latest; this is suggested: since the amazing R CRAN team always update their software for a good reason (and for free!);
• 2. if for some reason you really can't update your R version, you can simply download the released github version of the package using: devtools::install_github("TGuillerme/dispRity", ref = "release").

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.

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 pre-print on selecting the best metric for your specific question on biorXiv or the moms shiny app. You can also find more information in the dispRity manual.

Latest major patch notes

• 2020/09/25 v1.5 between groups

  • New function: multi.ace for performing fast ancestral character estimations on multiple matrices (based on castor::asr_mk_model).
  • New function: reduce.space, a function to modify trait spaces imported from the moms shiny app. This function comes with a new reduction algorithm: the "evenness" algorithm for flattening the curve (thanks to Gavin Thomas for the suggestion).
  • New function: test.metric (and associated plot, print and summary functions), to apply the reduce.space function on a specific space and metric to test whether a metric is picking up specific changes in trait space.
  • the dispRity function can now use "between.groups" metrics to calculate disparity between groups rather than within groups. The make.metric function is now modified to allow detection of metrics that can be applied between groups.
  • New metric: group.dist, a dimension level 1 metric for between groups that measures the distance between two groups. By default, this is the minimum distance but the function takes the probs argument allowing the distance to be between, says, the 95% CI (probs = c(0.025, 0.975))) or between the centroids (probs = c(0.5)).
  • New metric: point.dist, a dimension level 2 metric for between groups that measures the distance between the rows in matrix to a point in matrix2. That point is the centroid by default but the point argument can take any function.
  • The dispRity package now depends on R (>= 4.0.0).
  • Many updates to the dispRity manual.
  • Many minor speed improvements across the package
  • Simplified syntax for the internal plot.dispRity S3 methods (for a potential ggpRity?). These changes should not be apparent at the user level but see the two removed options below:
  • removed option in plot.dispRity: the chrono.subsets option (TRUE/FALSE) has now been removed. The time-slicing-ness is now automatically detected or can be specified by the user normally through xlab.
  • removed option in plot.dispRity: the ylim, ylab, xlab and col options have now been removed. They are now handled through ... as normal generic plot(...) arguments.
  • removed option in plot.dispRity: the elements.pch option has now been removed. The pch of the plotted elements can now be passed like other options directly to elements (e.g. elements = list(pch = 15)).
  • removed option in plot.dispRity: the dimensions, matrix, nclass and coeff options have now been removed. Any options for dual class plots (randtest, dtt, model.test, type = "preview" etc...) are now handled through the generic specific.args argument.
  • New option in dtt.dispRity: scale.time allowing to scale the time axis (like in geiger::dtt) or not.
  • when plotting chrono.subsets dispRity objects, the x label ticks are now rounded if possible (for nicer looking plots!).
  • when using automatic chrono.subsets time slices, the name of the time slices (their age) is now rounded for aesthetics.

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

Authors and contributors

• Thomas Guillerme
• Natalie Cooper
• Mark Puttick

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

Some ideas/functionalities/implementations in this package where implemented following the suggestions of Natalie Cooper, Graeme Lloyd, Dave Bapst, Andrew Jackson and Martin Brazeau.

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. The Ecological and Evolutionary Drivers of Spatial Biodiversity Patterns. Doctoral Thesis at the Australian National University 2020 Open Researcg

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