Description Usage Arguments Details Value Author(s) References See Also Examples
View source: R/procD.allometry.r
Function performs Procrustes ANOVA with permutation procedures to facilitate visualization of sizeshape patterns (allometry); i.e., patterns of shape covariation with size for a set of Procrustesaligned coordinates. Results for plotting allometric patterns based on several approaches in the literature are available.
1 2 3 
f1 
A formula for the relationship of shape and size; e.g., Y ~ X. 
f2 
An optional righthand formula for the inclusion of groups; e.g., ~ groups. 
logsz 
A logical argument to indicate if the variable for size should be logtransformed. 
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 Pvalues 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 Pvalues 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 longrunning analyses. 
data 
A data frame for the function environment, see 
... 
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 crossproducts (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. 
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 twodimensional 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).
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).
Experienced or advanced users will probably prefer using
procD.lm
with a combination of plot.procD.lm
, shape.predictor
, and plotRefToTarget
for publicationquality 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.
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.
Compared to previous versions of geomorph, users might notice differences in effect sizes. Previous versions used zscores 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 zscores on their empirically estimated expected values and where appropriate, logtransform 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 ANOVAbased functions, the option to choose among different statistics to measure effect size is now a function argument.
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.
method = ("CAC, "RegScore, "PredLine"). Choose the desired plot method.
warpgrids: default = TRUE. Logical value to indicate whether warpgrids should be plotted. (Only works with 3D array data)
label: can be logical to label points (1:n)  e.g., label = TRUE  or a vector indicating text to use as labels.
mesh: A mesh3d object to be warped to represent shape deformation of the minimum and maximum size
if warpgrids=TRUE (see warpRefMesh
).
Use ?plot.procD.allometry
to understand the arguments used. The following are brief
descriptions of the different plotting methods using plot
, with references.
If "method=CAC" (the default) the function calculates the common allometric component of the shape data, which is an estimate of the average allometric trend for groupmean centered data (Mitteroecker et al. 2004). The function also calculates the residual shape component (RSC) for the data.
If "method=RegScore" the function calculates shape scores from the regression of shape on size, and plots these versus size (Drake and Klingenberg 2008). For a single group, these shape scores are mathematically identical to the CAC (Adams et al. 2013).
If "method=PredLine" the function calculates predicted values from a regression of shape on size, and plots the first principal component of the predicted values versus size as a stylized graphic of the allometric trend (Adams and Nistri 2010).
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 fsquared values found via the resampling procedure used. 
call 
The matched call. 
formula 
The resulting formula, which can be used in followup 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 
Michael Collyer
Adams, D.C., F.J. Rohlf, and D.E. Slice. 2013. A field comes of age: geometric morphometrics in the 21st century. Hystrix. 24:714.
Adams, D. C., and A. Nistri. 2010. Ontogenetic convergence and evolution of foot morphology in European cave salamanders (Family: Plethodontidae). BMC Evol. Biol. 10:110.
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:7176.
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:679698.
Collyer, M.L., D.J. Sekora, and D.C. Adams. 2015. A method for analysis of phenotypic change for phenotypes described by highdimensional data. Heredity. 115:357365.
Adams, D.C. and M.L. Collyer. 2016. On the comparison of the strength of morphological integration across morphometric datasets. Evolution. 70:26232631.
procD.lm
and advanced.procD.lm
within geomorph;
lm
for more on linear model fits
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) #GPAalignment
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 sizeadjusted residuals (and allometryfree 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]) # allometryadjusted residuals
adj.shape < shape.resid + array(Y.gpa$consensus, dim(shape.resid)) # allometryfree shapes
plotTangentSpace(adj.shape) # PCA of allometryfree 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 = 149, 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)")

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.