procD.allometry: Procrustes ANOVA/regression, specifically for shape-size...

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/procD.allometry.r

Description

Function performs Procrustes ANOVA with permutation procedures to facilitate visualization of size-shape patterns (allometry); i.e., patterns of shape covariation with size for a set of Procrustes-aligned coordinates. Results for plotting allometric patterns based on several approaches in the literature are available.

Usage

1
2
3
procD.allometry(f1, f2 = NULL, logsz = TRUE, iter = 999, seed = NULL,
  alpha = 0.05, RRPP = TRUE, effect.type = c("F", "SS", "cohen"),
  print.progress = TRUE, data = NULL, ...)

Arguments

f1

A formula for the relationship of shape and size; e.g., Y ~ X.

f2

An optional right-hand formula for the inclusion of groups; e.g., ~ groups.

logsz

A logical argument to indicate if the variable for size should be log-transformed.

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.

alpha

The significance level for the homogeneity of slopes test

RRPP

A logical value indicating whether residual randomization should be used for significance testing

effect.type

One of "F", "SS", or "cohen", to choose from which random distribution to estimate effect size. (The default is "F").

print.progress

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

data

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

...

Arguments passed on to procD.fit (typically associated with the lm function, such as weights or offset). The function procD.fit can also currently handle either type I, type II, or type III sums of squares and cross-products (SSCP) calculations. Choice of SSCP type can be made with the argument, SS.type; i.e., SS.type = "I" or SS.type = "III". Only advanced users should consider using these additional arguments, as such arguments are experimental in nature.

Details

The function quantifies the relative amount of shape variation attributable to covariation with organism size (allometry) plus (potentially) another grouping factor in a linear model, so as to provide initial visualizations of patterns of shape allometry. Data input is specified by formulae (e.g., Y ~ X), where 'Y' specifies the response variables (shape data), and 'X' contains A SINGLE independent continuous variable representing size. The response matrix 'Y' can be either in the form of a two-dimensional data matrix of dimension (n x [p x k]), or a 3D array (p x n x k). It is assumed that -if the data are based on landmark coordinates - the landmarks have previously been aligned using Generalized Procrustes Analysis (GPA) [e.g., with gpagen]. Additionally, one has the option of providing a second formula where groups are specified in the form of ~ group. If groups are provided a "homogeneity of slopes" test will be performed.

It is assumed that the order of the specimens in the shape matrix matches the order of values in the independent variables. Linear model fits (using the lm function) can also be input in place of formulae. Arguments for lm can also be passed on via this function. For further information about ANOVA in geomorph, resampling procedures used, and output, see procD.lm or advanced.procD.lm. If greater flexibility is required for variable order, advanced.procD.lm should be used.

It is strongly recommended that geomorph.data.frame is used to create and input a data frame. This will reduce problems caused by conflicts between the global and function environments. In the absence of a specified data frame, procD.allometry will attempt to coerce input data into a data frame, but success is not guaranteed.

The generic functions, print, summary, and plot all work with procD.allometry. The generic function, plot, produces plots of allometric curves, using one of three methods input (see below). If diagnostic plots on model residuals are desired, procD.lm should be used with the resulting model formula. This, along with the data frame resulting from analysis with procD.allometry can be used directly in procD.lm, which might be useful for extracting ANOVA components (as procD.allometry is far more basic than procD.lm, in terms of output).

A note on allometric models

This function is intended to be used for the graphical visualization of simple allometric patterns. The method is appropriate for models such as shape~log(size) and shape~log(size) + groups. Three plotting options, the common allometric coefficient (CAC), regression scores (RegScore), and predicted lines (PredLine) are implemented as originally described in the literature. NOTE however that for more complex models with additional parameters, one may instead wish to use the plotting capabilities that accompany procD.lm (see below for more details).

Notes for experienced or advanced users

Experienced or advanced users will probably prefer using procD.lm with a combination of plot.procD.lm, shape.predictor, and plotRefToTarget for publication-quality analyses and graphics. As stated above, use of procD.allometry is for visualizing simple allometric models that do not contain additional covariates. Thus, procD.allometry may be thought of as a wrapper function for procD.lm, but only for a restricted set of models and using a philosophy for model selection based on the outcome of a homogeneity of slopes test. This is not necessary if one wishes to define a model, irrespective of this outcome, or if more complex models are of interest. In these circumstances procD.lm offers much greater flexibility, and provides more statistically general approaches to visualizing patterns. Thus, procD.allometry might be thought of as an exploratory tool, if one is unsure how to model allometry for multiple groups. One should not necessarily accept the procD.allometry result as "truth" and other models can be explored with procD.lm. Examples for more flexible approaches to modeling allometry using procD.lm are provided below.

Notes for geomorph 3.0.5 and subsequent versions

Previous versions of procD.allometry had an argument, f3, for providing additional covariates. Complex models can now be analyzed with procD.lm, which has similar plotting capabilities as procD.allometry. Examples are provided below. This argument is no longer used, and procD.allometry is restricted to simpler models, deferring instead to procD.lm for complex models.

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.

Notes for geomorph 3.0 and making allometry plots

Former versions of geomorph had a "plotAllometry" function that performed ANOVA and produced plots of allometry curves. In geomorph 3.0, the plot function is used with procD.allometry objects to produce such plots. The following arguments can be used in plot to achieve desired results.

Use ?plot.procD.allometry to understand the arguments used. The following are brief descriptions of the different plotting methods using plot, with references.

Value

An object of class "procD.allometry" is a list containing the following:

HOS.test

ANOVA for a homogeneity of slopes test (if groups are provided).

aov.table

An analysis of variance table, based on inputs and the homogeneity of slopes test.

alpha

The significance level criterion for the homogeneity of slopes test.

perm.method

A value indicating whether "RRPP" or randomization of "raw" vales was used.

permutations

The number of random permutations used in the resampling procedure.

data

The data frame for the model.

random.SS

A matrix or vector of random SS found via the resampling procedure used.

random.F

A matrix or vector of random F values found via the resampling procedure used.

random.cohenf

A matrix or vector of random Cohen's f-squared values found via the resampling procedure used.

call

The matched call.

formula

The resulting formula, which can be used in follow-up analyses. Irrespective of input, shape = Y in the formula, and the variable used for size is called "size".

CAC

The common allometric component of the shape data, which is an estimate of the average allometric trend within groups (Mitteroecker et al. 2004). The function also calculates the residual shape component (RSC) for the data.

RSC

The residual shape component (associated with CAC approach)

Reg.proj

The projected regression scores on the regression of shape on size. For a single group, these shape scores are mathematically identical to the CAC (Adams et al. 2013).

pred.val

Principal component scores (first PC) of predicted values.

ref

the reference configuration (if input coordinates are in a 3D array).

gps

A vector of group names.

size

A vector of size scores.

logsz

A logical value to indicate if size values were log=transformed for analysis.

A

Procrustes (aligned) residuals.

Ahat

Predicted Procrustes residuals(matching array or matrix, as input).

Ahat.at.min

Predicted Procrustes residuals, specifically at minimum size.

Ahat.at.max

Predicted Procrustes residuals, specifically at maximum size.

p

landmark number

k

landmark dimensions

Author(s)

Michael Collyer

References

Adams, D.C., F.J. Rohlf, and D.E. Slice. 2013. A field comes of age: geometric morphometrics in the 21st century. Hystrix. 24:7-14.

Adams, D. C., and A. Nistri. 2010. Ontogenetic convergence and evolution of foot morphology in European cave salamanders (Family: Plethodontidae). BMC Evol. Biol. 10:1-10.

Drake, A. G., and C. P. Klingenberg. 2008. The pace of morphological change: Historical transformation of skull shape in St Bernard dogs. Proc. R. Soc. B. 275:71-76.

Mitteroecker, P., P. Gunz, M. Bernhard, K. Schaefer, and F. L. Bookstein. 2004. Comparison of cranial ontogenetic trajectories among great apes and humans. J. Hum. Evol. 46:679-698.

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.

See Also

procD.lm and advanced.procD.lm within geomorph; lm for more on linear model fits

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
# Simple allometry
data(plethodon) 
Y.gpa <- gpagen(plethodon$land, print.progress = FALSE)    #GPA-alignment  

gdf <- geomorph.data.frame(Y.gpa, site = plethodon$site, 
species = plethodon$species) 
plethAllometry <- procD.allometry(coords~Csize, f2 = NULL, f3=NULL, 
logsz = TRUE, data=gdf, iter=149)
summary(plethAllometry)
plot(plethAllometry, method = "PredLine")
plot(plethAllometry, method = "RegScore")

## Obtaining size-adjusted residuals (and allometry-free shapes)
plethAnova <- procD.lm(plethAllometry$formula,
     data = plethAllometry$data, iter = 99, RRPP=TRUE) 
summary(plethAnova) # same ANOVA Table
shape.resid <- arrayspecs(plethAnova$residuals,
   p=dim(Y.gpa$coords)[1], k=dim(Y.gpa$coords)[2]) # allometry-adjusted residuals
adj.shape <- shape.resid + array(Y.gpa$consensus, dim(shape.resid)) # allometry-free shapes
plotTangentSpace(adj.shape) # PCA of allometry-free shape

# Group Allometries
plethAllometry <- procD.allometry(coords~Csize, ~species * site, 
logsz = TRUE, data=gdf, iter=99, RRPP=TRUE)
summary(plethAllometry)
plot(plethAllometry, method = "PredLine")

# Using procD.lm to call procD.allometry (in case more results are desired)
plethANOVA <- procD.lm(plethAllometry$formula, 
data = plethAllometry$data, iter = 249, RRPP=TRUE)
summary(plethANOVA) # Same ANOVA

# procD.allometry is a wrapper function for procD.lm.  The same analyses
# can be performed with procD.lm, and better graphics options
# are available. More complex models can be considered.
  
# Here are some examples using procD.lm, instead, offering greater flexibility.

data(larvalMorph)
Y.gpa <- gpagen(larvalMorph$tailcoords, curves = larvalMorph$tail.sliders, print.progress = FALSE)
gdf <- geomorph.data.frame(Y.gpa, Treatment = larvalMorph$treatment, 
Family = larvalMorph$family)

# procD.allometry approach
tailAllometry <- procD.allometry(coords ~ Csize, ~ Treatment,
logsz = TRUE, alpha = 0.05, data = gdf, iter = 149)
summary(tailAllometry) # HOS test suggests parallel allometries, but not unambiguous
plot(tailAllometry, method = "PredLine")

# procD.lm approach, including interaction
tailAllometry2 <- procD.lm(coords ~ log(Csize) * Treatment, data = gdf, iter = 149)
plot(tailAllometry2, type = "regression", 
predictor = log(gdf$Csize), 
reg.type = "PredLine", 
pch = 21, 
bg = as.numeric(gdf$Treatment), 
xlab = "log(CS)") # greater flexibility

# including nested family effects, but still plotting by treatment
tailAllometry3 <- procD.lm(coords ~ log(Csize) * Treatment + 
Treatment/Family, data = gdf, iter = 149)
tailAllometry3 <- nested.update(tailAllometry3, ~ Treatment/Family)
summary(tailAllometry3)
plot(tailAllometry3, type = "regression", 
predictor = log(gdf$Csize), 
reg.type = "PredLine", 
pch = 21, 
bg = as.numeric(gdf$Treatment), 
xlab = "log(CS)")

geomorph documentation built on Aug. 10, 2017, 1:11 a.m.