# gpagen: Generalized Procrustes analysis of points, curves, and... In geomorph: Geometric Morphometric Analyses of 2D/3D Landmark Data

## 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. If data are provided in the form of a 3D array, all landmarks and semilandmarks are contained in this object. If this is the only component provided, the function will treat all points as if they were fixed landmarks. To designate some points as semilandmarks, one uses the "curves=" or "surfaces=" options (or both). To include semilandmarks on curves, a matrix defining which landmarks are to be treated as semilandmarks is provided using the "curves=" option. This matrix contains three columns that specify the semilandmarks and two neighboring landmarks which are used to specify the tangent direction for sliding. The matrix may be generated using the function `define.sliders`). 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.

## 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 27 28 29``` ```# 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) ###Slider matrix hummingbirds\$curvepts # 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
Warning messages:
1: In rgl.init(initValue, onlyNULL) : RGL: unable to open X11 display
2: 'rgl_init' failed, running with rgl.useNULL = TRUE
call: fun(...)

|
|                                                                      |   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
before slide after
[1,]      1    11    12
[2,]     11    12    13
[3,]     13    14    15
[4,]      7    15    14
[5,]     12    13    14
[6,]      1    16    17
[7,]     16    17    18
[8,]     17    18    19
[9,]     18    19    20
[10,]     10    20    19
[11,]      2    21    22
[12,]     21    22    23
[13,]     22    23    24
[14,]     23    24    25
[15,]      8    25    24

|
|                                                                      |   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.23038063 -0.003997317
[2,] -0.23134115 -0.007844114
[3,] -0.13363122  0.009672411
[4,] -0.10747276  0.011130859
[5,]  0.26046563  0.015170442
[6,]  0.24266833  0.014738788
[7,]  0.27203523  0.022869131
[8,]  0.26393067 -0.029721456
[9,]  0.28771045 -0.006640248
[10,]  0.34775294 -0.024537938
[11,] -0.21093986  0.004204929
[12,] -0.18213433  0.011535170
[13,] -0.15190431  0.015620984
[14,]  0.06306921  0.024720583
[15,]  0.15638001  0.025355349
[16,] -0.21048255 -0.004148772
[17,] -0.18078229 -0.001960152
[18,] -0.15141150 -0.001192872
[19,]  0.06141738 -0.001527932
[20,]  0.15577726 -0.005334088
[21,] -0.21080906 -0.010703577
[22,] -0.18015635 -0.013827499
[23,] -0.14999080 -0.015207926
[24,]  0.06106313 -0.011479811
[25,]  0.15551708 -0.017247647

|
|                                                                      |   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.23177780 -0.004053837
[2,] -0.23274386 -0.007948807
[3,] -0.13444106  0.009716761
[4,] -0.10812319  0.011190603
[5,]  0.26205360  0.015310938
[6,]  0.24414907  0.014874126
[7,]  0.27369405  0.023056837
[8,]  0.26556266 -0.029859286
[9,]  0.28947462 -0.006634070
[10,]  0.34989273 -0.024630456
[11,] -0.21080433  0.004828034
[12,] -0.18146702  0.012010638
[13,] -0.15183759  0.015775025
[14,]  0.05432773  0.024636337
[15,]  0.15352457  0.025649616
[16,] -0.21019929 -0.004143957
[17,] -0.17988193 -0.001879482
[18,] -0.15128261 -0.001235516
[19,]  0.05155584 -0.001366949
[20,]  0.15238262 -0.005009697
[21,] -0.21055528 -0.010981598
[22,] -0.17929658 -0.014205837
[23,] -0.14983075 -0.015265645
[24,]  0.05109760 -0.011418998
[25,]  0.15208739 -0.016902605

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

geomorph documentation built on April 29, 2018, 9:03 a.m.