gpagen: Generalized Procrustes analysis of points, curves, and...

Description Usage Arguments Details Value Author(s) References Examples

View source: R/gpagen.r

Description

A general function to perform Procrustes analysis of two- or three-dimensional landmark data that can include both fixed landmarks and sliding semilandmarks

Usage

1
2
gpagen(A, curves = NULL, surfaces = NULL, PrinAxes = TRUE,
  max.iter = NULL, ProcD = TRUE, Proj = TRUE, print.progress = TRUE)

Arguments

A

A 3D array (p x k x n) containing landmark coordinates for a set of specimens

curves

An optional matrix defining which landmarks should be treated as semilandmarks on boundary curves, and which landmarks specify the tangent directions for their sliding

surfaces

An optional vector defining which landmarks should be treated as semilandmarks on surfaces

PrinAxes

A logical value indicating whether or not to align the shape data by principal axes

max.iter

The maximum number of GPA iterations to perform before superimposition is halted. The final number of iterations could be larger than this, if curves or surface semilandmarks are involved.

ProcD

A logical value indicating whether or not Procrustes distance should be used as the criterion for optimizing the positions of semilandmarks

Proj

A logical value indicating whether or not the aligned Procrustes residuals should be projected into tangent space

print.progress

A logical value to indicate whether a progress bar should be printed to the screen.

Details

The function performs a Generalized Procrustes Analysis (GPA) on two-dimensional or three-dimensional landmark coordinates. The analysis can be performed on fixed landmark points, semilandmarks on curves, semilandmarks on surfaces, or any combination. To include semilandmarks on curves, one must specify a matrix defining which landmarks are to be treated as semilandmarks using the "curves=" option. Likewise, to include semilandmarks on surfaces, one must specify a vector listing which landmarks are to be treated as surface semilandmarks using the "surfaces=" option. The "ProcD=TRUE" option will slide the semilandmarks along their tangent directions using the Procrustes distance criterion, while "ProcD=FALSE" will slide the semilandmarks based on minimizing bending energy. The aligned Procrustes residuals can be projected into tangent space using the "Proj=TRUE" option. NOTE: Large datasets may exceed the memory limitations of R.

Generalized Procrustes Analysis (GPA: Gower 1975, Rohlf and Slice 1990) is the primary means by which shape variables are obtained from landmark data (for a general overview of geometric morphometrics see Bookstein 1991, Rohlf and Marcus 1993, Adams et al. 2004, Zelditch et al. 2012, Mitteroecker and Gunz 2009, Adams et al. 2013). GPA translates all specimens to the origin, scales them to unit-centroid size, and optimally rotates them (using a least-squares criterion) until the coordinates of corresponding points align as closely as possible. The resulting aligned Procrustes coordinates represent the shape of each specimen, and are found in a curved space related to Kendall's shape space (Kendall 1984). Typically, these are projected into a linear tangent space yielding Kendall's tangent space coordinates (Dryden and Mardia 1993, Rohlf 1999), which are used for subsequent multivariate analyses. Additionally, any semilandmarks on curves and are slid along their tangent directions or tangent planes during the superimposition (see Bookstein 1997; Gunz et al. 2005). Presently, two implementations are possible: 1) the locations of semilandmarks can be optimized by minimizing the bending energy between the reference and target specimen (Bookstein 1997), or by minimizing the Procrustes distance between the two (Rohlf 2010). Note that specimens are NOT automatically reflected to improve the GPA-alignment.

The generic functions, print, summary, and plot all work with gpagen. The generic function, plot, calls plotAllSpecimens.

Notes for geomorph 3.0

Compared to older versions of geomorph, users might notice subtle differences in Procrustes residuals when using semilandmarks (curves or surfaces). This difference is a result of using recursive updates of the consensus configuration with the sliding algorithms (minimized bending energy or Procrustes distances). (Previous versions used a single consensus through the sliding algorithms.) Shape differences using the recursive updates of the consensus configuration should be highly correlated with shape differences using a single consensus during the sliding algorithm, but rotational "flutter" can be expected. This should have no qualitative effect on inferential analyses using Procrustes residuals.

Value

An object of class gpagen returns a list with the following components:

coords

A (p x k x n) array of aligned Procrustes coordinates, where p is the number of landmark points, k is the number of landmark dimensions (2 or 3), and n is the number of specimens. The third dimension of this array contains names for each specimen if specified in the original input array.

Csize

A vector of centroid sizes for each specimen, containing the names for each specimen if specified in the original input array.

iter

The number of GPA iterations until convergence was found (or GPA halted).

points.VCV

Variance-covariance matrix among landmark coordinates.

points.var

Variances of landmark points.

consnsus

The consensus (mean) configuration.

p

Number of landmarks.

k

Number of landmark dimensions.

nsliders

Number of semilandmarks along curves.

nsurf

Number of semilandmarks as surface points.

data

Data frame with an n x (pk) matrix of Procrustes residuals and centroid size.

Q

Final convergence criterion value.

slide.method

Method used to slide semilandmarks.

call

The match call.

Author(s)

Dean Adams and Michael Collyer

References

Adams, D. C., F. J. Rohlf, and D. E. Slice. 2004. Geometric morphometrics: ten years of progress following the 'revolution'. It. J. Zool. 71:5-16.

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.

Bookstein, F. L. 1991. Morphometric tools for landmark data: Geometry and Biology. Cambridge Univ. Press, New York.

Bookstein, F. L. 1997. Landmark methods for forms without landmarks: morphometrics of group differences in outline shape. 1:225-243.

Dryden, I. L., and K. V. Mardia. 1993. Multivariate shape analysis. Sankhya 55:460-480.

Gower, J. C. 1975. Generalized Procrustes analysis. Psychometrika 40:33-51.

Gunz, P., P. Mitteroecker, and F. L. Bookstein. 2005. semilandmarks in three dimensions. Pp. 73-98 in D. E. Slice, ed. Modern morphometrics in physical anthropology. Klewer Academic/Plenum, New York.

Kendall, D. G. 1984. Shape-manifolds, Procrustean metrics and complex projective spaces. Bulletin of the London Mathematical Society 16:81-121.

Mitteroecker, P., and P. Gunz. 2009. Advances in geometric morphometrics. Evol. Biol. 36:235-247.

Rohlf, F. J., and D. E. Slice. 1990. Extensions of the Procrustes method for the optimal superimposition of landmarks. Syst. Zool. 39:40-59.

Rohlf, F. J., and L. F. Marcus. 1993. A revolution in morphometrics. Trends Ecol. Evol. 8:129-132.

Rohlf, F. J. 1999. Shape statistics: Procrustes superimpositions and tangent spaces. Journal of Classification 16:197-223.

Rohlf, F. J. 2010. tpsRelw: Relative warps analysis. Version 1.49. Department of Ecology and Evolution, State University of New York at Stony Brook, Stony Brook, NY.

Zelditch, M. L., D. L. Swiderski, H. D. Sheets, and W. L. Fink. 2012. Geometric morphometrics for biologists: a primer. 2nd edition. Elsevier/Academic Press, Amsterdam.

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
# Example 1: fixed points only
data(plethodon) 
Y.gpa <- gpagen(plethodon$land,PrinAxes=FALSE)
summary(Y.gpa)
plot(Y.gpa)

# Example 2: points and semilandmarks on curves
data(hummingbirds)

# Using Procrustes Distance for sliding
Y.gpa <- gpagen(hummingbirds$land,curves=hummingbirds$curvepts)   
summary(Y.gpa)
plot(Y.gpa)

# Using bending energy for sliding
Y.gpa <- gpagen(hummingbirds$land,curves=hummingbirds$curvepts,ProcD=FALSE)   
summary(Y.gpa)
plot(Y.gpa)

# Example 3: points, curves and surfaces
data(scallops)

# Using Procrustes Distance for sliding
Y.gpa <- gpagen(A=scallops$coorddata, curves=scallops$curvslide, surfaces=scallops$surfslide)
# NOTE can summarize as: summary(Y.gpa)
# NOTE can plot as: plot(Y.gpa) 

Example output

Loading required package: rgl
Loading required package: ape
Warning messages:
1: In rgl.init(initValue, onlyNULL) : RGL: unable to open X11 display
2: 'rgl_init' failed, running with rgl.useNULL = TRUE 
3: .onUnload failed in unloadNamespace() for 'rgl', details:
  call: fun(...)
  error: object 'rgl_quit' not found 

  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |======================================================================| 100%

Call:
gpagen(A = plethodon$land, PrinAxes = FALSE) 



Generalized Procrustes Analysis
with Partial Procrustes Superimposition

12 fixed landmarks
0 semilandmarks (sliders)
2-dimensional landmarks
2 GPA iterations to converge


Consensus (mean) Configuration

                X            Y
 [1,]  0.15211185 -0.026533305
 [2,]  0.19247319 -0.096684354
 [3,] -0.03375833 -0.006642568
 [4,] -0.28257532 -0.086967013
 [5,] -0.31120803 -0.055184150
 [6,] -0.32626166 -0.029304072
 [7,] -0.31721998  0.042760371
 [8,] -0.18738266  0.101946978
 [9,]  0.02243401  0.098665833
[10,]  0.19009938  0.073323490
[11,]  0.35264222  0.058513478
[12,]  0.54864532 -0.073894687

  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |======================================================================| 100%

Call:
gpagen(A = hummingbirds$land, curves = hummingbirds$curvepts) 



Generalized Procrustes Analysis
with Partial Procrustes Superimposition

10 fixed landmarks
15 semilandmarks (sliders)
2-dimensional landmarks
6 GPA iterations to converge
Minimized squared Procrustes Distance used


Consensus (mean) Configuration

                X            Y
 [1,] -0.23023465 -0.003983208
 [2,] -0.23119517 -0.007830006
 [3,] -0.13348524  0.009686519
 [4,] -0.10732678  0.011144967
 [5,]  0.26061161  0.015184550
 [6,]  0.24281431  0.014752896
 [7,]  0.27218121  0.022883239
 [8,]  0.26407665 -0.029707348
 [9,]  0.28785643 -0.006626140
[10,]  0.34789892 -0.024523830
[11,] -0.21079388  0.004219037
[12,] -0.18198835  0.011549278
[13,] -0.15175833  0.015635092
[14,]  0.06321519  0.024734691
[15,]  0.15652599  0.025369457
[16,] -0.21033657 -0.004134664
[17,] -0.18063631 -0.001946044
[18,] -0.15126552 -0.001178764
[19,]  0.06156336 -0.001513824
[20,]  0.15592324 -0.005319980
[21,] -0.21066309 -0.010689469
[22,] -0.18001037 -0.013813391
[23,] -0.14984482 -0.015193818
[24,]  0.06120911 -0.011465702
[25,]  0.15566306 -0.017233539

  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |======================================================================| 100%

Call:
gpagen(A = hummingbirds$land, curves = hummingbirds$curvepts,  
    ProcD = FALSE) 



Generalized Procrustes Analysis
with Partial Procrustes Superimposition

10 fixed landmarks
15 semilandmarks (sliders)
2-dimensional landmarks
6 GPA iterations to converge
Minimized Bending Energy used


Consensus (mean) Configuration

                X            Y
 [1,] -0.23048024 -0.004114324
 [2,] -0.23144631 -0.008009294
 [3,] -0.13314350  0.009656274
 [4,] -0.10682564  0.011130116
 [5,]  0.26335116  0.015250451
 [6,]  0.24544662  0.014813639
 [7,]  0.27499160  0.022996350
 [8,]  0.26686021 -0.029919773
 [9,]  0.29077218 -0.006694557
[10,]  0.35119028 -0.024690943
[11,] -0.20950678  0.004767547
[12,] -0.18016947  0.011950151
[13,] -0.15054004  0.015714539
[14,]  0.05562528  0.024575850
[15,]  0.15482212  0.025589129
[16,] -0.20890174 -0.004204444
[17,] -0.17858438 -0.001939969
[18,] -0.14998506 -0.001296003
[19,]  0.05285339 -0.001427436
[20,]  0.15368018 -0.005070184
[21,] -0.20925773 -0.011042085
[22,] -0.17799902 -0.014266324
[23,] -0.14853320 -0.015326132
[24,]  0.05239516 -0.011479485
[25,]  0.15338494 -0.016963092

  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |======================================================================| 100%

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