---
title: "A synopsis of geomorph functions"
author: "Antigoni Kaliontzopoulou"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{geomorph functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```


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  |


