Summary: This module performs Generalized Procrustes Analysis (GPA) with or without scaling shape configurations to unit size, conducts principal component analysis (PCA) of GPA aligned shape coordinates, provides graphical output of GPA results and real-time 3D visualization of PC warps either using the landmarks of mean shape, or using a reference model that is transformed into the mean shape. Visualization of 3D shape deformation of the reference model can be exported as video clips. The input into the module is a folder path containing a number of landmark files stored in Slicer’s fcsv format and optionally a 3D model and accompanying set of landmarks to be used as reference model in 3D visualization of PCA results. Aesthetics (label shape, text size etc) of the morphospace plots (aka PC scatter plot) can be further customized using the Plots module of Slicer.

This section of the module runs the GPA and PCA analysis on a directory of landmark files. For data sets with a large number of landmarks, please expect running this step to take several minutes.

• Select Landmark Files: Use file dialog box to highlight and select samples to be included in the analysis. The files can be .fcsv or .mrk.json format. There should be one file per subject. Filenames are used as subject IDs in analysis. Selected files will be displayed in the table below the View Selected Files.

• Output directory prefix: Use the output directory field to select the directory where the results will be written. Each time the GPA module is run, a new timestamped results folder is created in this directory to prevent results from being overwritten. Please ensure that you have write access to the specified directory. Output folder will contain a log file that lists the files and the settings used in the analysis. This file can be parsed by convenience function log_parser.R for further analysis in R.

• Exclude landmarks: Optionally, landmarks can be excluded from analysis. Please enter the number of each landmark to exclude, separated by commas (example: 25,27,29). If all landmarks will be used, this field can be left empty.

• Skip Scaling: Option to skip the scaling step in the GPA. Useful to keep the physical scale of the data.

• Execute GPA + PCA: Initiates the GPA and also calculates the major axis of shape variaiton using PCA decomposition. PCA may take up to few minutes for large datasets.

• View Output Folder: Pops up a file browser and shows the contents of specified output folder.

As an alternative to running the GPA and PCA analysis, the module can be used to browse and visulize the results from a previous run of the module.

• Results directory: Use the directory selector to choose the output results folder generated by a previous run of the GPA module. This folder name will include a timestamp documenting the date/time of the analysis.

This section provides options for quickly and easily interacting with the display of the Procrustes mean shape without leaving the GPA module. If there is a warped display of the mean shape in the second 3D viewer, it will also control the display properties for this model. If a more customized display is needed, more display properties are available in the Markups module.

• Mean shape visibility: Toggle the visibility of the mean shape landmark points.

• Mean point label visibility: Toggle the visibility of the mean shape landmark names.

• Mean shape color: Select a new color for the mean shape landmark points.

• Mean shape glyph scale: Adjust the scale of the mean shape landmark points.

This section creates a visualization of the Procrustes distance variance at each point in mean shape, displayed in the 3D viewer. The visualizations are scaled by the size of the mean shape for visibility, and should be used assess relative, rather than absolute variance. Each landmark point is assigned a unique, randomlu assigned color that is not associated with the magnitude of variance.

• Ellipse type: The variance is plotted as an ellipse at each point with the radius in each dimension corresponding to the amount of variance along that axis.

• Sphere type: The variance is plotted as a sphere at each point with a radius dertermined by the average variance across three dimensions.

• Point cloud: Plots GPA aligned landmark coordinates for the entire data set as a point cloud.

This section creates a 2D scatter plot of two selected principal component scores in the Plot Viewer. The menu options are used to select the principal components on each axis, or optionally group subjects using factor data.

• X Axis: Select the PC on the X-axis.

• Y Axis: Select the PC on the Y-axis.

• Factor name: Input the title of the factor to be added. Click Add factor data to display a table with the factor added as a column header. Input the factor data under this header.

• Select factor: To group subjects in the PC scatter plot using the input factor data, select a factor from the dropdown menu. Each factor grouping will be displayed in the PC scatter plot with a unique, random color.

This section creates a visualization of the eigenvectors associated with each principal component in the 3D viewer. This vector indicates how the mean shape will change along the positive values of the selected PC. Between one and three PC vectors can be displayed simultaneously.

• Vector one: red Select the first PC, which will be displayed in red.

• Vector two: green Optionally select an additional PC that will be displayed in green.

• Vector three: blue Optionally select an additional PC that will be displayed in blue.

• Lollipop 2D projection Option to project the vector visualization from the 3D viewer to a 2D view.

This section sets up an interactive visualization demonstrating how selected principal components impact the mean shape. The visualization can be shown using only the Procrustes mean shape calculated in the first step of the GPA module, which requires no additional data. Alternatively, the impact of each PC can be shown on a reference model. This option requires a representative 3D model with and a corresponding landmark file. When the interactive visualization has been set up, a the mean shape or reference model that will be warped by the PCs is displayed in the second 3D viewer.

• Mean shape visualization This option selects the default visualization, which displays the impact of the PCs on the mean shape landmarks only.

• 3D model visualization This option will set up the interactive visualization using a sample mesh to show the impact of the PCs, if a model and corresponding landmark file are loaded.

• Specify reference model If the 3D model visualization option was chosen, this field is used to select the model. Supported model filetypes include: .ply, .stl, .obj, .vtk, .vtp, .orig, .g, and .byu.

• Specify landmark set for selected model If the 3D model visualization option was chosen, this field is used to select the .fcsv file containing the model's corresponding landmarks.

This section allows the user to visualize the influence of select principal components on the mean shape landmarks or reference model displayed the second 3D viewer. The original mean shape or model remains in the first 3D viewer for comparison. The PC selectors allow up to two PCs to be selected and their influence to be modulated in both the positive and negative direction interactively using the slider bars.

• PC Selector One Select the first principal component and scaling factor.

• PC Selector Two Optionally select the second principal component and scaling factor.

This section allows the user to capture a PC deformation as an animation. The animation created can be exported using the Screen Capture module, which supports several video export formats, including mp4.

• Start recording Begins recording the warping applied to the mean shape landmarks or reference model.

• Stop recording Ends recording the warping applied to the mean shape landamrks or reference model.

As implemented, GPA module does not allow sliding of the semi or pseudoLMs during superimposition. If sliding is required, we advise using the R/geomorph package for GPA superimposition.

For more information how to use the module, please see:

1. GPA Basics
2. GPA Exploring morphospaces
3. GPA Exporing Data to R

There are also video tutorials available. Note that while the UI might be slightly different, the functionality is the same:

1. Basics of GPA
2. Visualizing shape deformation with a reference model:
3. Recording shape deformations as an animation: