facefuns: Quickstart to shape analyses of 2-D or 3-D data

In iholzleitner/facefuns: Convenience Functions Around 2D and 3D Face Shape Analysis

Description

\lifecycle

maturing

Performs some of the routine steps for getting landmark data ready for shape analyses, such as Procrustes alignment and principal component analysis. For more details see vignette: vignette("intro", package = "facefuns")

Usage

facefuns(
  data,
  remove_points = NULL,
  pc_criterion = "broken_stick",
  plot_sample = TRUE,
  auto_rotate = TRUE,
  quiet = FALSE
)

Arguments

data	Array of dimensions p, k, and n, where p = number of landmarks/vertices, k = dimensionality of data (2 or 3), n = number of specimens
remove_points	Specify any points/landmarks you want to remove prior to analyses. See remove_points and frl_features for more info
pc_criterion	Criterion used to choose which PCs to retain. See select_pcs
plot_sample	Plot sample to check data. See plotAllSpecimens
auto_rotate	Landmark templates are sometimes no longer upright after Procrustes-alignment. Auto-rotate uses rotate.coords to guess which type of rotation is required
quiet	Set to FALSE to suppress short summary of loaded data in console

Value

Returns a list of the following components:

aligned	Three-dimensional array containing Procrustes-aligned data
average	Coordinates of sample average for plotting
pc_info	List of selected PCs (including their SD, variance explained and cumulative variance explained), number of selected PCs, criterion used to select PCs
pc_scores	Principal component scores
pc_plot	PCs for plotting. Will by default create list of coordinates for all selected PCs at +/- 3SDs. To create plots of other PCs or at different level of SD, please see make_pcs or plot_2dpcs
summary	Short summary of key descriptives

Examples

################
### 2-D DATA ###
################
path_to_tem <- system.file("extdata", "tem", package="facefuns")
data2d <- read_lmdata(lmdata = path_to_tem)

shapedata2d <- facefuns(data = data2d,
                        pc_criterion = "broken_stick")

# REMOVING POINTS
# You can also remove points from your landmark templates prior to analyses
shapedata2d <- facefuns(data = data2d,
                        remove_points = c("left_eye", "right_eye", "nose", "mouth"))

shapedata2d <- facefuns(data = data2d,
                        remove_points = c(115:124, 145:157, 183:184) + 1)

shapedata2d <- facefuns(data = data2d,
                        remove_points = "frlgmm")

# PLOT AlIGNED TEMPLATES
shapedata2d$summary$plot_sample() #or geomorph::plotAllSpecimens(shapedata2d$aligned)

# PLOT PCS
plot_2dpcs(shapedata2d,
           which_pcs = 1:2)

# To plot PCs at different levels of SD:
pca <- geomorph::gm.prcomp(shapedata2d$aligned)

plot_2dpcs(pca,
           ref = shapedata2d$average,
           which_pcs = 1:2,
           vis_sd = 5)

# To save PC plots
## Not run: 
plot_2dpcs(shapedata2d,
           which_pcs = 1:2,
           output = "plotpcs.pdf")

## End(Not run)

################
### 3-D DATA ###
################
path_to_ply <- system.file("extdata", "ply", package="facefuns")

data3d <- read_vertices(path_to_ply)

shapedata3d <- facefuns(data = data3d,
                        pc_criterion = "broken_stick")

iholzleitner/facefuns documentation built on March 19, 2021, 2:43 p.m.