Format configurations into a data block — formatBlock • morphoBlocks

Organises data representing a block of landmark configurations (or pseudolandmark configurations) into a single data block. formatBlock is useful for formatting a data block of configurations from sources other than Landmark Editor (Wiley et al. 2005) or Generalized Procrustes Surface Analysis (Pomidor et al. 2016).

formatBlock(
  block,
  curves = NULL,
  surfaces = NULL,
  cs = NULL,
  k = 2,
  gpa = TRUE
)

Arguments

block	two-dimensional matrix or three-dimensional array of configurations to be formatted into a data block.
curves	optional matrix passed to `gpagen` for correctly calculating position of curve semilandmarks (see `geomorph::gpagen` for more detail).
surfaces	optional vector passed to `gpagen` for defining positions of semilandmarks on surfaces (see `geomorph::gpagen` for more detail).
cs	optional vector of centroid sizes.
k	number of dimensions that each point within the data block has. Required for configurations presented as a two-dimensional matrix. `k = 2` by default, but is updated when data are presented as a three-dimensional array.
gpa	a logical value indicating whether generalized Procrustes analyses should be performed. Default is `TRUE`.

Value

a 'block' object, used for downstream analyses. The list contains the elements:

raw

collation of original configuration data

gpa.3D

if gpa = TRUE, configurations after Procrustes transformation organised into a 3D array. If gpa = FALSE, original configuration data organised into a 3D array (may duplicate raw)

gpa.2D

if gpa = TRUE, configurations after Procrustes transformation organised into a 2D matrix. If gpa = FALSE, original configuration data organised into a 2D matrix (may duplicate raw)

centroid

centroid sizes either calculated from original configurations or supplied using the cs argument

number of points in the configurations of each data block

number of dimensions that the points in each configuration has

number of configurations included in each data block

Details

formatBlock expects configurations to be presented as either a two-dimensional matrix or a three-dimensional array. If data are presented as a two-dimensional matrix then the number of k dimensions for the landmarks (or pseudolandmarks) must be specified (default k = 2), each configuration should be a separate row in the matrix, and columns should contain corresponding points and dimensions in each configuration. If data are presented as a three-dimensional array then each of the n configurations should be a separate matrix in the array (i.e. array[p, k, n]), and each matrix should have the same number of rows and columns where rows represent p points and columns represent k dimensions of each point. By default formatBlock will perform generalized Procustes analysis (gpa) on the block using gpagen from the geomorph package (Adams and Otárola-Castillo 2013). Curve and surface information must be supplied if they are required. Centroid size will be calculated from the original configurations before Procrustes transformation. If gpa is not required then set gpa = FALSE. Centroid sizes of the original configurations should be supplied using the cs argument if gpa = FALSE, or else centroid sizes will be calculated from the (presumably Procrustes-transformed) configurations that are supplied. formatBlock is a wrapper function for the cSize function from the Morpho package (Schlager 2017), and the gpagen, two.d.array and arrayspecs functions from the geomorph package (Adams and Otárola-Castillo 2013).

References

Adams DC, Otárola-Castillo E. 2013. geomorph: an R package for the collection and analysis of geometric morphometric shape data. Methods in Ecology and Evolution 4:393–399 https://doi.org/10.1111/2041-210X.12035

Schlager S. 2017. Morpho and Rvcg–shape analysis in R. In Zheng G, Li S, Székely (eds.) Statistical shape and deformation analysis. Academic Press, London. Pp. 217–256.

Pomidor BJ, Makedonska J, Slice DE. 2016. A landmark-free method for three-dimensional shape analysis. PLoS One 11: e0150368 https://doi.org/10.1371/journal.pone.0150368

Wiley DF, Amenta N, Alcantara DA, Ghosh D, Kil YJ, Delson E, Harcourt-Smith W, Rohlf FJ, St. John K, Hamann B. 2005. Evolutionary morphing. Proceedings of the IEEE Visualization 2005 (VIS’05), 431–438.

Examples

# Format the head and tail data from the Plethodon dataset in the geomorph library

# Load the geomorph package
library(geomorph)

# Access the Plethodon head and tail landmark data from the larvalMorph dataset
data(larvalMorph)

# Format the Plethodon head data as block 1 (requires specifying mapping information for the curve semilandmarks)
block1 <- formatBlock(block = larvalMorph$headcoords, curves = larvalMorph$head.sliders)

# Format the Plethodon tail data as block 2 (requires specifying mapping information for the curve semilandmarks)
block2 <- formatBlock(block = larvalMorph$tailcoords, curves = larvalMorph$tail.sliders)