Getting Started

I. What is geomorph?

Geomorph is a freely available software package for geometric morphometric analyses of two- and three-dimensional landmark (shape) data in the R statistical computing environment. It can be installed from the Comprehensive R Archive Network, CRAN http://cran.r-project.org/web/packages/geomorph/. Occasionally, we make updates between uploads to CRAN. Users can install via GitHub the current beta version from https://github.com/geomorphR/geomorph.

How to cite: When using geomorph in publications, please cite the software with version and the publication.

citation(package="geomorph")
## 
## To cite package 'geomorph' in a publication use:
## 
##   Adams, D.C., and E. Otarola-Castillo. 2013. geomorph: an R
##   package for the collection and analysis of geometric
##   morphometric shape data. Methods in Ecology and Evolution.
##   4:393-399.
## 
## A BibTeX entry for LaTeX users is
## 
##   @Article{,
##     title = {geomorph: an R package for the collection and analysis of geometric morphometric shape data},
##     author = {D.C. Adams and E. Otarola-Castillo},
##     journal = {Methods in Ecology and Evolution},
##     year = {2013},
##     volume = {4},
##     pages = {393-399},
##   }
## 
## As geomorph is evolving quickly, you may want to cite also its
## version number (found with 'library(help = geomorph)').

Also, since the package is quickly evolving, it is advisable to cite the CRAN package and version as:

Adams, D.C., M. L. Collyer, and E. Sherratt. 2016 geomorph: Software for geometric morphometric analyses. R package version 3.x http://cran.r-project.org/web/ packages/geomorph/index.html.

II. How to use this manual

This manual is not meant to be exhaustive – the benefit of working within the R environment is its flexibility and infinite possibilities. Instead, the manual presents the functions in geomorph and how they can be used together to perform analyses to address a variety of questions in Biology, Anthropology, Paleontology, Archaeology, Medicine etc. This help guide is structured according to the pipeline outlined in Figure 1, which is based on a general workflow for morphometric analysis.

Figure 1 Overview of the morphometric analysis process. In blue are the steps performed in R and geomorph, and those in orange are done outside of R and imported in.

In Vignette 1, we go over how to import data files of (raw) landmark coordinates digitized elsewhere, e.g., using software such as ImageJ or tpsDig for 2D data, or IDAV Landmark editor, AMIRA, Microscribe for 3D data (note that data collection – digitizing landmarks – can also be done in geomorph, and is outlined in Vignette 4). Then we demonstrate some techniques and functions for preparing and manipulating imported datasets, such as adding grouping variables and estimating missing data, and adjusting articulated datasets (2D only). Note that some functions described in this section can also be used on Procrustes coordinate data, but are presented here because they are important steps to learn familiarize the user with the R environment. In Vignette 2 the raw data are taken through the morphometric-specific step of alignment using a generalized Procrustes superimposition, which is imperative for raw coordinate data. In Vignette 3, the statistical analysis functions are presented in order by type of analysis (Table 1). In Vignette 4, we describe how to plot and visualize the data analysis results, including shape deformation graphs and ordination plots (e.g., PCA). In Vignette 5 the functions that can be used to generate coordinate data from 2D images and 3D surface files (i.e., an ASCII .ply) are discussed. In Vignette 6 there are some frequently asked questions and their solutions, and references listed in these guides.

Table 1 Functions in geomorph.

Input Preparation Analysis
read.morphologika arrayspecs advanced.procD.lm
readland.nts define.links bilat.symmetry
readland.tps define.modules compare.evol.rates
readmulti.nts estimate.missing compare.multi.evol.rates
findMeanSpec globalIntegration
fixed.angle gpagen
mshape integration.test
two.d.array morphol.disparity
writeland.tps phylo.integration
phylo.modularity
physignal
procD.lm
procD.pgls
trajectory.analysis
two.b.pls
Visualization Datasets Digitizing
procD.allometry hummingbirds buildtemplate
gridPar mosquito define.sliders
plotAllSpecimens motionpaths digit.curves
plotGMPhyloMorphoSpace plethodon digit.fixed
plotOutliers plethspecies digitize2d
plotRefToTarget plethShapeFood digitsurface
plotspec pupfish editTemplate
plotTangentSpace ratland read.ply
warpRefMesh scallopPLY
warpRefOutline scallops
larvalTails

Throughout this manual, we will use the following abbreviations as is conventional in morphometrics and R: n number of specimens/individuals
p number of landmarks
k number of dimensions
# a comment, in R this is text that is ignored (not run)
... data not shown
code code to be written into the R console
[1] in a code example at the start of a line, a number in brackets denotes the first element of the output and is not intended to be typed

Briefly understanding functions; below is a geomorph function annotated by color:

procD.allometry(f1, f2 = NULL, f3 = NULL, logsz = TRUE, iter = 999,
  seed = NULL, alpha = 0.05, RRPP = TRUE, data = NULL, ...)

readland.tps(file, specID = c("None", "ID", "imageID"), readcurves = FALSE,
  warnmsg = TRUE)

In dark blue, the function name and options. In black, an object, usually data, a formula of data, or sometimes a file name. In green, a multipart option, requires choice of ONE of the presented values. In brown, a logical option that requires a TRUE or FALSE input, or an option that requires a value. In blue, an option that requires a numeric value.
Usually only the objects are necessary to run a function, as it will use the defaults for the options (which are presented in the function as above, and under “usage” in the R help pages). Always read the help pages and check the examples for usage. Order does not matter as long as the option is written in full, e.g., A= mydata. But " " are important, e.g., method = "RegScore".

Finally, I occasionally write source code for very specific issues to complement geomorph functions. They can be found here: http://emsherratt.github.io/MorphometricSupportCode/.

III. Installing geomorph and R

These instructions assume you already have R (and perhaps also RStudio) installed.

To install geomorph from CRAN

install.packages("geomorph", dependencies = TRUE)

This will install the latest version of geomorph from CRAN https://cran.rstudio.com/.

Alternatively, if you prefer menus:
Rapp: Packages & Data > Package Installer > Choose CRAN (binaries) from drop down menu, type geomorph in box and click get list. Select geomorph, select install dependencies box, and click install selected.
or
Rstudio: Packages tab > Install: Install from CRAN repository > type geomorph in box and select install dependencies box, and click install.

Installing from GitHub

CRAN restricts the number of updates package maintainers can make in a year. Occasionally, bugs slip through that need to be fixed immediately. We maintain a “Stable” version of the current CRAN version of geomorph in our GitHub repository, which can be installed as source.

To install the source package from GitHub:

install.packages("devtools", dependencies = TRUE)
devtools::install_github("geomorphR/geomorph",ref = "Stable")

Installing the beta version

We have a beta version for the upcoming version that contains the most current updates and new features. It is held on a GitHub repository:

To install the beta geomorph package:

devtools::install_github("geomorphR/geomorph",ref = "Develop")

Installing compilers for Mac users:

Previous versions of geomorph required users to have compilers installed in order to install packages from source. This is no longer necessary from geomorph version 3.0. However the information is provided here if any issues arise.

  1. Go to the Mac App store and download Xcode Development Tools https://itunes.apple.com/au/app/xcode/id497799835?mt=12 and follow install instructions. For OS10.6, follow the instructions here http://kitcambridge.tumblr.com/post/17778742499/installing-the-xcode-command-line-tools-on-snow.

  2. Download the compilers. For OS10.8 and below: go to CRAN website here and download the GNU Fortran compiler (gfortran-4.2.3.pkg) and follow install instructions. For OS10.9 and above: Open Terminal (Applications/Utilities) and type in:

curl -O http://r.research.att.com/libs/gfortran-4.8.2-darwin13.tar.bz2

This will download the installer. Then type

sudo tar fvxz gfortran-4.8.2-darwin13.tar.bz2 -C /

This will install the compilers into the /usr/local/lib/ folder. The command sudo will ask for your password. Type it in, but note it will not appear on the line. Press return. The terminal window will fill with all the files being written. (This information is thanks to the The Coatless Professor http://r.research.att.com/libs/gfortran-4.8.2-darwin13.tar.bz2 sudo tar fvxz gfortran-4.8.2-darwin13.tar.bz2 -C /).

  1. Download and install XQuartz (X11) http://xquartz.macosforge.org/trac if it is not already on your Mac. It will be installed in the Utilities folder. This program must be running every time you use geomorph (required by rgl).

This is a short version of information available here http://cran.r-project.org/bin/macosx/tools/ and here http://r.research.att.com/tools/.

Installing compilers for Windows users:

Go to the R website and download RTools http://cran.rstudio.com/bin/windows/Rtools. Make sure to download the correct version! Follow the install instructions. You may need to modify the path (asked during the installing). Try first without ticking the box on the install window. If running install_github() above does not work then re-install the RTools with the new path box ticked). Alternatively, use the function find_rtools() in devtools package.

For more information for Windows users, see here http://cran.r-project.org/doc/manuals/R-admin.html#The-Windows-toolset.

Using geomorph

Regardless of how you install geomorph, in order to use it you must start every session by loading the package

library(geomorph)
## Loading required package: rgl
## Loading required package: ape

You’ll notice that a black warning message is printed in the console saying the package rgl and ape are also loaded. All of the 3D plots of interactive functions of geomorph are run through rgl https://cran.r-project.org/web/packages/rgl/index.html. ape is called for several phylogenetic analyses.

IV. Workflows for common analyses

Below are some pathways to perform common analyses in geomorph. This is not an exhaustive list, but provides a reference for users familiar with other morphometric software to navigate the functions. In red the type of question or analysis is presented, and in blue the specific geomorph functions in sequence.