Type: Package
Title: 3D Morphological Analyses with 'RRphylo'
Date: 2025-05-07
Version: 0.0.1
Maintainer: Silvia Castiglione <silvia.castiglione@unina.it>
Description: Combined with 'RRphylo', this package provides a powerful tool to analyse and visualise 3d models (surfaces and meshes) in a phylogenetically explicit context (Melchionna et al., 2024 <doi:10.1038/s42003-024-06710-8>).
License: GPL-2
Encoding: UTF-8
Depends: R (≥ 3.6.0)
Imports: Morpho, rgl, Rvcg, RRphylo
Suggests: inflection, ddpcr, ape, knitr, rmarkdown
RoxygenNote: 7.3.2
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-05-12 16:54:02 UTC; Silvia
Author: Marina Melchionna [aut], Silvia Castiglione [aut, cre], Carmela Serio [aut], Giorgia Girardi [aut], Alessandro Mondanaro [aut], Pasquale Raia [aut]
Repository: CRAN
Date/Publication: 2025-05-14 08:30:06 UTC

Color a mesh according to provided values

Description

The function colors a mesh according to a vector of continuous values related to individual vertices.

Usage

col2mesh(mesh,values,pal,from=NULL,to=NULL,NAcol="gray90")

Arguments

mesh

a mesh3d object.

values

a vector of continuous values associated to individual vertices of the mesh.

pal

a vector of colors to be passed to colorRampPalette.

from, to

lower and upper values to be associated to the ends of pal.

NAcol

the color associated to NA values.

Value

A mesh3d object colored according to values.

Author(s)

Marina Melchionna, Silvia Castiglione

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(rgl)
  require(Morpho)
  require(Rvcg)

  pca<-procSym(endo.set)
  ldm<-endo.set[,,"Homo_sapiens"]
  sur<-endo.sur[["Homo_sapiens"]]

  rec<- vcgBallPivoting(pca$mshape, radius = 0)
  rec$vb[1:3,]<-t(ldm)
  val<-rnorm(ncol(rec$vb))

  interp<-interpolMesh(sur = rec,refsur = sur,refmat = ldm,
                       values = val,element ="vertices",k = 4)

  colmesh<-col2mesh(mesh = sur,values = interp,pal = heat.colors(5))
  plotLegend(mesh = colmesh,values = interp, main = "Pan troglodytes")
  open3d()
  shade3d(colmesh,specular="black")

Mapping morphological convergence on 3D surfaces

Description

Given vectors of RW (or PC) scores for some converging species, the function selects the RW (PC) axes which best account for convergence and maps convergent areas on the corresponding 3D surfaces.

Usage

conv.map(x1,x2=NULL,scores, pcs, mshape,focal=NULL,mshape_sur=NULL,
  refmat = NULL,refsur = NULL, k = 4, exclude = NULL, out.rem = TRUE, plot =
  TRUE, col = "blue", NAcol = "gray", names = TRUE, nsim = 1000)

Arguments

x1, x2

vectors of convergent species. When convergence within a single clade was found, x1 represents the vector of species belonging to the clade (x2=NULL). When convergence between groups/clades was found, x1 and x2 are the two convergent groups/clades.

scores

data frame (or matrix) with the RW (or PC) scores returned by RWA/PCA. Species not included in x1 or x2 are ignored.

pcs

RW (or PC) vectors (eigenvectors of the covariance matrix) returned by RWA/PCA.

mshape

the consensus configuration.

focal

vector of species included in x1/x2 to be plotted. To be provided if refsur=NULL and refmat=NULL.

mshape_sur

a mesh3d object used as a reference for mesh reconstruction. The vertices of mshape_sur must be the consensus configuration. If NULL, it is automatically generated by applying vcgBallPivoting on mshape.

refmat

a named list of landmark sets corresponding to refsur.

refsur

a named list of mesh3d objects for species in x1/x2 to be plotted. If focal is not NULL this is ignored.

k

the argument k passed to interpolMesh.

exclude

integer: the index numbers of the RWs (or PCs) to be excluded from the comparison.

out.rem

logical: if TRUE triangles with outlying area difference are removed.

plot

logical: if TRUE, the pairwise comparisons are plotted. For more than 5 pairwise comparisons, the plot is not shown.

col

character: the color for plotting.

NAcol

the argument NAcol passed to col2mesh.

names

logical: if TRUE, the names of the groups or species are displayed in the 3d plot.

nsim

the number of iterations to evaluate significance.

Details

After selecting the RW (PC) axes which best account for convergence, conv.map uses such axes (and related scores) within restoreShapes (Morpho) to reconstruct landmark matrices for each convergent species (in x1/x2). The reconstruction of species 3d surfaces is based on mshape_sur, either provided by the user or generated within the function. Finally, the area differences between corresponding triangles of reconstructed 3d meshes for each possible pair of convergent species are calculated. In the calculation of differences, the possibility to find and remove outliers is supplied (out.rem=TRUE, we suggest considering this possibility if the mesh may contain degenerate facets).

If the combination of focal species (or species within refsur/refmat) contains a number equal or lower then 5 items, conv.map returns a rgl plot mapping the convergence on the 3D models. If lists of refsur/refmat are not provided, the area differences are plotted onto reconstructed surfaces. If refsur/refmat are available, difference values are interpolated by means of interpolMesh to be plotted onto real surfaces. When species in either x1 or x2 are missing from focal or refmat/refsur, conv.map plots the reconstructed surface of the species having the smallest $selected angle with the focal (see angle.compare in the description of outputs).

conv.map further gives the opportunity to exclude some RW (or PC) axes from the analysis because, for example, in most cases the first axes are mainly related to high-order morphological differences driven by phylogeny and size variations.

Value

The function returns a list including:

Author(s)

Marina Melchionna, Antonio Profico, Silvia Castiglione, Carmela Serio, Gabriele Sansalone, Pasquale Raia

References

Schlager, S. (2017). Morpho and Rvcg–Shape Analysis in R: R-Packages for geometric morphometrics, shape analysis and surface manipulations. In: Statistical shape and deformation analysis. Academic Press.

Melchionna, M., Profico, A., Castiglione, S., Serio, C., Mondanaro, A., Modafferi, M., Tamagnini, D., Maiorano, L. , Raia, P., Witmer, L.M., Wroe, S., & Sansalone, G. (2021). A method for mapping morphological convergence on three-dimensional digital models: the case of the mammalian sabre-tooth. Palaeontology, 64, 573–584. doi:10.1111/pala.12542

See Also

search.conv vignette ; relWarps ; procSym

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(Morpho)

  pca<-procSym(endo.set)
  ldm_homo<-endo.set[,,"Homo_sapiens"]
  sur_homo<-endo.sur[["Homo_sapiens"]]
  ldm_macaca<-endo.set[,,"Macaca_fuscata"]
  sur_macaca<-endo.sur[["Macaca_fuscata"]]


  # Convergence within group plotted on reconstructed surfaces
  cm1<-conv.map(x1=c("Pan_troglodytes","Gorilla_gorilla","Pongo_abelii"),
                scores=pca$PCscores,pcs=pca$PCs,mshape=pca$mshape,
                focal=c("Pan_troglodytes","Gorilla_gorilla"))

  # Convergence between group plotted on reconstructed surfaces
  cm2<-conv.map(x1=c("Pongo_abelii"),x2=c("Alouatta_caraya"),
                scores=pca$PCscores,pcs=pca$PCs,mshape=pca$mshape,
                focal="Alouatta_caraya")

  # Convergence within group plotted on real surfaces
  cm3<-conv.map(x1=c("Homo_sapiens","Gorilla_gorilla","Pongo_abelii"),
                scores=pca$PCscores,pcs=pca$PCs,mshape=pca$mshape,
                refsur=list("Homo_sapiens"=sur_homo),
                refmat=list("Homo_sapiens"=ldm_homo))

  # Convergence between group plotted on real surfaces
  cm3<-conv.map(x1=c("Homo_sapiens","Pongo_abelii"),x2=c("Macaca_fuscata"),
                scores=pca$PCscores,pcs=pca$PCs,mshape=pca$mshape,
                refsur=list("Homo_sapiens"=sur_homo,"Macaca_fuscata"=sur_macaca),
                refmat=list("Homo_sapiens"=ldm_homo,"Macaca_fuscata"=ldm_macaca))

Interpolate values on a 3d mesh

Description

The function takes a reconstructed mesh3d object (sur) with some related values (to either triangles or vertices of the mesh) and transfers such values to the real mesh (refsur) from which sur was derived.

Usage

interpolMesh(sur,values,refsur,refmat,element=c("triangles","vertices"),k=4)

Arguments

sur

a reconstructed mesh3d object with vertices matching to refmat.

values

the vector of values related to sur to be interpolated. values can be related to either triangles or vertices (see element).

refsur

the reference mesh (mesh3d object) to interpolate the values on.

refmat

the landmark set related to refsur.

element

one of "triangles" or "vertices", depending on which of them values is related to.

k

the number of nearest neighbor vertices used for interpolation (see details).

Details

The function starts by locating a set of points (NNps) on refsur, each being the single nearest neighbor for each vertex of sur (or barycenter if element="triangles"). Then, interpolation is performed by identifying the k points among NNps being the closest to each vertex of refsur and computing the mean of their values weighted by their distance.

Value

The vector of values related to each vertex of refsur.

Author(s)

Marina Melchionna, Silvia Castiglione

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(rgl)
  require(Morpho)
  require(Rvcg)

  pca<-procSym(endo.set)
  ldm<-endo.set[,,"Homo_sapiens"]
  sur<-endo.sur[["Homo_sapiens"]]

  rec<- vcgBallPivoting(pca$mshape, radius = 0)
  rec$vb[1:3,]<-t(ldm)
  val1<-rnorm(ncol(rec$vb))

  # Interpolate values associated to vertices
  val1<-rnorm(ncol(rec$vb))
  interp1<-interpolMesh(sur = rec,refsur = sur,refmat = ldm,
                        values = val1,element ="vertices",k = 4)

  colmesh1<-col2mesh(mesh = sur,values = interp1,pal = heat.colors(5))
  open3d()
  shade3d(colmesh1,specular="black")


  # Interpolate values associated to triangles
  val2<-rnorm(ncol(rec$it))
  interp2<-interpolMesh(sur = rec,refsur = sur,refmat = ldm,
                        values = val2,element ="triangles",k = 4)

  colmesh2<-col2mesh(mesh = sur,values = interp2,pal = heat.colors(5))
  open3d()
  shade3d(colmesh2,specular="black")

Plot legend for colored mesh.

Description

Assuming a mesh is colored according to a vector of values, the function takes the color sequence from the mesh and plots it associated to values.

Usage

plotLegend(mesh,values,main)

Arguments

mesh

a mesh3d object

values

a vector of continuous values associated to individual vertices of the mesh.

main

plot title.

Value

A plot of the color sequence associated to values on the mesh.

Author(s)

Marina Melchionna, Silvia Castiglione

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(rgl)
  require(Morpho)
  require(Rvcg)

  pca<-procSym(endo.set)
  ldm<-endo.set[,,"Homo_sapiens"]
  sur<-endo.sur[["Homo_sapiens"]]

  rec<- vcgBallPivoting(pca$mshape, radius = 0)
  rec$vb[1:3,]<-t(ldm)
  val<-rnorm(ncol(rec$vb))

  interp<-interpolMesh(sur = rec,refsur = sur,refmat = ldm,
                       values = val,element ="vertices",k = 4)

  colmesh<-col2mesh(mesh = sur,values = interp,pal = heat.colors(5))
  plotLegend(mesh = colmesh,values = interp, main = "Pan troglodytes")
  open3d()
  shade3d(colmesh,specular="black")

Plot landmarks importance on 3d mesh

Description

The function relates PCA loadings of a single PC axis to individual landmarks and plots them on a 3d mesh by means of interpolation.

Usage

plotland(pca,sel=1,refsur=NULL,refmat=NULL,k=5,pal=NULL,
  defo=FALSE,radius=0.001)

Arguments

pca

the result of a relative warp analysis. Classes relwarps and nosymproc are supported.

sel

numeric indicating the focal RW/PC axis.

refsur

the mesh3d object to plot on. If NULL, the mesh is reconstructed by means of vcgBallPivoting from the consensus configuration derived from pca.

refmat

the landmark set related to refsur. If NULL, the consensus configuration derived from pca is used.

k

the argument k passed to interpolMesh.

pal

a vector of colors to be passed to colorRampPalette.

defo

when refsur and refmat are provided, defo = TRUE warps refsur on the consensus shape.

radius

argument radius passed to spheres3d

Value

A list including a mesh3d object colored according to landmarks importance and a matrix of landmarks importance on each RW/PC axis. Additionally, the function returns a 3d plot of the mesh.

Author(s)

Marina Melchionna, Silvia Castiglione, Carmela Serio, Giorgia Girardi

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(rgl)
  require(Morpho)

  pca<-procSym(endo.set)
  ldm<-endo.set[,,"Homo_sapiens"]
  sur<-endo.sur[["Homo_sapiens"]]

  plotland(pca=pca,sel=1,refsur = sur,refmat = ldm)

Mapping rate and direction of phenotypic change on 3D surfaces.

Description

Given vectors of RW (or PC) scores, the function selects the RW (PC) axes linked to highest (and lowest) evolutionary rate values and reconstructs the morphology weighted on them. In this way, rate.map shows where and how the phenotype changed the most between any pair of taxa.

Usage

rate.map(x, RR, scores, pcs, mshape, mshape_sur=NULL,refsur=NULL,
  refmat=NULL, k=4,out.rem = TRUE, plot=TRUE, pal=NULL,
  NAcol="gray90",from=NULL, to=NULL,show.names=TRUE)

Arguments

x

the species/nodes to be compared; it can be a single species, or a vector containing two species or a species and any of its parental nodes.

RR

an object generated by using the RRphylo function.

scores

RW or PC scores.

pcs

RW (or PC) vectors (eigenvectors of the covariance matrix) returned by RWA/PCA.

mshape

the consensus configuration.

mshape_sur

a mesh3d object used as a reference for mesh reconstruction. The vertices of mshape_sur must be the consensus configuration. If NULL, it is automatically generated by applying vcgBallPivoting on mshape.

refsur

a list of mesh3d to be provided for all species in x.

refmat

a list of landmark sets to be provided for all species in x.

k

the argument k passed to interpolMesh.

out.rem

logical: if TRUE mesh triangles with outlying area difference are removed.

plot

logical indicating if the 3d plot must be shown.

pal

a vector of colors to be passed to colorRampPalette.

NAcol

the argument NAcol passed to col2mesh.

from, to

lower and upper limits to be associated to the ends of pal.

show.names

logical: if TRUE, the names of the species are displayed in the 3d plot.

Details

After selecting the RW (PC) axes, rate.map automatically builds a 3D mesh on the mean shape calculated from the Relative Warp Analysis (RWA) or Principal Component Analysis (PCA) (Schlager 2017) by applying the function vcgBallPivoting (Rvcg). The reconstruction of species 3d surfaces is based on mshape_sur, either provided by the user or generated within the function. Finally, for each species in x, the function computes the area differences between corresponding triangles of its reconstructed 3D mesh and the surface of the ancestor (most recent common ancestor in the case of two species in x). In the calculation of differences, the possibility to find and remove outliers is supplied (out.rem=TRUE, we suggest considering this possibility if the mesh may contain degenerate facets).

Finally, rate.map returns a 3D plot showing such comparisons displayed on shape of the ancestor/mrca used as the reference. The color gradient goes from blue to red, where blue areas represent expansion of the mesh, while the red areas represent contraction of the mesh triangles. If a list refsur (and refmat) is provided, convergence is plotted onto them (see interpolMesh for further details).

Value

The function returns a list including:

Author(s)

Marina Melchionna, Antonio Profico, Silvia Castiglione, Gabriele Sansalone, Pasquale Raia

References

Schlager, S. (2017). Morpho and Rvcg-Shape Analysis in R: R-Packages for geometric morphometrics, shape analysis and surface manipulations. In: Statistical shape and deformation analysis. Academic Press.

Castiglione, S., Melchionna, M., Profico, A., Sansalone, G., Modafferi, M., Mondanaro, A., Wroe, S., Piras, P., & Raia, P. (2021). Human face-off: a new method for mapping evolutionary rates on three-dimensional digital models. Palaeontology, 65, 1. doi:10.1111/pala.12582

Melchionna, M., Castiglione, S., Girardi, G., Serio, C., Esposito, A., Mondanaro, A., Profico, A., Sansalone, G., & Raia, P. (2024). RRmorph—a new R packageto map phenotypic evolutionary rates and patterns on 3D meshes. Communications Biology, 7, 1009.

See Also

RRphylo vignette ; relWarps ; procSym

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(Morpho)
  require(Rvcg)

  pca<-procSym(endo.set)
  ldm_homo<-endo.set[,,"Homo_sapiens"]
  sur_homo<-endo.sur[["Homo_sapiens"]]
  ldm_macaca<-endo.set[,,"Macaca_fuscata"]
  sur_macaca<-endo.sur[["Macaca_fuscata"]]

  cc<- 2/parallel::detectCores()
  RR<-RRphylo::RRphylo(tree.prima,pca$PCscores,clus=cc)

  # plotting on reconstructed surfaces
  Rmap1<-rate.map(x=c("Homo_sapiens","Macaca_fuscata"),RR=RR, scores=pca$PCscores,
                  pcs=pca$PCs, mshape=pca$mshape)

  # plotting on real surfaces
  Rmap2<-rate.map(x=c("Homo_sapiens","Macaca_fuscata"),RR=RR, scores=pca$PCscores,
                  pcs=pca$PCs, mshape=pca$mshape,
                  refsur=list("Homo_sapiens"=sur_homo,"Macaca_fuscata"=sur_macaca),
                  refmat=list("Homo_sapiens"=ldm_homo,"Macaca_fuscata"=ldm_macaca))

Shape difference between 3d meshes

Description

The function reconstructs two specimens' meshes (x) by using their superimposed configurations (from within pca), calculates the shape difference between them, and plots such differences on provided meshes (refsur).

Usage

shapeDiff(x,pca,refsur,refmat,mshape_sur = NULL,
  pal=NULL,NAcol="gray90",show.names=TRUE)

Arguments

x

a vector of specimens pair.

pca

the result of a relative warp analysis. Classes relwarps and nosymproc are both accepted.

refsur

a list of two mesh3d objects to be provided in the same order as x.

refmat

a list of two landmark sets related to refsur to be provided in the same order as x.

mshape_sur

a mesh3d object used as a reference for mesh reconstruction. The vertices of mshape_sur must be the consensus configuration. If NULL, it is automatically generated by applying vcgBallPivoting on the consensus configuration derived from pca.

pal

a vector of colors to be passed to colorRampPalette.

NAcol

the color associated to refsur vertices falling outside the range of refmat (not involved in interpolation).

show.names

logical: if TRUE, the names of the specimens as in x are displayed in the 3d plot.

Value

Two mesh3d objects colored according to shape differences. Additionally, the function returns 3d plots of the meshes.

Author(s)

Marina Melchionna, Silvia Castiglione

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(Morpho)

  pca<-procSym(endo.set)
  ldm_homo<-endo.set[,,"Homo_sapiens"]
  sur_homo<-endo.sur[["Homo_sapiens"]]
  ldm_macaca<-endo.set[,,"Macaca_fuscata"]
  sur_macaca<-endo.sur[["Macaca_fuscata"]]

  diffs<-RRmorph::shapeDiff(x=c("Homo_sapiens","Macaca_fuscata"),
                   pca = pca,refsur = list(sur_homo,sur_macaca),
                   refmat = list(ldm_homo,ldm_macaca))

Triangles to vertices

Description

The function transfers values associated to triangles of a mesh3d object to its vertices.

Usage

tri2verts(mesh,values)

Arguments

mesh

a mesh3d object.

values

a vector of continuous values associated to individual triangles of the mesh.

Value

A vector of continuous values associated to individual vertices of the mesh.

Author(s)

Marina Melchionna, Silvia Castiglione

Examples

  
  da<-"https://github.com/pasraia/RRmorph_example_data/raw/refs/heads/main/RRmorphdata.rda"
  download.file(url=da,destfile = paste0(tempdir(),"/RRmorphdata.rda"))
  load(paste0(tempdir(),"/RRmorphdata.rda"))

  require(Morpho)
  require(Rvcg)

  pca<-procSym(endo.set)
  ldm<-endo.set[,,"Homo_sapiens"]
  sur<-endo.sur[["Homo_sapiens"]]

  rec<- vcgBallPivoting(pca$mshape, radius = 0)
  rec$vb[1:3,]<-t(ldm)
  val<-rnorm(ncol(rec$vb))

  vertval<-tri2verts(rec,val)