# A synopsis of geomorph functions

#### Antigoni Kaliontzopoulou

#### 2023-01-16

The tables below provide a summary index of `geomorph` functions and their main purpose, to assist users to find available tools. They are organized into: 1) Analytical, 2) Utility, and 3) Plotting functions. At the end, a separate table provides an overview of the example datasets available.

NOTE: Deprecated (or soon to be) functions are not included.

## Analytical functions

These are the core analytical functions of `geomorph`. Many of them produce S3 objects which can then be further explored using `summary()` and `plot()`.

Function name | Brief description | `summary()` | `plot()`
--- | --- | --- | ---
`bilat.symmetry` | Symmetry analysis and calculation of symmetric and asymmetric shape components | X | X
`compare.evol.rates` | Calculate and compare rates of shape evolution among groups on a phylogeny | X | X
`compare.multi.evol.rates` | Calculate and compare evolutionary rates for two or more shape traits on a phylogeny | X | X
`compare.pls` | Compare effect sizes of two or more PLS fits | X |
`estimate.missing` | Estimate the position of missing landmarks using regression or the TPS |  |
`fixed.angle` | Standardize the angle of articulated structures |  |
`globalIntegration` | Calculate global integration as the slope of the log-variance of partial warps vs. their bending energy |  |
`gm.prcomp` | Principal components analysis of Procrustes shape coordinates | X | X
`gpagen` | Generalized Procrustes Analysis | X | X
`integration.test` | Test for morphological integration using PLS | X | X
`modularity.test` | Test for morphological modularity using the Covariance Ratio | X | X
`morphol.disparity` | Estimate and compare across groups morphological disparity | X |
`mshape` | Calculate the mean shape of a landmark configuration |  | X
`phylo.integration` | Test for morphological integration across species while accounting for phylogeny using PLS | X | X
`phylo.modularity` | Test for morphological modularity across species using the Covariance Ratio, while accounting for phylogeny | X | X
`physignal` | Calculate phylogenetic signal for shape data | X | X
`procD.lm` | Linear model and Procrustes ANOVA with permutation procedures | X | X
`procD.pgls` | Linear model and Procrustes ANOVA in a phylogenetic framework with permutation procedures | X | X
`shape.predictor` | Estimate shape configurations based on linear predictors |  |
`two.b.pls` | Two-block partial least squares analysis | X | X

## Utility functions

These include functions for reading and writing data, digitizing, data-formatting operations

Function name | Brief description
--- | ---
`arrayspecs` | Transform a matrix of landmark coordinates into an array
`buildtemplate` | Build template of 3D surface semilandmarks
`combine.subsets` | Combine subsets of landmarks into a single configuration by specimen
`coords.subset` | Subset landmark coordinates by grouping factor
`define.links` | Interactively make link definition matrix
`define.modules` | Interactively make module definition matrix
`define.sliders` | Interactively make sliding semilandmark definition matrix
`digit.curves` | Digitize 3D curve semilandmarks in a 3D surface object
`digit.fixed` | Digitize fixed 3D landmarks in a 3D surface object
`digitize2d` | Digitize 2D landmarks in jpg files
`digitsurface` | Digitize 3D fixed landmarks and surface semilandmarks in a 3D surface object using an already created template
`editTemplate` | Manually remove surface semilandmarks from a 3D template
`findMeanSpec` | Identify specimen closest to the mean
`geomorph.data.frame` | Combine data for analyses into a geomorph data frame
`interlmkdist` | Calculate linear distances between landmarks
`read.morphologika` | Read morphologika file
`read.ply` | Read ply file
`readland.nts` | Read nts file
`readland.shapes` | Read `StereoMorph` shapes object
`readland.tps` | Read tps file
`readmulti.nts` | Read multiple nts files simultaneously
`rotate.coords` | Rotate or flip landmark coordinates
`two.d.array` | Transform an array of landmark coordinates into a matrix
`writeland.tps` | Save landmarks in tps file

## Plotting functions

Stand-alone `geomorph` plotting functions. For S3 plot functions of `geomorph` objects see the section of analytical functions.

Function name | Brief description
--- | ---
`picknplot.shape` | Interactively pick a point in a scatterplot (output from another `geomorph` function) and visualize the corresponding shape
`plotAllometry` | Different options for visualizing allometric plots from an lm fit
`plotAllSpecimens` | Plot all the specimens in a sample
`plotGMPhyloMorphoSpace` | Phylomorphospace plot, with the possibility of visualizing time as the z axis
`plotOutliers` | Visualization of outliers through inspection of the distribution of Procrustes distances of individual shapes from the consensus configuration
`plotRefToTarget` | Obtain deformation grids between a reference and plot specimen using the TPS
`plotspec` | Single 3D specimen plotting
`shapeHulls` | Update procD.lm or gm.prcomp plots to add convex hulls for groups
`warpRefMesh` | Warp a 3D mesh into the mean shape
`warpRefOutline` | Warp a 2D outline into the mean shape

## Example datasets

Example datasets included in `geomorph` are:

Dataset | landmarks + semilandmarks (p) | Landmark dimensions (k) | Sample size (n) | Content
--- | --- | --- | --- | ---
`hummingbirds` | 10 + 15 | 2 | 44 | Hummingbird bill shape data, and slider definition matrix
`larvalMorph` | 1 + 25 / 6 + 58 | 2 | 114 | Salamander larvae head and tail landmark coordinates, and corresponding slider definition matrices and treatment and family indices
`mosquito` | 18 | 2 | 40 | Mosquito wings with individual, side and replicate indices for symmetry analysis
`plethodon` | 12 | 2 | 40 | Salamander skulls with links, outline, and species and site indices
`plethShapeFood` | 13 | 2 | 69 | Salamander skulls and corresponding food items matrix
`plethspecies` | 11 | 2 | 9 | Skull shape data for 11 salamander species and corresponding phylogeny
`pupfish` | 56 | 2 | 54 | Pupfish shape data (superimposed) and corresponding centroid size, sex and population indices
`ratland` | 8 | 2 | 164 | Rat skull landmark data
`scallopPLY` | 166 | 3 | 1 | Scallop 3D scan in ply format, and corresponding matrix with digitized surface sliding semilandmarks
`scallops` | 46 + 11 + 30 | 3 | 5 | Fixed landmarks, curve and surface semilandmarks for scallop specimens, and corresponding matrix of symmetric landmark pairs