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

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")

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")
#> All landmarks were used in analyses.
#> The loaded data set contains 102 specimen, delineated with 189 2-D landmarks.
#> The broken_stick criterion was used to select 8 principal components.
#> Templates were rotated using "rotateC" after the GPA.

# 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"))
#> You removed 93 landmarks prior to analyses.
#> The loaded data set contains 102 specimen, delineated with 96 2-D landmarks.
#> The broken_stick criterion was used to select 9 principal components.
#> Templates were rotated using "rotateC" after the GPA.

shapedata2d <- facefuns(data = data2d,
                        remove_points = c(115:124, 145:157, 183:184) + 1)
#> You removed 25 landmarks prior to analyses.
#> The loaded data set contains 102 specimen, delineated with 164 2-D landmarks.
#> The broken_stick criterion was used to select 8 principal components.
#> Templates were rotated using "rotateC" after the GPA.

shapedata2d <- facefuns(data = data2d,
                        remove_points = "frlgmm")
#> You removed 57 landmarks prior to analyses.
#> The loaded data set contains 102 specimen, delineated with 132 2-D landmarks.
#> The broken_stick criterion was used to select 8 principal components.
#> Templates were rotated using "rotateC" after the GPA.

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

# PLOT PCS
plot_2dpcs(shapedata2d,
           which_pcs = 1:2)
#> [1] "/var/folders/lh/555rbl4x0yvbf8n6w709q7kh0000gn/T//Rtmpouu1D0/fileeac6f0e1b0f.png"
#> attr(,"class")
#> [1] "knit_image_paths" "knit_asis"       

# 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)
#> [1] "/var/folders/lh/555rbl4x0yvbf8n6w709q7kh0000gn/T//Rtmpouu1D0/fileeac712aebf.png"
#> attr(,"class")
#> [1] "knit_image_paths" "knit_asis"       

# To save PC plots
if (FALSE) {
plot_2dpcs(shapedata2d,
           which_pcs = 1:2,
           output = "plotpcs.pdf")
}

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

data3d <- read_vertices(path_to_ply)
#> Registered S3 method overwritten by 'Morpho':
#>   method         from
#>   print.classify RRPP

shapedata3d <- facefuns(data = data3d,
                        pc_criterion = "broken_stick")
#> The loaded data set contains 12 specimen, containing 30204 vertices.
#> The broken_stick criterion was used to select 2 principal components.