Measuring Disparity

A modular package for measuring disparity from multidimensional matrices. Disparity can be calculated from any matrix defining a multidimensional space. The package provides a set of implemented metrics to measure properties of the space and allows users to provide and test their own metrics. The package also provides functions for looking at disparity in a serial way (e.g. disparity through time) or per groups as well as visualising the results. Finally, this package provides several basic statistical tests for disparity analysis.


Release:

Build Status codecov Project Status: Active - The project has reached a stable, usable state and is being actively developed. develVersion DOI

Development (master):

Build Status codecov Project Status: Active - The project has reached a stable, usable state and is being actively developed. develVersion DOI

CRAN:

minimal R version cran version rstudio mirror downloads

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.

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.

Latest patch notes

  • 2018/09/19 - v1.2 model tests

    • New functions: model.test, model.test.sim and model.test.wrapper for fitting models of disparity evolution through time (with associated manuals, vignettes and S3 methods! Thanks to Mark Puttick).
    • New argument in boot.matrix: prob for passing probabilities of sampling for specific elements.
    • S3 print method for objects of class "dtt" and "dispRity" (from dtt.dispRity).
    • tydiversed most of the error messages.
    • dtt.dispRity now allows to specify the alternative hypothesis (if nsim > 0).
    • ellipse.volume can now take an explicit eigen value vector (the eigen values are still automatically estimated correctly for PCO and MDS).
    • Improved metric checking messages from make.metric when dealing with optional arguments.
    • Removed cascade of warnings triggered by plot.dispRity.dtt.
    • Corrected char.diff to properly reflect the probability of different splits between characters (thanks to Abigail Pastore).

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

Authors and contributors

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

To cite the dispRity manual, please use:

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

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

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.

Used in

  • JW Clark, PCJ Donoghue (2018) Whole-Genome Duplication and Plant Macroevolution. Trends in plant science. DOI: 10.1016/j.tplants.2018.07.006

  • D Foffa, MT Young, TL Stubbs, KG Dexter, SL Brusatte (2018) The long-term ecology and evolution of marine reptiles in a Jurassic seaway. Nature Ecology & Evolution. DOI: 10.1038/s41559-018-0656-6

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

News


<!-- dispRity 0.2.0 (2016-04-01)

NEW FEATURES

  • Blabla

MINOR IMPROVEMENTS

  • Blabla

BUG FIXES

  • Blabla

DEPRECATED AND DEFUNCT

  • Blabla --> [GitHub release] dispRity v1.2.1 model tests (2018-09-19) =========================

NEW FEATURES

  • CRAN release 2 (v.1.2) with the additional Claddis.ordination function.

[CRAN release] dispRity v1.2 model tests (2018-09-19)

NEW FEATURES

  • New functions: model.test, model.test.sim and model.test.wrapper for fitting models of disparity evolution through time (with associated manuals, vignettes and S3 methods! Thanks to Mark Puttick).
  • New argument in boot.matrix: prob for passing probabilities of sampling for specific elements.
  • S3 print method for objects of class "dtt" and "dispRity" (from dtt.dispRity).

MINOR IMPROVEMENTS

  • tydiversed most of the error messages.
  • dtt.dispRity now allows to specify the alternative hypothesis (if nsim > 0).
  • ellipse.volume can now take an explicit eigen value vector (the eigen values are still automatically estimated correctly for PCO and MDS).
  • Improved metric checking messages from make.metric when dealing with optional arguments.
  • Removed cascade of warnings triggered by plot.dispRity.dtt.

BUG FIXES

  • Corrected char.diff to properly reflect the probability of different splits between characters (thanks to Abigail Pastore).

dispRity v1.1 got CRAN (2018-03-20)

NEW FEATURES

  • CRAN release 1 with the additional Claddis.ordination function.

MINOR IMPROVEMENTS

  • Added default Cailliez correction to Claddis.ordination function (with add = TRUE).
  • Improved test coverage.

[CRAN release] dispRity v1.0.3 got CRAN (2018-03-20)

NEW FEATURES

  • First CRAN release

MINOR IMPROVEMENTS

  • Registered C symbols properly.
  • Overall improvement for the S3 methods.
  • Changed name: scale.dispRity is now rescale.dispRity.
  • Changed name: merge.subsets is now combine.subsets.
  • Changed name: time.subsets is now chrono.subsets - time.subsets can still be called as an alias for the same function.

BUG FIXES

  • Minor bug fixes and typos in various error messages and in the manual.

DEPRECATED AND DEFUNCT

  • Removed Claddis.ordination function to comply with the CRAN requirement (this function is still live in the GitHub version 1.1).

dispRity v0.5 covered with tests (2017-12-20)

NEW FEATURES

  • custom.subset can now automatically create clade-based groups if a phylo object is passed to group.
  • New utility function: extinction.subsets, to get the list to be passed to test.dispRity for testing the effect of extinction.
  • New test function: dtt.dispRity, a wrapper for geiger::dtt. This version is slower that geiger::dtt but allows any univariate disparity metric!
  • New test function: adonis.dispRity, a wrapper for vegan::adonis.
  • New utility function: crown.stem for separating a tree into crown and stem groups.
  • New disparity metric: span.tree.length the length of the minimum spanning tree.
  • New disparity metric: pairwise.dist: the element's pairwise distances.
  • New disparity metric: radius: the radius of each dimensions.
  • New disparity metric: n.ball.volume: the n-dimensional sphere or ellipsoid volume.
  • New argument in time.subsets, model = "equal.split" and model = "gradual.split" that retain the probability of being either the descendant or the ancestor. This probability is passed to boot.matrix .

MINOR IMPROVEMENTS

  • Changed calls to stats::dist to vegan::vegdist to allow more distances to be passed through methods arguments.
  • slice.tree can now slice through a single edge.
  • Various minor speed improvements.

BUG FIXES

  • Correct behaviour in tree.age to estimate ages for trees with fossils only.

DEPRECATED AND DEFUNCT

  • Change name throughout the package, subsample is now replaced by subset (e.g. time.subsamples is now renamed time.subsets, data$subsamples is now data$subsets, etc...).
  • Changed argument in time.subsets, model = "gradual" is now replaced by model = "proximity" and model = "punctuated" is now replaced by model = "random".

dispRity v0.4.1 (2017-11-13)

NEW FEATURES

  • New disparity metric: ancestral.distance to get the distance from taxa/nodes to their ancestors.
  • New function: random.circle for generating random circle coordinates (see example in space.maker for creating doughnut spaces!).
  • New function: get.bin.ages for getting the geological timescale of a tree (based on geoscale).

MINOR IMPROVEMENTS

  • Added a t0 argument to time.subsamples allowing to set the start age of the first subsample.
  • Allowing subsamples to contain less than three elements (up to 0!).

BUG FIXES

  • Fixed fuzzy match issues in slice.tree.

dispRity v0.4 user friendly (2017-08-21)

NEW FEATURES

  • Entirely rewritten manual (in GitBook)!
  • New function: Claddis.ordination and geomorph.ordination for automatically ordinating data from Claddis and geomorph packages!
  • New function: char.diff for calculating character differences and associated plot function (plot.char.diff)
  • New utility function: merge.subsamples for... merging subsamples.
  • New utility function: size.subsamples for getting the size of subsamples in a disparity object.
  • New wrapping functions: dispRity.through.time and dispRity.per.group now runs easy default disparity analysis.

MINOR IMPROVEMENTS

  • Input ordinated matrices do not need to be of maximum size n*(n-1). Bigger matrices now only trigger a warning.
  • Added dimensions optional argument to dispRity to overwrite the number of dimensions generated by boot.matrix.
  • variances, ranges and centroids are now simplified for speed. The optional arguments for data cleaning are now passed to make.metric.
  • space.maker now allows to approximate the dimensions variance distribution with the scree option.

DEPRECATED AND DEFUNCT

  • Removed hyper.volume metric for dependencies reasons,
  • Removed parallel option from boot.matrix (the new architecture is already super fast: <2sec for 5k taxa and 10k bootstraps!).
  • Changed name: series as a part of dispRity objects is now changed to subsamples throughout the whole package.
  • Changed name: time.series is now renamed time.subsamples, if dates are provided and method is discrete, this function doesn't need a phylogeny any more.
  • Changed name: get.subsamples.dispRity is now renamed get.subsamples.
  • Modified function: cust.series is now renamed custom.subsamples (to avoid confusion with custard.subsamples!). Its factor argument as been changed to groups and can now take a simple list.

dispRity v0.3 dispRity lite (2017-01-25)

NEW FEATURES

  • Complete change of the dispRity object architecture (see more here).

MINOR IMPROVEMENTS

  • sim.morpho can now use model = "mixed" for using both HKY-binary and Mk in characters simulation.
  • dispRity object utilities are now all grouped under the ?dispRity.utilities manual with appropriate S3 methods.

DEPRECATED AND DEFUNCT

  • Removed rm.last.axis argument in boot.matrix. It is now replaced by dimensions.
  • Changed argument in plot.dispRity, type = "lines" is now replaced by type = "line".

dispRity v0.2.1 making stuff up (2016-11-07)

NEW FEATURES

  • New utility function: merge.time.series for cleaning or merging time series,.
  • New vignette: dispRity-simulate_data on how to simulate morphological characters in dispRity.
  • New function: sim.morpho generates morphological matrices.
  • New function: check.morpho for checking how "realistic" the simulate morphological matrices are.
  • New utility functions: get.contrast.matrix and apply.inapplicable functions for morphological matrices.

MINOR IMPROVEMENTS

  • Minor updates for the graphical functions.

dispRity v0.2 (2016-06-15)

NEW FEATURES

  • New utility functions: pair.plot, scale.dispRity and sort.dispRity.
  • New function: space.maker for creating some multidimensional spaces!
  • New disparity metrics: convhull.surface, convhull.volume and hyper.volume.
  • New disparity test null.test.
  • New plot.dispRity arguments: density for controlling the polygons density and add for adding plots.

MINOR IMPROVEMENTS

  • Many updates to the functions manual and vignettes.
  • Some algorithm are now greatly improved for speed.
  • Disparity can now be calculated as a distribution (i.e. dispRity, test.dispRity, plot.dispRity, and summary.dispRity can now intake one or more distribution rather than just one or more single values of disparity; whether the data is bootstrapped or not).
  • dispRity can now intake dispRity objects with level 2 disparity metrics.
  • boot.matrix and dispRity can now run in parallel.
  • centroids disparity metric can now use a centroid argument for fixing the centroid point value.
  • variances and ranges disparity metrics can now intake a k.root argument for scaling the results.

BUG FIXES

  • Minor functions corrections for specific optional arguments combinations.

DEPRECATED AND DEFUNCT

  • Removed type_discrete argument in plot.dispRity and type argument can now be:
    • continuous disparity curves.
    • box for real boxplots.
    • lines for the distribution vertical lines.
    • polygon for the distribution boxes.

dispRity v0.1.2 (2015-12-01)

NEW FEATURES

  • New function: get.dispRity for subsampling dispRity objects.
  • New function: extract.dispRity for extracting disparity results.
  • New function: test.dispRity for applying tests to dispRity objects.
  • New function: make.metric for helping creating your very own disparity metric.
  • New metric: hyper.volume for measuring the morphospace hyper-ellipsoid volume.

MINOR IMPROVEMENTS

  • metric argument from dispRity can now intake up two three functions (see dispRity.metric and make.metric).
  • Many improved functions manuals and examples!
  • Improved vignettes:
    • dispRity palaeo demo a quick demo aimed more for palaeobiologist.
    • dispRity ecology demo a quick demo aimed more for ecologists.
    • dispRity manual for people that want to know the package in details.
    • dispRity metrics for explaining how the disparity metric implementation works.

dispRity v0.1.1 (2015-10-08)

MINOR IMPROVEMENTS

  • plot.dispRity options improved (rarefaction + default).
  • cust.series can now intake multiple factors columns.
  • Added example for ecological data.
  • boot.matrix, dispRity, summary and plot now also include observed values.
  • plot now has an observed option to plot the observed disparity.

BUG FIXES

  • Fixed many error/warning messages.

DEPRECATED AND DEFUNCT

  • Changed taxa to elements.
  • plot option diversity has been renamed elements.

dispRity v0.1 (2015-10-01)

  • First release!

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("dispRity")

1.2.3 by Thomas Guillerme, 2 months ago


https://github.com/TGuillerme/dispRity


Browse source code at https://github.com/cran/dispRity


Authors: Thomas Guillerme [aut, cre, cph] , Mark N Puttick [aut, cph]


Documentation:   PDF Manual  


Task views: Phylogenetics, Especially Comparative Methods


GPL-3 | file LICENSE license


Imports ade4, Claddis, geiger, geometry, geoscale, graphics, grDevices, methods, mnormt, paleotree, phangorn, phyclust, utils, vegan

Depends on ape, stats

Suggests testthat, knitr


See at CRAN