Simulate a data block of landmark configurations

Generates a block of n dodecahedra where the vertices of each dodecahedron represent a landmark configuration with p = 20 points in k = 3 dimensions. The data block is transformed using generalized Procrustes analysis.

dodecBlock(
  n = 10,
  dist_x = NULL,
  dist_y = NULL,
  dist_z = NULL,
  theta_x = NULL,
  theta_y = NULL,
  theta_z = NULL,
  size = NULL,
  noise = NULL,
  vertex_shift = NULL,
  plot = FALSE
)

Arguments

n	the number of configurations to generate for the data block. Default is 10. Must be 2 or greater.
dist_x, dist_y, dist_z	optional integer or vector to specify a distance along the stated axis (i.e. `dist_x` for the x axis) for translating the configurations. If no value is specified then configurations will not be translated. If a single integer is supplied (e.g. `dist_x = 1`) then all configurations will be translated along an axis by the same amount. If a vector of length n is supplied (e.g. `dist_x = 1:10`) then each configuration will be translated by a value corresponding to its position in the vector.
theta_x, theta_y, theta_z	optional integer or vector to specify an angle for rotating the configuration about its origin in the stated axis (i.e. `theta_x` for the x axis). If no value is specified then configurations will not be rotated. If a single integer is supplied (e.g. `theta_x = 30`) then all configurations will be rotated by the same amount. If a vector of length n is supplied (e.g. `theta_x = seq(from = 0, to = 210, by = 30)`) then each configuration will be rotated by a value corresponding to its position in the vector.
size	optional integer or vector for scaling the configurations. If no value is specified then configurations will not be scaled relative to one another. If a single integer is supplied (e.g. `size = 1`) then all configurations will be scaled by the same amount. If a vector of length n is supplied (e.g. `size = 1:10`) then each configuration will be scaled by a value corresponding to its position in the vector.
noise	optional integer for introducing noise to the configurations. If no value is specified then `runif(1, min = 0, max = (1 / 100))` is added to each of the `x`, `y` and `z` positions of each point in each configuration. This small amount of noise is added so that no configuration has identical coordinates. The amount of noise that is introduced to the data block can be increased by specifying a noise value that is greater than 1.
vertex_shift	optional integer or vector to specify a distance along the z axis for translating the first vertex in each configuration. This argument can be used to introduce variation into the data block. If no value is specified then vertex 1 in each configuration will not be translated. If a single integer is supplied (e.g. `vertex_shift = 1`) then vertex 1 in all configurations will be translated along the z axis by the same amount. If a vector of length n is supplied (e.g. `vertex_shift = 1:10`) then vertex 1 in each configuration will be translated by a value corresponding to its position in the vector. Things get really fun when you use both `vertex_shift` and `theta_z` together (see example 2 below).
plot	a logical value indicating whether the configurations should be plotted. Default is FALSE.

Value

a 'blockList' object of n dodecahedra, used for downstream analyses. The list contains the elements:

raw

configurations without Procrustes transformation

gpa.3D

configurations after Procrustes transformation organised into a 3D array

gpa.2D

configurations after Procrustes transformation organised into a 2D matrix

centroid

centroid sizes of the configurations

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

dodecBlock builds a data block of configurations that have been transformed using generalized Procrustes analysis. The resulting data block is a three dimensional array with n = 2 or greater configurations, with each configuration represented by p = 20 points that have k = 3 dimensions. Several objects are calculated for downstream analyses including centroid sizes for each configuration. formatBlock uses 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.

Examples

# Example 1: Generate a block with ten configurations
block <- dodecBlock()

# Example 2: Generate a block with five configurations.
# Rotate the configurations and translate the first vertex in each configuration.
# Plot the result.
block2 <- dodecBlock(n = 5, theta_z = seq(from = 0, to = 270, by = 60), vertex_shift = 0:4, plot = TRUE)