integration.test: Quantify morphological integration between modules

In geomorph: Geometric Morphometric Analyses of 2D and 3D Landmark Data

Quantify morphological integration between modules

Description

Function quantifies the degree of morphological integration between modules of Procrustes shape variables

Usage

integration.test(
  A,
  A2 = NULL,
  partition.gp = NULL,
  iter = 999,
  seed = NULL,
  print.progress = TRUE
)

Arguments

A	A 3D array (p x k x n) containing Procrustes shape variables for all specimens, or a matrix (n x variables)
A2	An optional 3D array (p x k x n) containing Procrustes shape variables for all specimens, or a matrix (n x variables) for a second partition
partition.gp	A list of which landmarks (or variables) belong in which partition: (e.g. A, A, A, B, B, B, C, C, C). Required when only 1 dataset provided.
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 quantifies the degree of morphological integration between modular partitions of shape data as defined by Procrustes shape variables. It is assumed that the landmarks have previously been aligned using Generalized Procrustes Analysis (GPA) [e.g., with gpagen]. The function may be used to assess the degree of morphological integration between two or more sets of variables.

The function estimates the degree of morphological integration using a two-block partial least squares analysis (PLS). When used with landmark data, this analysis is referred to as singular warps analysis (Bookstein et al. 2003). If more than two partitions are defined, the average pairwise PLS correlation is utilized as the test statistic. The observed test value is then compared to a distribution of values obtained by randomly permuting the individuals (rows) in one partition relative to those in the other. A significant result is found when the observed PLS correlation is large relative to this distribution, and implies that the structures are integrated with one another (see Bookstein et al. 2003). In addition, a multivariate effect size describing the strength of the effect is estimated from the empirically-generated sampling distribution (see details in Adams and Collyer 2019). If only two partitions are specified, a plot of PLS scores along the first set of PLS axes is optionally displayed, and thin-plate spline deformation grids along these axes are also shown if data were input as a 3D array.

Input for the analysis can take one of two forms. First, one can input a single dataset (as a matrix or 3D array, along with a vector describing which variables correspond to which partitions (for the case of a 3D array, which landmarks belong to which partitions is specified). Alternatively, when evaluating the integration between two structures or partitions, two datasets may be provided.

The generic functions, print, summary, and plot all work with integration.test. The generic function, plot, produces a two-block.pls plot. This function calls plot.pls, which produces an ordination plot. An additional argument allows one to include a vector to label points. Starting with version 3.1.0, warpgrids are no longer available with plot.pls but after making a plot, the function returns values that can be used with picknplot.shape or a combination of shape.predictor and plotRefToTarget to visualize shape changes in the plot (via warpgrids).

Similarity to two.b.pls and compare.pls

Note that integration.test performed on two matrices or arrays returns the same results as two.b.pls. However, two.b.pls is limited to only two modules. It might be of interest with 3+ modules to perform integration tests between all pairwise comparisons of modules. This can be done, test by test, and the levels of integration can be compared with compare.pls. Such results are different than using the average amount of integration, as performed by integration.test when more than two modules are input.

Using phylogenies and PGLS

If one wishes to incorporate a phylogeny, phylo.integration is the function to use. This function is exactly the same as integration.test but allows PGLS estimation of PLS vectors. Because integration.test can be used on two blocks, phylo.integration likewise allows one to perform a phylogenetic two-block PLS analysis.

Notes for geomorph 3.0.4 and subsequent versions

Compared to previous versions of geomorph, users might notice differences in effect sizes. Previous versions used z-scores calculated with expected values of statistics from null hypotheses (sensu Collyer et al. 2015); however Adams and Collyer (2016) showed that expected values for some statistics can vary with sample size and variable number, and recommended finding the expected value, empirically, as the mean from the set of random outcomes. Geomorph 3.0.4 and subsequent versions now center z-scores on their empirically estimated expected values and where appropriate, log-transform values to assure statistics are normally distributed. This can result in negative effect sizes, when statistics are smaller than expected compared to the average random outcome. For ANOVA-based functions, the option to choose among different statistics to measure effect size is now a function argument.

Value

Objects of class "pls" from integration.test return a list of the following:

r.pls	The estimate of morphological integration: PLS.corr. The mean of pairwise PLS correlations between partitions is used when there are more than two partitions.
r.pls.mat	The pairwise r.pls, if the number of partitions is greater than 2.
P.value	The empirically calculated P-value from the resampling procedure.
Effect.Size	The multivariate effect size associated with sigma.d.ratio.
left.pls.vectors	The singular vectors of the left (x) block (for 2 modules only).
right.pls.vectors	The singular vectors of the right (y) block (for 2 modules only).
random.r	The correlation coefficients found in each random permutation of the resampling procedure.
XScores	Values of left (x) block projected onto singular vectors (for 2 modules only).
YScores	Values of right (y) block projected onto singular vectors (for 2 modules only).
svd	The singular value decomposition of the cross-covariances (for 2 modules only).
A1	Input values for the left block (for 2 modules only).
A2	Input values for the right block (for 2 modules only).
A1.matrix	Left block (matrix) found from A1 (for 2 modules only).
A2.matrix	Right block (matrix) found from A2 (for 2 modules only).
permutations	The number of random permutations used in the resampling procedure.
call	The match call.

Author(s)

Dean Adams

References

Bookstein, F. L., P. Gunz, P. Mitteroecker, H. Prossinger, K. Schaefer, and H. Seidler. 2003. Cranial integration in Homo: singular warps analysis of the midsagittal plane in ontogeny and evolution. J. Hum. Evol. 44:167-187.

Collyer, M.L., D.J. Sekora, and D.C. Adams. 2015. A method for analysis of phenotypic change for phenotypes described by high-dimensional data. Heredity. 115:357-365.

Adams, D.C. and M.L. Collyer. 2016. On the comparison of the strength of morphological integration across morphometric datasets. Evolution. 70:2623-2631.

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

two.b.pls, modularity.test, phylo.integration, and compare.pls

Examples

data(plethodon) 
Y.gpa<-gpagen(plethodon$land)    #GPA-alignment    
#landmarks on the skull and mandible assigned to partitions
land.gps<-c("A","A","A","A","A","B","B","B","B","B","B","B") 
IT <- integration.test(Y.gpa$coords, partition.gp=land.gps, iter=999)
summary(IT) # Test summary
P <- plot(IT) # PLS plot

 # Visualize shape at minimum and maximum PLS scores.
 # This is the challenging way
 
 # Block 1 
 minx <- min(P$plot.args$x)
 maxx <- max(P$plot.args$x)
 preds <- shape.predictor(P$A1, 
 x = P$plot.args$x,
 min = minx, max = maxx)
 plotRefToTarget(mshape(P$A1), preds$min)
 plotRefToTarget(mshape(P$A1), preds$max)

 # Block 2 
 miny <- min(P$plot.args$y)
 maxy <- max(P$plot.args$y)
 preds <- shape.predictor(P$A2, 
 x = P$plot.args$y,
 min = miny, max = maxy)
 plotRefToTarget(mshape(P$A2), preds$min)
 plotRefToTarget(mshape(P$A2), preds$max)
 
 ### Visualize shape variation using picknplot.shape Because picknplot  
 ### requires user decisions, the following example
 ### is not run (but can be with removal of #).
 ### For detailed options, see the picknplot help file
 # picknplot.shape(P)

IT$left.pls.vectors # extracting just the left (first block) 
# singular vectors

geomorph documentation built on Sept. 1, 2023, 1:07 a.m.