plotRefToTarget: Plot shape differences between a reference and target specimen

Description

Function plots shape differences between a reference and target specimen

Usage

plotRefToTarget(
  M1,
  M2,
  mesh = NULL,
  outline = NULL,
  method = c("TPS", "vector", "points", "surface"),
  mag = 1,
  links = NULL,
  label = FALSE,
  axes = FALSE,
  gridPars = NULL,
  useRefPts = FALSE,
  ...
)

Value

If using method="surface", function will return the warped mesh3d object.

Arguments

M1: Matrix of landmark coordinates for the first (reference) specimen
M2: Matrix of landmark coordinates for the second (target) specimen
mesh: A mesh3d object for use with method="surface"
outline: An x,y curve or curves warped to the reference (2D only)
method: Method used to visualize shape difference; see below for details
mag: The desired magnification to be used when visualizing the shape difference (e.g., mag=2)
links: An optional matrix defining for links between landmarks
label: A logical value indicating whether landmark numbers will be plotted
axes: A logical value indicating whether the box and axes should be plotted (points and vector only)
gridPars: An optional object made by gridPar
useRefPts: An option (logical value) to use reference configuration points rather than target configuration points (when method = "TPS")
...: Additional parameters not covered by gridPar to be passed to plot, plot3d or shade3d

Author

Dean Adams, Emma Sherratt, Antigoni Kaliontzopoulou & Michael Collyer

Details

The function generates a plot of the shape differences of a target specimen relative to a reference specimen. The option mag allows the user to indicates the degree of magnification to be used when displaying the shape difference. The function will plot either two- or three-dimensional data.

For two-dimensional data and thin-plate spline deformation plots, the user may also supply boundary curves of the object, which will be deformed from the reference to the target specimen using the thin-plate spline. Such curves are often useful in describing the biological shape differences expressed in the landmark coordinates. Note that to utilize this option, a boundary curve from a representative specimen must first be warped to the reference specimen using warpRefOutline.

Additionally, if a matrix of links is provided, the landmarks will be connected by lines. The link matrix is an M x 2 matrix, where M is the desired number of links. Each row of the link matrix designates the two landmarks to be connected by that link.

Four distinct methods for plots are available:

TPS a thin-plate spline deformation grid is generated. For 3D data, this method will generate thin-plate spline deformations in the x-y and x-z planes.
vector: a plot showing the vector displacements between corresponding landmarks in the reference and target specimen is shown.
points a plot is displayed with the landmarks in the target overlaying those of the reference.
surface a mesh3d surface is warped using thin-plate spline (for 3D data only). Requires mesh3d object in option mesh, made using warpRefMesh.

This function combines numerous plotting functions found in Claude (2008).

References

Claude, J. 2008. Morphometrics with R. Springer, New York.

Examples

Run this code

# Not Run
# Two dimensional data
# data(plethodon) 
# Y.gpa<-gpagen(plethodon$land)    #GPA-alignment
# ref<-mshape(Y.gpa$coords)
# plotRefToTarget(ref,Y.gpa$coords[,,39])
# plotRefToTarget(ref,Y.gpa$coords[,,39], mag=2, outline=plethodon$outline)   
#magnify by 2X
# plotRefToTarget(ref,Y.gpa$coords[,,39], method="vector", mag=3)
# plotRefToTarget(ref,Y.gpa$coords[,,39], method="points", 
# outline=plethodon$outline)
# plotRefToTarget(ref,Y.gpa$coords[,,39], method="vector", 
# outline=plethodon$outline, mag=2.5)
# plotRefToTarget(ref,Y.gpa$coords[,,39], 
# gridPars=gridPar(pt.bg = "green", pt.size = 1),
# method="vector",mag=3)

# Three dimensional data
# data(scallops)
# Y.gpa<-gpagen(A=scallops$coorddata, curves=scallops$curvslide, 
# surfaces=scallops$surfslide)
# ref<-mshape(Y.gpa$coords)
# plotRefToTarget(ref,Y.gpa$coords[,,1],method="points")
# scallinks <- matrix(c(1,rep(2:16, each=2),1), nrow=16, byrow=TRUE)
# plotRefToTarget(ref,Y.gpa$coords[,,1],
# gridPars=gridPar(tar.pt.bg = "blue", tar.link.col="blue",
# tar.link.lwd=2), method="points", links = scallinks)

Run the code above in your browser using DataLab