geomorph (version 4.0.3)

morphol.disparity: Morphological disparity for one or more groups of specimens

Description

Function estimates morphological disparity and performs pairwise comparisons among groups

Usage

morphol.disparity(
  f1,
  groups = NULL,
  partial = FALSE,
  transform = FALSE,
  iter = 999,
  seed = NULL,
  data = NULL,
  print.progress = TRUE,
  ...
)

Arguments

f1

A formula describing the linear model used. The left-hand portion of the formula should be a 3D array (p x k x n) containing Procrustes shape variables for a set of specimens, or a matrix (n x variables). The right-hand portion of the formula should be " ~1" to use the overall mean, or "~ x1 + x2 + x3 +...", where each x is a covariate or factor. (Interactions and nested terms also work.) Alternatively, one can use an object of class "procD.lm" or "lm.rrpp", which already has a formula defined. This is especially helpful for analyses performed with procD.pgls, as residuals from PGLS will be used for analysis (see examples).

groups

Either a formula designating groups, e.g., groups = ~ groups, or a factor, or a vector coercible to factor. If NULL and if f1 is a procD.lm or lm.rrpp model fit, morphol.disparity will attempt to define groups based on the terms of the model. If there are no groups inherently indicated in f1 and groups is NULL, a single Procrustes variance will be returned for the entire data set.

partial

A logical value to indicate whether partial disparities should be calculated, sensu Foote (1993). If TRUE, the model formula should have only an intercept (e.g., coords ~ 1); otherwise an error will be returned.

transform

A logical value to indicate whether disparity should be measured in the transformed space rather than the tangent space. This is only applicable if a PGLS model is used, in which case the transformation would be necessary for a variance that is independent of phylogeny. If transform = FALSE, disparity tracks the dispersion one would observe in a phylo-PC plot. If transform = TRUE, disparity tracks the dispersion in a PC plot of the transformed space (lacking phylogenetic signal). See Collyer and Adams 2021, and examples below.

iter

Number of iterations for permutation test

seed

An optional argument for setting the seed for random permutations of the resampling procedure. If left NULL (the default), the exact same P-values will be found for repeated runs of the analysis (with the same number of iterations). If seed = "random", a random seed will be used, and P-values will vary. One can also specify an integer for specific seed values, which might be of interest for advanced users.

data

A data frame for the function environment, see geomorph.data.frame

print.progress

A logical value to indicate whether a progress bar should be printed to the screen. This is helpful for long-running analyses.

...

Arguments passed on to procD.lm (typically associated with the lm function, such as weights or offset, plus SS.type).

Value

Objects of class "morphol.disparity" return a list with the following components (if groups are specified):

Procrustes.var

Observed Procrustes variances.

PV.dist

Observed pairwise absolute differences (as distances) among group Procrustes variances.

PV.dist.Pval

P-values associated with pairwise differences.

random.PV.dist

Pairwise distance matrices produced in the resampling procedure.

permutations

Number of random permutations in resampling procedure.

partial

Logical value to indicate if partial disparities were calculated.

call

The match call

Details

The function estimates morphological disparity and performs pairwise comparisons to identify differences among groups. Morphological disparity is estimated as the Procrustes variance, overall or for groups, using residuals of a linear model fit. Procrustes variance is the same sum of the diagonal elements of the group covariance matrix divided by the number of observations in the group (e.g., Zelditch et al. 2012). The function takes as input a formula to describe the linear model fit, plus a formulaic indication of groups (e.g., ~ groups). It is assumed that the formula describes shape data that have been GPA-aligned [e.g., gpagen], although the function can work with any multivariate data.

Partial disparities (Foote 1993) can also be calculated, but only for model formulas containing only an intercept (e.g., coords ~ 1). Partial disparity has the same numerator as Procrustes variance (with respect to an overall mean) but the denominator is N - 1 for all N observations, rather than n, the group size. (The sum of all group n equals N.) Partial disparities have the appeal that the sum of group partial disparities it the total disparity.

Absolute differences in Procrustes variances are test statistics that can be used to test differences in morphological disparity among groups. These differences are statistically evaluated through permutation, where the vectors of residuals are randomized among groups. The function can be used to obtain disparity for the whole dataset by using "a dummy group factor "~ 1" as the right-hand portion of the formula, in which case only Procrustes variance is returned. Additionally, if the right-hand portion of the formula only contains (continuous) covariates, e.g., "~ Csize", Procrustes variance will be calculated for the whole data set or groups, after accounting for the linear regression described. Finally, different factors can be indicated in the formula and for groups, if one wishes to compare morphological disparities for groups comprising only a portion of or collapsing of the groups in a more complex model (see examples).

This function can be used with an object of class "procD.lm" or "lm.rrpp", if such analyses have already been performed. This is especially useful for analyses performed with procD.pgls. In this case, residuals obtained from PGLS estimation of coefficients, rather than OLS estimation, will be used in the analysis. Thus, one can account for phylogeny when comparing morphological disparity among groups. However, one should be aware that PGLS finds the PGLS residuals and transforms them via the phylogenetic covariance matrix in order to calculate variance. Thus, disparity (dispersion in tangent space) and variance (dispersion in transformed space, after accounting for phylogeny) can be considered different things. This function uses an argument, transform, to allow users to use either GLS residuals in tangent space or transformed residuals in the transformed space to calculate disparity. The former characterizes the dispersion of actual shapes around GLS means; the latter estimates GLS variances, by group.

Notes for geomorph 3.1.0 and subsequent versions

The function pairwise in the RRPP package can also be used to evaluate morphological disparity, and will yield results identical to those of the current function. A simple example is shown below

References

Zelditch, M. L., D. L. Swiderski, H. D. Sheets, and W. L. Fink. 2012. Geometric morphometrics for biologists: a primer. 2nd edition. Elsevier/Academic Press, Amsterdam.

Foote, M. 1993. Contributions of individual taxa to overall morphological disparity. Paleobiology, 19: 403-419.

Collyer, M.L and D.C. Adams, 2021. Phylogenetically Aligned component analysis. Methods in Ecology and Evolution, 12: 369-372.

Examples

# NOT RUN {
data(plethodon)
Y.gpa<-gpagen(plethodon$land, print.progress = FALSE)    #GPA-alignment
gdf <- geomorph.data.frame(Y.gpa, species = plethodon$species, 
site = plethodon$site)

# Morphological disparity for entire data set
morphol.disparity(coords ~ 1, groups = NULL, data = gdf, 
iter = 999, print.progress = FALSE)

# Morphological disparity for entire data set, accounting for allometry
morphol.disparity(coords ~ Csize, groups= NULL, data = gdf, 
iter = 999, print.progress = FALSE)

# Morphological disparity without covariates, using overall mean
morphol.disparity(coords ~ 1, groups= ~ species*site, data = gdf, 
iter = 999, print.progress = FALSE)

# Morphological partial disparities for overal mean
morphol.disparity(coords ~ 1, groups= ~ species*site, partial = TRUE, 
data = gdf, iter = 999, print.progress = FALSE)

# Morphological disparity without covariates, using group means
morphol.disparity(coords ~ species*site, groups= ~species*site, 
data = gdf, iter = 999, print.progress = FALSE)

# Morphological disparity of different groups than those 
# described by the linear model
morphol.disparity(coords ~ Csize + species*site, groups= ~ species, 
data = gdf, iter = 999, print.progress = FALSE)

# Extracting components
MD <- morphol.disparity(coords ~ Csize + species*site, groups= ~ species, 
data = gdf, iter = 999, print.progress = FALSE)
MD$Procrustes.var # just the Procrustes variances


### Morphol.disparity can be used with previously-defined 
### procD.lm or lm.rrpp class objects

data(plethspecies)
Y.gpa<-gpagen(plethspecies$land)    #GPA-alignment
gp.end<-factor(c(0,0,1,0,0,1,1,0,0))  #endangered species vs. rest
names(gp.end)<-plethspecies$phy$tip

gdf <- geomorph.data.frame(Y.gpa, phy = plethspecies$phy, 
gp.end = gp.end)

pleth.ols <- procD.lm(coords ~ Csize + gp.end, 
data = gdf, iter = 999) # ordinary least squares
pleth.pgls <- procD.pgls(coords ~ Csize + gp.end, phy = phy, 
data = gdf, iter = 999) # phylogenetic generalized least squares

summary(pleth.ols)
summary(pleth.pgls)

morphol.disparity(f1 = pleth.ols, groups = ~ gp.end, data = gdf, 
iter = 999, print.progress = FALSE)
morphol.disparity(f1 = pleth.pgls, groups = ~ gp.end, 
transform = FALSE, data = gdf, 
iter = 999, print.progress = FALSE) # disparity in tangent space
morphol.disparity(f1 = pleth.pgls, groups = ~ gp.end,
transform = TRUE, data = gdf, 
iter = 999, print.progress = FALSE) # disparity in transformed space 

# Three plots that correspond to the three tests
PCA <- gm.prcomp(Y.gpa$coords, phy = plethspecies$phy)
pPCA <- gm.prcomp(Y.gpa$coords, phy = plethspecies$phy, 
GLS = TRUE, transform = FALSE)
tpPCA <- gm.prcomp(Y.gpa$coords, phy = plethspecies$phy, 
GLS = TRUE, transform = TRUE)

par(mfrow = c(1,3))

# Phylomorphospace
PC.plot <- plot(PCA, pch = 19, phylo = TRUE, main = "PCA-OLS")
shapeHulls(PC.plot, groups = gp.end)

# Phylo-PCA
pPC.plot <- plot(pPCA, pch = 19, phylo = TRUE, main = "pPCA - GLS, not transformed")
shapeHulls(pPC.plot, groups = gp.end)

# Transformed phylo-PCA
tpPC.plot <- plot(tpPCA, pch = 19, phylo = TRUE, main = "tpPCA - GLS, transformed")
shapeHulls(tpPC.plot, groups = gp.end)

par(mfrow = c(1,1))

 ### Variance using RRPP (not necessarily the same as disparity)
 PW <- pairwise(pleth.ols, groups = gp.end)
 summary(PW, test.type = 'var')
 PW2 <- pairwise(pleth.pgls, groups = gp.end)
 summary(PW2, test.type = 'var')

# }