two.b.pls: Two-block partial least squares analysis for Procrustes shape...

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

Two-block partial least squares analysis for Procrustes shape variables

Description

Function performs two-block partial least squares analysis to assess the degree of association between to blocks of Procrustes shape variables (or other variables)

Usage

two.b.pls(A1, A2, iter = 999, seed = NULL, print.progress = TRUE)

Arguments

A1	A 3D array (p x k x n) containing Procrustes shape variables for the first block, or a matrix (n x variables)
A2	A 3D array (p x k x n) containing Procrustes shape variables for the second block, or a matrix (n x variables)
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 association between two blocks of shape data as defined by Procrustes shape variables using partial least squares (see Rohlf and Corti 2000). If geometric morphometric data are used, it is assumed that the landmarks have previously been aligned using Generalized Procrustes Analysis (GPA) [e.g., with gpagen]. If other variables are used, they must be input as a 2-Dimensional matrix (rows = specimens, columns = variables). It is also assumed that the separate inputs have specimens (observations) in the same order. Additionally, if names for the objects are specified, these must be the same for both datasets. 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. 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 2016; Adams and Collyer 2019).

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).

For more than two blocks

If one wishes to consider 3+ arrays or matrices, there are multiple options. First, one could perform multiple two.b.pls analyses and use compare.pls to ascertain which blocks are more "integrated". Second, one could use integration.test and perform a test that averages the amount of integration (correlations) across multiple pairwise blocks. Note that performing integration.test performed on two matrices or arrays returns the same results as two.b.pls. Thus, integration.test is more flexible and thorough.

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

There is a slight change in two.b.pls plots with geomorph 3.0. Rather than use the shapes of specimens that matched minimum and maximum PLS scores, major-axis regression is used and the extreme fitted values are used to generate deformation grids. This ensures that shape deformations are exactly along the major axis of shape covariation. This axis is also shown as a best-fit line in the plot.

Value

Object of class "pls" that returns a list of the following:

r.pls	The correlation coefficient between scores of projected values on the first singular vectors of left (x) and right (y) blocks of landmarks (or other variables). This value can only be negative if single variables are input, as it reduces to the Pearson correlation coefficient.
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
right.pls.vectors	The singular vectors of the right (y) block
random.r	The correlation coefficients found in each random permutation of the resampling procedure.
XScores	Values of left (x) block projected onto singular vectors.
YScores	Values of right (y) block projected onto singular vectors.
svd	The singular value decomposition of the cross-covariances. See svd for further details.
A1	Input values for the left block.
A2	Input values for the right block.
A1.matrix	Left block (matrix) found from A1.
A2.matrix	Right block (matrix) found from A2.
permutations	The number of random permutations used in the resampling procedure.
call	The match call.

Author(s)

Dean Adams and Michael Collyer

References

Rohlf, F.J., and M. Corti. 2000. The use of partial least-squares to study covariation in shape. Systematic Biology 49: 740-753.

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

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

Examples

data(plethShapeFood) 
Y.gpa<-gpagen(plethShapeFood$land)    #GPA-alignment    

#2B-PLS between head shape and food use data
PLS <-two.b.pls(Y.gpa$coords,plethShapeFood$food,iter=999)
summary(PLS)
P <- plot(PLS)
 
 # Visualize shape at minimum and maximum PLS scores.
 # This is the challenging way
 
 # Block 1 (shape)
 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)
 
 ### 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)
 

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