physignal: Assessing phylogenetic signal in Procrustes shape variables

View source: R/physignal.r

physignalR Documentation

Assessing phylogenetic signal in Procrustes shape variables

Description

Function calculates the degree of phylogenetic signal from Procrustes shape variables

Usage

physignal(A, phy, iter = 999, seed = NULL, print.progress = FALSE)

Arguments

A

A matrix (n x [p x k]) or 3D array (p x k x n) containing Procrustes shape variables for a set of specimens

phy

A phylogenetic tree of class = "phylo" - see read.tree in library ape

iter

Number of iterations for significance testing

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.

print.progress

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

Details

The function estimates the degree of phylogenetic signal present in Procrustes shape variables for a given phylogeny. It is assumed that the landmarks have previously been aligned using Generalized Procrustes Analysis (GPA) [e.g., with gpagen]. The degree of phylogenetic signal in data is estimated using the multivariate version of the K-statistic (Kmult: Adams 2014). This value evaluates the degree of phylogenetic signal in a dataset relative to what is expected under a Brownian motion model of evolution. For geometric morphometric data, the approach is a mathematical generalization of the Kappa statistic (Blomberg et al. 2003) appropriate for highly multivariate data (see Adams 2014). Significance testing is found by permuting the shape data among the tips of the phylogeny. And effect size can be estimated based on likelihood method that finds and optimal scaling of the tree; see physignal.z.

This function can also be used with univariate data (i.e. centroid size) if imported as matrix with rownames giving the taxa names. In this case, the estimate of phylogenetic signal is identical to that found using the standard kappa statistic (Blomberg et al. 2003).

The generic functions, print, summary, and plot all work with physignal. The generic function, plot, produces a histogram of random K statistics, associated with the resampling procedure.

Notes for geomorph 4.0

Starting with version 4.0.2, this function no longer reports an effect size. Effect sizes for phylogenetic signal can be calculated with physignal.z, based on likelihood.

Notes for geomorph 3.0

Compared to older versions of geomorph, the order of input variables has changed, so that it is consistent with other functions in the program. Additionally, users should note that the function physignal no longer contains multiple methods. Only Kmult is used. Thus, for older scripts method="" should be removed from the function call.

Value

Function returns a list with the following components:

phy.signal

The estimate of phylogenetic signal.

pvalue

The significance level of the observed signal.

random.K

Each random K-statistic from random permutations.

permutations

The number of random permutations used in the resampling procedure.

PACA

A phylogenetically aligned component analysis, based on OLS residuals.

K.by.p

The phylogenetic signal in 1, 1:2, 1:3, ..., 1:p dimensions, for the p components from PACA.

call

The matched call

Author(s)

Dean Adams and Michael Collyer

References

Blomberg SP, Garland T, Ives AR. 2003. Testing for phylogenetic signal in comparative data: behavioral traits are more labile. Evolution, 57:717-745.

Adams, D.C. 2014. A generalized K statistic for estimating phylogenetic signal from shape and other high-dimensional multivariate data. Systematic Biology. 63:685-697.

Adams, D.C. and M.L. Collyer. 2019. Comparing the strength of modular signal, and evaluating alternative modular hypotheses, using covariance ratio effect sizes with morphometric data. Evolution. 73:2352-2367.

See Also

gm.prcomp, physignal.z

Examples

## Not run: 
data(plethspecies) 
Y.gpa <- gpagen(plethspecies$land)    #GPA-alignment    

#Test for phylogenetic signal in shape
PS.shape <- physignal(A = Y.gpa$coords, phy = plethspecies$phy)
summary(PS.shape)
plot(PS.shape)
plot(PS.shape$PACA, phylo = TRUE)
PS.shape$K.by.p # Phylogenetic signal profile

#Test for phylogenetic signal in size
PS.size <- physignal(A = Y.gpa$Csize, phy = plethspecies$phy)
summary(PS.size)
plot(PS.size)

## End(Not run)

geomorph documentation built on June 24, 2024, 5:07 p.m.