Merge pull request #120 from TGuillerme/master

v1.7

.github/workflows/R-CMD-check.yaml

@@ -3,11 +3,13 @@
 on:
   push:
     branches:
+      - MCMCglmm
       - main
       - master
       - release
   pull_request:
     branches:
+      - MCMCglmm
       - main
       - master
       - release
@@ -29,6 +31,7 @@ jobs:
           - {os: ubuntu-20.04, r: 'release', rspm: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest"}
 
     env:
+      RGL_USE_NULL: true
       _R_CHECK_CRAN_INCOMING_: true # Seemingly not set by --as-cran
       _R_CHECK_FORCE_SUGGESTS_: false # CRAN settings
       R_COMPILE_AND_INSTALL_PACKAGES: 'never'
@@ -92,4 +95,4 @@ jobs:
         uses: actions/upload-artifact@main
         with:
           name: ${{ runner.os }}-r${{ matrix.config.r }}-results
-          path: check
+          path: check

.gitignore

@@ -1,6 +1,10 @@
+# security
+.coveralls.yml
+
 #pdf
 *.pdf
 *.Rapp.history
+*.png
 
 *.DS_Store
 
@@ -19,4 +23,4 @@ inst/old/*
 
 paper/*.fls
 
-inst/gitbook/_bookdown_files/*
+inst/gitbook/_bookdown_files/*

DESCRIPTION

@@ -3,9 +3,9 @@ Title: Measuring Disparity
 Author: Thomas Guillerme [aut, cre, cph],
 		Mark N Puttick [aut, cph]
 Maintainer: Thomas Guillerme <[email protected]>
-Version: 1.6.8
-Date: 2022-01-18
-Description: A modular package for measuring disparity (multidimensional space occupancy). 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 (Guillerme (2018) <doi:10.1111/2041-210X.13022>). The package also provides functions for looking at disparity in a serial way (e.g. disparity through time - Guillerme and Cooper (2018) <doi:10.1111/pala.12364>) or per groups as well as visualising the results. Finally, this package provides several statistical tests for disparity analysis.
+Version: 1.7.0
+Date: 2022-08-08
+Description: A modular package for measuring disparity (multidimensional space occupancy). 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 statistical tests for disparity analysis.
 Depends:
     R (>= 3.6.0),
     ape,
@@ -14,11 +14,11 @@ Imports:
 	ade4,
 	castor,
 	Claddis,
-	geiger,
+	ellipse,
 	geometry,
-	geoscale,
 	graphics,
 	grDevices,
+	MASS,
 	methods,
 	mnormt,
 	parallel,
@@ -32,7 +32,9 @@ License: GPL-3 | file LICENSE
 Remotes:
     github::myllym/spptest@no_fastdepth
 Suggests:
+	MCMCglmm,
+    geoscale,
     testthat,
     knitr
-RoxygenNote: 7.1.2
+RoxygenNote: 7.2.0
 URL: https://github.com/TGuillerme/dispRity

NAMESPACE

@@ -5,10 +5,11 @@ import(stats)
 importFrom("ade4", "randtest", "as.randtest")
 importFrom("castor", "get_subtree_with_tips", "get_all_pairwise_distances", "get_all_distances_to_root", "asr_mk_model")
 importFrom("Claddis", "calculate_morphological_distances")
-importFrom("geiger", "dtt", "ratematrix", "sim.char", "treedata")
+importFrom("ellipse", "ellipse")
 importFrom("geometry", "convhulln", "dot")
 importFrom("graphics", "abline", "axis", "boxplot", "hist", "image", "lines", "mtext", "par", "plot", "points", "polygon", "text", "layout", "legend", "barplot")
 importFrom("grDevices", "colorRampPalette", "grey", "hcl", "heat.colors", "adjustcolor")
+importFrom("MASS", "mvrnorm")
 importFrom("methods", "hasArg", "formalArgs")#, "is")
 importFrom("mnormt", "dmnorm", "rmnorm")
 # importFrom("paleotree", "timeSliceTree")
@@ -34,9 +35,13 @@ export(select.axes)
 export(boot.matrix)
 export(chrono.subsets)
 export(custom.subsets)
+export(covar.plot)
 export(dispRity)
+export(dispRity.fast)
+export(dispRity.covar.projections)
 export(dispRity.per.group)
 export(dispRity.through.time)
+export(MCMCglmm.subsets)
 export(plot.dispRity)
 export(print.dispRity)
 export(summary.dispRity)
@@ -54,6 +59,7 @@ export(diagonal)
 export(dimension.level1.fun)
 export(dimension.level2.fun)
 export(dimension.level3.fun)
+export(disalignment)
 export(displacements)
 export(ellipse.volume)
 export(edge.length.tree)
@@ -66,6 +72,7 @@ export(neighbours)
 export(pairwise.dist)
 export(point.dist)
 export(projections)
+export(projections.between)
 export(projections.tree)
 export(quantiles)
 export(radius)
@@ -85,14 +92,17 @@ export(randtest.dispRity)
 # export(sequential.test)
 
 ##dispRity object utilities
+export(as.covar)
+export(axis.covar)
 export(combine.subsets)
 export(extinction.subsets)
-export(extract.dispRity)
 export(fill.dispRity)
+export(get.disparity)
+export(get.matrix)
 export(get.subsets)
+export(get.covar)
 export(n.subsets)
 export(make.dispRity)
-export(matrix.dispRity)
 export(rescale.dispRity)
 export(size.subsets)
 export(sort.dispRity)
@@ -105,6 +115,11 @@ export(clean.data)
 export(crown.stem)
 export(get.bin.ages)
 export(make.metric)
+export(match.tip.edge)
+export(MCMCglmm.traits)
+export(MCMCglmm.levels)
+export(MCMCglmm.sample)
+export(MCMCglmm.covars)
 export(pair.plot)
 export(random.circle)
 export(randtest.dist)
@@ -127,7 +142,6 @@ export(multi.ace)
 
 ##S3 
 S3method(adonis, dispRity)
-S3method(dtt, dispRity)
 S3method(matrix, dispRity)
 S3method(plot, char.diff)
 S3method(plot, dispRity)

NEWS.md

@@ -23,33 +23,64 @@ dispRity 0.2.0 (2016-04-01)
 <!--   * `dtt.dispRity` now works with time-slicing. -->
 
 
-dispRity v1.6.8 (2022-01-24)
+dispRity v1.7 (2022-08-08) *MacMacGlimm*
 =========================
 
 ### NEW FEATURES
 
  * *New* data function: `select.axes` for selecting and analysing the number of axes required to contain an arbitrary amount of variance.
  * *New* utility function: `randtest.dist` for measuring the distance between the observed statistic and a specific quantile of the simulated statistic (thanks to [Frane Babarovic](https://twitter.com/FBabarovic) for the inspiration).
-
+ * `dispRity` objects can now contain covariance matrices as a `$covar` object. The `covar` part can be directly used for some specific metrics (usually `my_metric.covar`) and are handled by the `dispRity` function (and `plot`, `summary`, etc...) in a specific way. `$covar` contains a list of two elements `VCV` the variance covariance matrix and `loc` the coordinates of the centre of the `VCV` in space (can be left empty). `$covar` matrices are effectively treated as bootstraps.
+ * *New function* `covar.plot` for plotting the `covar` content of `dispRity` objects (this is separated from `plot.dispRity` because of the many different options).
+ * *New function*: `MCMCglmm.subsets` is a function that allows to convert a `MCMCglmm` object into a `dispRity` object.
+ * *New metric*: `projections.between` a between group metric for applying the `projections` metric between the major covariance axis of two matrices.
+ * *New metric*: `disalignment`: the (dis)alignment of a group compared to another one (i.e. the rejection from group B's centre on the group A's major axis).
+ a between group metric for applying the `projections` metric between the major covariance axis of two matrices.
+ * New `dispRity.fast` function for the fastest disparity calculations at the expanses of pretty much everything this package does. This is a really situational function.
+ * *New utility functions* for manipulating `MCMCglmm` objects: `MCMCglmm.traits` for extracting the number of traits, `MCMCglmm.levels` for extracting the level names, `MCMCglmm.sample` for sampling posterior IDs and `MCMCglmm.covars` for extracting variance-covariance matrices
+ * *New utility functions* for `dispRity` objects with `covar` matrices: `get.covar` to extract the VCV matrices (or a subsample of them); `axes.covar` to extract the major axes of the VCV matrices and `as.covar` to transform `dispRity` metric function to use a covar object.
+ * *New utility function* `match.tip.edge` for matching tip labels as factors/characters/integer to tree edges.
+ * *New wrapper function* `dispRity.covar.projections` for covariance projections analyses (with its associated S3 sub-class).
+ * One new demo datasets: `charadriiformes`, a `data.frame` and a `phylo` object of 359 _Charadriiformes_ species (gulls, plovers and sandpipers) from [Cooney et al 2017](https://www.nature.com/articles/d41586-021-02480-z) along with a `MCMCglmm` model with each clade as a random term.
+ * Additional plot arguments `...` in all the `dispRity` plotting functions can now be targeted to a specific plotting element. When multiple elements are plot by default (e.g. lines, legend, points, etc...) it is now possible to pass a specific `...` argument to the specific plotted element using the syntax `<element>.<argument>` (e.g. `points.col = "blue"` will only apply the argument `col = "blue"` to the points).
+
 ### MINOR IMPROVEMENTS
 
+ * **Changed default arguments** for `projections` and `projections.tree` metrics: the default `"position"` output is now scaled, centred and absolute (see `?projections` for details).
  * Formalised the grouping logic for `custom.subsets` and `select.axes`. This can create some minor user level changes namely: warning messages for empty subsets now correctly mentions "subsets" (rather than subsamples); groups with incorrect elements are now always flagged as errors (rather than just ignored). The changes at the developer level is that the logic is now made smoother and exported in `custom.subsets_fun.R`.
  * Added a `function.index.csv` list (and updater) to help developers find internal functions locations easily.
  * Restricted the type-I error inflation warning message in `test.dispRity` to only occur when using a test of class `"htest"`.
  * Continuous Integration has been moved from Travis-CI to GitHub Actions.
+ * `custom.subsets` can now group elements using a `"factor"` vector.
+ * Utility functions manuals are now grouped by topic (e.g. utilities related to `MCMCglmm` objects, `dispRity` objects in general, `dispRity` objects with subsets, ect...). It should now be much easier to find these sometimes overlooked functions.
+ * Many updates and new entries in the `dispRity` manual, including a section on `covar` and `between.groups` specific analyses.
+ * Improving speed for the `test.metric` (using the new official `dispRity.fast` function).
+ * Most core functions in the package now have a garbage memory cleaning component. This improves the speed and the memory footprint when handling very large datasets.
+ * Disparity results stored in `data$disparity` now don't have dimension names anymore (significantly reducing the size of `disparity` objects). However, you can always retrieve the dimensions names using `get.disparity`.
+ * Updated the calculation options for `ellipse.volume`, you can now directly specify one of the following methods: `"pca"` to calculate the eigen values from the ordinated matrix; `"eigen"` to directly do an eigen decomposition of the matrix (new); or `"axes"` to directly measure the axes (new); or directly provide the eigen values.
+ * The interval function `check.subsets` now handles the checking of `"dispRity"` objects much faster making most functions relying on it slightly faster (this function is typically not called more than once per function).
+ * Updated `adonis.dispRity` to the newest `vegan::adonis2` code (thanks to Jari Oksanen for the notification).
+ * Removed dependency to `geiger` for `dtt.dispRity` to avoid package maintenance errors. This leads to no changes at the user level and `geiger::dtt` is still acknowledged in the manual.
+ * `tree.age` function's manual now makes it clear it does not estimate tree ages.
+ * When using `plot.dispRity(..., type = "preview")`, group's colour attribution and plotting is now made so that the groups larger groups are plotted in the background and the smaller in the foreground.
+ * `NA`s are now better handled in internal checking functions. 
 
 ### BUG FIXES
 
  * Removed warning in `dispRity` when selecting a specific number of dimensions (old warning artefact).
  * Fixed bug in `plot.dispRity` when using `type = "preview"` on bootstrapped data and for `type = "box"` when the subsets to plot are from different sizes (now plots all the data correctly).
- * Fixed bug when using `chrono.subsets` with `"continuous"` method a `FADLAD` data containing only node values (now correctly taken into account; thanks to [Peng-Wei Li](https://www.researchgate.net/profile/Peng-Wei-Li) for noticing it) and when using `chrono.subsets` with `"gradual.*"` models on empty subsets.
+ * Fixed bug when using `chrono.subsets` with `"continuous"` method a `FADLAD` data containing only node values (now correctly taken into account; thanks to Peng-Wei Li for noticing it) and when using `chrono.subsets` with `"gradual.*"` models on empty subsets.
  * `standardGeneric` functions are now correctly interpreted as functions throughout the package.
  * Fixed bug when plotting level 1 disparity metric results without bootstrapped (`observed = TRUE` is now used as the default).
  * Fixed bug when plotting `test.metric` plots with `save.steps` options with more than two types of shifts.
  * Fixed bug with `null.test` which is now correctly managing the number of dimensions inherited from `dispRity` objects (thanks to [Alex Slavenko](https://alexslavenko.weebly.com/) for spotting this one and the two above).
- * Fixed bug when using level 2 dimension metrics on unidimensional data (the metric is now detected as a level 2 correctly; thanks to [Catherine Klein](https://www.researchgate.net/profile/Catherine-Klein) and [Rachel Warnock](https://www.gzn.nat.fau.de/palaeontologie/team/professors/rachel-warnock/) for noticing that one).
+ * Fixed bug when using level 2 dimension metrics on unidimensional data (the metric is now detected as a level 2 correctly; thanks to Catherine Klein and [Rachel Warnock](https://www.gzn.nat.fau.de/palaeontologie/team/professors/rachel-warnock/) for noticing that one).
  * Update internal use of `is(data, c("array", "matrix"))` to `is.array(data)` for R 4.1.2.
-
+
+### DEPRECATED AND DEFUNCT
+
+ * `matrix.dispRity` and `extract.dispRity` are now deprecated. You should now use respectively `get.matrix` and `get.disparity` instead (the arguments don't change though).
+
 dispRity v1.6.0 (2021-04-16) *dispRitree*
 =========================
 
@@ -61,7 +92,7 @@ dispRity v1.6.0 (2021-04-16) *dispRitree*
  * You can now save the shifts results in `test.metric` with `save.steps` and then visualise them with `plot.dispRity` along side the disparity metric test results.
  * *New* utility function `n.subsets` to directly get the number of subsets in a `dispRity` object.
  * *New* statistical test: `randtest.dispRity` that is a wrapper for `ade4::randtest` applied to `dispRity` objects (not dissimilar from `null.test`).
- * Six more demo datasets have been added to the package! These datasets are the ones used in [Guillerme et al. 2020](https://onlinelibrary.wiley.com/doi/full/10.1002/ece3.6452) and published originally in [Beck & Lee 2014](https://royalsocietypublishing.org/doi/full/10.1098/rspb.2014.1278) (that one was originally the only demo dataset in the package), [Wright 2017](https://www.cambridge.org/core/journals/journal-of-paleontology/article/bayesian-estimation-of-fossil-phylogenies-and-the-evolution-of-early-to-middle-paleozoic-crinoids-echinodermata/E37972902541CD0995AAD08A1122BD54), [Marcy et al. 2016](https://link.springer.com/article/10.1186/s12862-016-0782-1), [Hopkins & Pearson 2016](https://www.researchgate.net/profile/Melanie-Hopkins/publication/320543447_Non-linear_ontogenetic_shape_change_in_Cryptolithus_tesselatus_Trilobita_using_three-dimensional_geometric_morphometrics/links/59f7307d0f7e9b553ebd5e03/Non-linear-ontogenetic-shape-change-in-Cryptolithus-tesselatus-Trilobita-using-three-dimensional-geometric-morphometrics.pdf)), [Jones et al. 2015](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/1365-2745.12405), [Healy et al. 2019](https://www.nature.com/articles/s41559-019-0938-7). Thanks to all these authors for their open science work!
+ * Six more demo datasets have been added to the package! These datasets are the ones used in [Guillerme et al. 2020](https://scholar.google.co.uk/scholar?hl=en&as_sdt=0%2C5&q=Shifting+spaces%3A+Which+disparity+or+dissimilarity+measurement+best+summarize+occupancy+in+multidimensional+spaces%3F&btnG=) and published originally in [Beck & Lee 2014](https://royalsocietypublishing.org/doi/full/10.1098/rspb.2014.1278) (that one was originally the only demo dataset in the package), [Wright 2017](https://www.cambridge.org/core/journals/journal-of-paleontology/article/bayesian-estimation-of-fossil-phylogenies-and-the-evolution-of-early-to-middle-paleozoic-crinoids-echinodermata/E37972902541CD0995AAD08A1122BD54), [Marcy et al. 2016](https://link.springer.com/article/10.1186/s12862-016-0782-1), [Hopkins & Pearson 2016](https://pdfs.semanticscholar.org/a3f0/50944d2aefa1df811ea94a3eea630d82c24f.pdf)), [Jones et al. 2015](https://scholar.google.co.uk/scholar?hl=en&as_sdt=0%2C5&q=Dispersal+mode+mediates+the+effect+of+patch+size+and+patch+connectivity+on+metacommunity+diversity&btnG=), [Healy et al. 2019](https://www.nature.com/articles/s41559-019-0938-7). Thanks to all these authors for their open science work!
  * `dispRity` objects now have a reserved `$tree` component that contain any number of trees attached to the data. This allows any function to use the reserved argument name `tree` to extract directly the relevant tree from the `dispRity` object, for functions like `chrono.subsets` or metrics like `ancestral.dist`! To help manipulate the `tree` component of the `dispRity` object, you can now use the new utility functions `add.tree`, `get.tree` and `remove.tree`.
 
 ### MINOR IMPROVEMENT
@@ -71,7 +102,7 @@ dispRity v1.6.0 (2021-04-16) *dispRitree*
   * remove the `"only"` text when printing `dispRity` objects that contains "only" matrices (even though that can be 10k matrices!).
   * added a dedicated behaviour to `summary.dispRity` for `"dispRity"` `"randtest"` objects to output "ready-to-publish" result tables.
   * some error messages have been updated to be slightly more useful.
-  * added the `estimation.details` argument to `multi.ace` allowing to also return specific arguments from the ancestral states estimation (thanks to [Armin Elsler](https://www.researchgate.net/profile/Armin-Elsler-2) for the suggestion).
+  * added the `estimation.details` argument to `multi.ace` allowing to also return specific arguments from the ancestral states estimation (thanks to Armin Elsler for the suggestion).
   * Added new option `inc.nodes` to `clean.data` whether to check if the nodes in the tree match the labels in the matrix.
   * `make.metric` with the option `silent = TRUE` now outputs a list of info rather than only the level of the metric. You can reproduce the old behaviour using `make.metric(..., silent = TRUE)$type)`.
   * Fixed bug in `plot` using `preview` when the given argument `pch` did not match the number of groups (the different `pch` arguments are now used correctly).