Package 'RRphylo'

Description

RRphylo provides tools for phylogenetic comparative analysis. The main functions allow estimation of phenotypic evolutionary rates, identification of shifts in rate of evolution, quantification of direction and size of evolutionary change of multivariate traits, and computation of species ontogenetic vectors. Additionally, there are functions for simulating phenotypic data, manipulating phylogenetic trees, and retrieving information from phylogenies. Finally, there are functions to plot and test rate shifts at particular nodes.

The complete list of functions can be displayed with library(help = RRphylo). Citations to individual functions are available by typing citation("RRphylo").

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Description

This function computes and compares ontogenetic vectors among species in a tree.

Usage

angle.matrix(RR,node,Y=NULL,select.axes=c("no","yes"),
  type=c("phenotypes","rates"),cova=NULL,clus=0.5)

Arguments

Details

The angle.matrix function takes as objects a phylogenetic tree (retrieved directly from an RRphylo object), including the different ontogenetic stages of each species as polytomies. Names at tips must be written as species ID and stage number separated by the underscore. The RR object angle.matrix is fed with is just used to extract the dichotomized version of the phylogeny. This is necessary because node numbers change randomly at dichotomizing non-binary trees. However, when performing angle.matrix with the covariate the RR object must be produced without accounting for the covariate. Furthermore, as the covariate only affects the rates computation, it makes no sense to use it when computing vectors for phenotypic variables. Once angles and vectors are computed, angle.matrix performs two tests by means of standard major axis (SMA) regression. For each species pair, the "biogenetic test" verifies whether the angle between species grows during development, meaning that the two species becomes less similar to each other during growth. The "paedomorphosis test" tells whether there is heterochronic shape change in the data. Under paedomorphosis, the adult stages of one (paedomorphic) species will resemble the juvenile stages of the other (peramorphic) species. The test regresses the angles formed by the shapes at different ontogenetic stages of a species to the shape at the youngest stage of the other in the pair, against age. Then, it tests whether the two regression lines (one per species) have different slopes, and whether they have different signs. If the regression lines point to different directions, it means that one of the two species in the pair resembles, with age, the juveniles of the other, indicating paedomorphosis. Ontogenetic vectors of individual species are further computed, in reference to the MRCA of the pair, and to the first stage of each species (i.e. intraspecifically). Importantly, the size of the ontogenetic vectors of rates tell whether the two species differ in terms of developmental rate, which is crucial to understand which process is behind paedomorphosis, where it applies.While performing the analysis, the function prints messages on-screen informing about tests results. If select.axes = "yes", informs the user about which phenotypic variables are used. Secondly, it specifies whether ontogenetic vectors to MRCA, and intraspecific ontogenetic vectors significantly differ in angle or size between species pairs. Then, for each species pair, it indicates if the biogenetic law and paedomorphosis apply.

Value

A list containing 4 objects:

1. $regression.matrix a 'list' including 'angles between species' and 'angles between species to MRCA' matrices for all possible combinations of species pairs from the two sides descending from the MRCA. For each matrix, corresponding biogenetic and paedomorphosis tests are reported.

2. $angles.2.MRCA.and.vector.size a 'data.frame' including angles between the resultant vector of species and the MRCA and the size of the resultant vector computed from species to MRCA, per stage per species.

3. $ontogenetic.vectors2MRCA a 'data.frame' including angle, size, and corresponding x and y components, of ontogenetic vectors computed between each species and the MRCA. For both angle and size, the p-value for the difference between species pairs is reported.

4. $ontogenetic.vectors.to.1st.stage a 'list' containing:

   • $matrices: for all possible combinations of species pairs from the two sides descending form the MRCA, the upper triangle of the matrix contains the angles between different ontogenetic stages for the first species. The same applies to the lower triangle, but for the second species.

   • $vectors: for all possible combinations of species pairs from the two sides descending form the MRCA, angles and sizes of ontogenetic vectors computed to the first stage of each species. For both, the p-value for the difference between the species pair is reported.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

## Not run: 
  data("DataApes")
  DataApes$PCstage->PCstage
  DataApes$Tstage->Tstage
  DataApes$CentroidSize->CS
  cc<- 2/parallel::detectCores()

  RRphylo(tree=Tstage,y=PCstage,clus=cc)->RRstage
# Case 1. without accounting for the effect of a covariate

 # Case 1.1 selecting shape variables that show significant relationship with age
  # on phenotypic vectors
    angle.matrix(RRstage,node=72,Y=PCstage,select.axes="yes",type="phenotypes",clus=cc)->am1
  # on rates vectors
    angle.matrix(RRstage,node=72,Y=PCstage,select.axes="yes",type="rates",clus=cc)->am2

 # Case 1.2 using all shape variables
  # on phenotypic vectors
    angle.matrix(RRstage,node=72,Y=PCstage,select.axes="no",type="phenotypes",clus=cc)->am3
  # on rates vectors
    angle.matrix(RRstage,node=72,Y=PCstage,select.axes="no",type="rates",clus=cc)->am4


# Case 2. accounting for the effect of a covariate (on rates vectors only)

 # Case 2.1 selecting shape variables that show significant relationship with age
   angle.matrix(RRstage,node=72,Y=PCstage,select.axes="yes",type="rates", cova=CS,clus=cc)->am5


 # Case 2.2 using all shape variables
   angle.matrix(RRstage,node=72,Y=PCstage,select.axes="no",type="rates",cova=CS,clus=cc)->am6
  
## End(Not run)

Description

The function adds a color bar to the current plot.

Usage

colorbar(colors,x,y=NULL,direction="vertical",
  height=1,width=1,border="black",lwd=2,lty=1,
  labs=NULL,labs.pos=NULL,title=NULL,title.pos=NULL,
  ticks=TRUE,tck.pos=NULL,tck.length=1,xpd=FALSE,...)

Arguments

Author(s)

Silvia Castiglione

Examples

rainbow(30)->cols
replicate(4,paste(sample(letters,4),collapse=""))->labs

plot(rnorm(20),rnorm(20))
colorbar(cols,"topleft")

plot(rnorm(20),rnorm(20))
colorbar(cols,"topright",
         height=1.2,width=1.2,lwd=2,
         labs=labs,labs.pos="left",labs.cex=1.3,labs.adj=1,
         title="Colorbar!",title.cex=1.4,title.font=2,title.adj=c(0,0),
         tck.pos="out",tck.lwd=2,xpd=TRUE)

Description

The function compRates is an adaptation of search.shift which performs pairwise comparison of average absolute rates between clades via bootstrap.

Usage

compRates(RR,node, nrep = 1000, cov = NULL)

Arguments

Value

For each node pair, the function returns the average absolute rate difference (computed as the difference between the average absolute rate over all branches subtended by the nodes) and related significance level. Probabilities are derived by contrasting the rate differences to simulated ones derived by shuffling the rates across the tree branches for a number of replicates specified by the argument nrep. Note that the p-values refer to the number of times the real differences are larger (p-value>=0.975) or smaller (p-value<=0.025) than the simulated ones, divided by the number of simulations, hence the test should be considered as two-tailed. The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Giorgia Girardi

See Also

search.shift vignette

Examples

## Not run: 
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
DataOrnithodirans$statedino->statedino
cc<- 2/parallel::detectCores()

RRphylo(tree=treedino,y=massdino,clus=cc)->dinoRates
compRates(RR=dinoRates,node=c(696,746))->cr1
compRates(RR=dinoRates,node=c(696,746),cov=massdino)->cr2
    
## End(Not run)

Description

The function is deprecated, please check the new version of conv.map in package RRmorph.

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

Usage

conv.map(dataset,pcs,mshape,conv=NULL, exclude=NULL,out.rem=TRUE,
  show.consensus=FALSE, plot=TRUE,col="blue",names = TRUE)

Arguments

Details

conv.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). 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. conv.map finds and plots the strength of convergence on 3D surfaces. An output of conv.map (if the dataset contains a number equal or lower then 5 items) is an interactive plot mapping the convergence on the 3D models. In the upper triangle of the 3D multiple layouts the rows representing the reference models and the columns the target models. On the contrary, on the lower triangle the rows correspond to the target models and the columns the reference models. In the calculation of the differences of areas we supply the possibility to find and remove outliers from the vectors of areas calculated on the reference and target surfaces. We suggest considering this possibility if the mesh may contain degenerate facets.

Value

The function returns a list including:

• $angle.compare data frame including the real angles between the given shape vectors, the angles conv computed between vectors of the selected RWs (or PCs), the angles between vectors of the non-selected RWs (or PCs), the difference conv, and its p values.

• $selected.pcs RWs (or PCs) axes selected for convergence.

• $average.dist symmetric matrix of pairwise distances between 3D surfaces.

• $suface1 list of coloured surfaces, if two meshes are given, it represents convergence between mesh A and B charted on mesh A.

• $suface2 list of coloured surfaces, if two meshes are given, it represents convergence between mesh A and B charted on mesh B.

• $scale the value used to set the colour gradient, computed as the maximum of all differences between each surface and the mean shape.

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

## Not run: 
  data(DataSimians)
  DataSimians$pca->pcasim

  ## Case 1. Convergent species only
     dato1<-pcasim$PCscores[c(1,4),]

     CM1<-conv.map(dataset = dato1,
                 pcs = pcasim$PCs,
                 mshape = pcasim$mshape,
                 show.consensus = TRUE)

  ## Case 2. Convergent and non-convergent species
     dato2<-pcasim$PCscores[c(1,4,7),]
     conv<-c("conv","conv","noconv")
     names(conv)<-rownames(dato2)

     CM2<-conv.map(dataset = dato2,
                  pcs = pcasim$PCs,
                  mshape = pcasim$mshape,
                  conv = conv,
                  show.consensus = TRUE,
                  col = "orange")
  
## End(Not run)

Description

The function cuts all the branches of the phylogeny which are younger than a specific age or node (i.e. the age of the node).

Usage

cutPhylo(tree,age=NULL,node=NULL,keep.lineage=TRUE)

Arguments

Details

When an entire lineage is cut (i.e. one or more nodes along a path) and keep.lineages = TRUE, the leaves left are labeled as "l" followed by a number.

Value

The function returns the cut phylogeny and plots it into the graphic device. The time axis keeps the root age of the original tree. Note, tip labels are ordered according to their position in the tree.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

See Also

cutPhylo vignette

Examples

## Not run: 
library(ape)

set.seed(22)
rtree(100)->tree
3->age

cutPhylo(tree,age=age)->t1
cutPhylo(tree,age=age,keep.lineage=FALSE)->t1a
cutPhylo(tree,node=151)->t2
cutPhylo(tree,node=151,keep.lineage=FALSE)->t2a

## End(Not run)

Description

Geometric morphometrics shape data regarding Apes' facial skeleton and Apes phylogentic trees (Profico et al. 2017).

Usage

data(DataApes)

Format

A list containing:

$PCstage

A data frame containing 38 shape variables for Apes' facial skull at different ontogenetic stages

.

$PCadult

A data frame containing 3 shape variables for Apes' facial skull

.

$Tstage

Phylogenetic tree of Apes including the different ontogenetic stages of each species as polytomies

.

$Tadult

Phylogenetic tree of Apes

.

$CentroidSize

numeric vector of Centroid Size values of ‘PCstage’

.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Profico, A., Piras, P., Buzi, C., Di Vincenzo, F., Lattarini, F., Melchionna, M., Veneziano, A., Raia, P. & Manzi, G. (2017). The evolution of cranial base and face in Cercopithecoidea and Hominoidea: Modularity and morphological integration. American journal of primatology,79: e22721.

Description

Cetaceans' body and brain mass, and phylogenetic tree (Serio et al. 2019).

Usage

data(DataCetaceans)

Format

A list containing:

treecet

Cetaceans phylogenetic tree

.

masscet

numeric vector of cetaceans body masses (ln g)

.

brainmasscet

numeric vector of cetaceans brain masses (ln g)

.

aceMyst

body mass (ln g) for Mystacodon selenensis, used as node prior at the ancestor of the Mysticeti

.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Serio, C., Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Di Febbraro, M., & Raia, P. (2019). Macroevolution of Toothed Whales Exceptional Relative Brain Size. Evolutionary Biology, 46: 332-342. doi:10.1007/s11692-019-09485-7

Description

Geometric morphometrics shape data regarding felids' mandible and phylogentic tree (Piras et al., 2018).

Usage

data(DataFelids)

Format

A list containing:

$treefel

Phylogenetic tree of felids

.

$landfel

list of 2D landmark configuration for each species of the tree

.

$PCscoresfel

A data.frame containing 83 shape variables for felids' mandible

.

$statefel

sabertooth - not sabertooth ecomorph categorization for each species

.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Piras, P., Silvestro, D., Carotenuto, F., Castiglione, S., Kotsakis, A., Maiorino, L., Melchionna, M.,Mondanaro, A., Sansalone, G., Serio, C., Vero, V. A., & Raia, P. (2018). Evolution of the sabertooth mandible: A deadly ecomorphological specialization. Palaeogeography, Palaeoclimatology, Palaeoecology, 496, 166-174.

Description

Ornithodirans' body mass, phylogenetic tree and locomotory type (Castiglione et al 2018).

Usage

data(DataOrnithodirans)

Format

A list containing:

treedino

Ornithodirans phylogenetic tree

.

massdino

numeric vector of ornithodirans body masses

.

statedino

vector of ornithodirans locomotory type

.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P.(2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

Description

The output of Procrustes superimposition as performed by the function procSym on 9 simians faces and the phylogenetic tree for such species.

Usage

data(DataSimians)

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Description

Geometric morphometrics shape data regarding mandible and phylogentic tree of 'Ungulatomorpha' (Raia et al., 2010).

Usage

data(DataUng)

Format

A list containing:

$PCscoresung

A data frame containing 205 shape variables for mandible of 'Ungulatomorpha'

.

$treeung

Phylogenetic tree of 'Ungulatomorpha'

.

$stateung

vector of 'Ungulatomorpha' feeding type

.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Raia, P., Carotenuto, F., Meloro, C., Piras, P., & Pushkina, D. (2010). The shape of contention: adaptation, history, and contingency in ungulate mandibles. Evolution, 64: 1489-1503.

Description

The function computes the distance between pairs of nodes, pairs of tips, or between nodes and tips. The distance is meant as both patristic distance and the number of nodes intervening between the pair.

Usage

distNodes(tree,node=NULL,clus=0.5)

Arguments

Value

If node is specified, the function returns a data frame with distances between the focal node/tip and the other nodes/tips on the tree (or for the selected pair only). Otherwise, the function returns a matrix containing the number of nodes intervening between each pair of nodes and tips.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

data("DataApes")
DataApes$Tstage->Tstage

cc<- 2/parallel::detectCores()
distNodes(tree=Tstage,clus=cc)->dn1
distNodes(tree=Tstage,node=64,clus=cc)->dn2
distNodes(tree=Tstage,node="Tro_2",clus=cc)->dn3
distNodes(tree=Tstage,node=c(64,48),clus=cc)->dn4
distNodes(tree=Tstage,node=c(64,"Tro_2"),clus=cc)->dn5

Description

This function quantifies direction, size and rate of evolutionary change of multivariate traits along node-to-tip paths and between species.

Usage

evo.dir(RR,angle.dimension=c("rates","phenotypes"),
  y.type=c("original","RR"),y=NULL,pair.type=c("node","tips"),pair=NULL,
  node=NULL,random=c("yes","no"),nrep=100)

Arguments

Details

The way evo.dir computes vectors depends on whether phenotypes or rates are used as variables. RRphylo rates along a path are aligned along a chain of ancestor/descendant relationships. As such, each rate vector origin coincides to the tip of its ancestor, and the resultant of the path is given by vector addition. In contrast, phenotypic vectors are computed with reference to a common origin (i.e. the consensus shape in a geometric morphometrics). In this latter case, vector subtraction (rather than addition) will define the resultant of the evolutionary direction. It is important to realize that resultants could be at any angle even if the species (the terminal vectors) have similar phenotypes, because path resultants, rather than individual phenotypes, are being contrasted. However, the function also provides the angle between individual phenotypes as 'angle.between.species'. To perform randomization test (random = "yes"), the evolutionary directions of the two species are collapsed together. Then, for each variable, the median is found, and random paths of the same size as the original paths are produced sampling at random from the 47.5th to the 52.5th percentile around the medians. This way, a random distribution of angles is obtained under the hypothesis that the two directions are actually parallel. The 'angle.direction' represents the angle formed by the species phenotype and a vector of 1s (as long as the number of variables representing the phenotype). This way, each species phenotype is contrasted to the same vector. The 'angle.direction' values could be inspected to test whether individual species phenotypes evolve towards similar directions.

Value

Under all specs, evo.dir returns a 'list' object. The length of the list is one if pair.type = "tips". If pair.type = "node", the list is as long as the number of all possible species pairs descending from the node. Each element of the list contains:

angle.path.A angle of the resultant vector of species A to MRCA

vector.size.species.A size of the resultant vector of species A to MRCA

angle.path.B angle of the resultant vector of species B to MRCA

vector.size.species.B size of the resultant vector of species B to MRCA

angle.between.species.to.mrca angle between the species paths resultant vectors to the MRCA

angle.between.species angle between species vectors (as they are, without computing the path)

MRCA the node identifying the most recent common ancestor of A and B

angle.direction.A angle of the vector of species A (as it is, without computing the path) to a fixed reference vector (the same for all species)

vec.size.direction.A size of the vector of species A

angle.direction.B angle of the vector of species B (as it is, without computing the path) to a fixed reference vector (the same for all species)

vec.size.direction.B size of the vector of species B

If random = "yes", results also include p-values for the angles.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

## Not run: 
  data("DataApes")
  DataApes$PCstage->PCstage
  DataApes$Tstage->Tstage
  cc<- 2/parallel::detectCores()

  RRphylo(tree=Tstage,y=PCstage, clus=cc)->RRstage

# Case 1. Without performing randomization test

 # Case 1.1 Computing angles between rate vectors
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="rates",pair.type="node",node=57 ,
    random="no")->ed1
  # for a given couple of species
    evo.dir(RRstage,angle.dimension="rates",pair.type="tips",
    pair= c("Sap_1","Tro_2"),random="no")->ed2

 # Case 1.2 computing angles between phenotypic vectors provided by the user
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="original",
    y=PCstage,pair.type="node",node=57,random="no")->ed3
  # for a given couple of species
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="original",
    y=PCstage,pair.type="tips",pair=c("Sap_1","Tro_2"),random="no")->ed4

 # Case 1.3 computing angles between phenotypic vectors produced by "RRphylo"
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="RR",
    pair.type="node",node=57,random="no")->ed5
  # for a given couple of species
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="RR",
    pair.type="tips",pair=c("Sap_1","Tro_2"),random="no")->ed6


# Case 2. Performing randomization test

 # Case 2.1 Computing angles between rate vectors
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="rates",pair.type="node",node=57 ,
    random="yes",nrep=10)->ed7

  # for a given couple of species
    evo.dir(RRstage,angle.dimension="rates",pair.type="tips",
    pair= c("Sap_1","Tro_2"),random="yes",nrep=10)->ed8

 # Case 2.2 computing angles between phenotypic vectors provided by the user
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="original",
    y=PCstage,pair.type="node",node=57,random="yes",nrep=10)->ed9

  # for a given couple of species
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="original",
    y=PCstage,pair.type="tips",pair=c("Sap_1","Tro_2"),random="yes",nrep=10)->ed10

 # Case 2.3 computing angles between phenotypic vectors produced by "RRphylo"
  # for each possible couple of species descending from node 57
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="RR",
    pair.type="node",node=57,random="yes",nrep=10)->ed11

  # for a given couple of species
    evo.dir(RRstage,angle.dimension="phenotypes",y.type="RR",
    pair.type="tips",pair=c("Sap_1","Tro_2"),random="yes",nrep=10)->ed12
    
## End(Not run)

Description

The function either collapses clades under a polytomy or resolves polytomous clades to non-zero length branches, dichotomous clades.

Usage

fix.poly(tree,type=c("collapse","resolve"),node=NULL,tol=1e-10,random=TRUE)

Arguments

Details

Under type='resolve' polytomous clades are resolved adding non-zero length branches to each new node. The evolutionary time attached to the new nodes is partitioned equally below the dichotomized clade.

Value

A phylogenetic tree with randomly fixed (i.e. type='resolve') polytomies or created polytomies (i.e. type='collapse').Note, tip labels are ordered according to their position in the tree.

Author(s)

Silvia Castiglione, Pasquale Raia, Carmela Serio

References

Castiglione, S., Serio, C., Piccolo, M., Mondanaro, A., Melchionna, M., Di Febbraro, M., Sansalone, G., Wroe, S., & Raia, P. (2020). The influence of domestication, insularity and sociality on the tempo and mode of brain size evolution in mammals. Biological Journal of the Linnean Society,132: 221-231. doi:10.1093/biolinnean/blaa186

See Also

fix.poly vignette;

Examples

## Not run: 
 require(ape)

 data("DataCetaceans")
 DataCetaceans$treecet->treecet

 # Resolve all the polytomies within Cetaceans phylogeny
 fix.poly(treecet,type="resolve")->treecet.fixed
 par(mfrow=c(1,2))
 plot(treecet,no.margin=TRUE,show.tip.label=FALSE)
 plot(treecet.fixed,no.margin=TRUE,show.tip.label=FALSE)

 # Resolve the polytomies pertaining the genus Kentriodon
 fix.poly(treecet,type="resolve",node=221)->treecet.fixed2
 par(mfrow=c(1,2))
 plot(treecet,no.margin=TRUE,show.tip.label=FALSE)
 plot(treecet.fixed2,no.margin=TRUE,show.tip.label=FALSE)

 # Collapse Delphinidae into a polytomous clade
 fix.poly(treecet,type="collapse",node=179)->treecet.collapsed
 par(mfrow=c(1,2))
 plot(treecet,no.margin=TRUE,show.tip.label=FALSE)
 plot(treecet.collapsed,no.margin=TRUE,show.tip.label=FALSE)

## End(Not run)

Description

The function returns the most recent common ancestor and the number of species belonging to each or some user-specified genera within the phylogenetic tree.

Usage

getGenus(tree,genera=NULL)

Arguments

Value

The function returns a data-frame including the number of species, the most recent common ancestor of each genera (if a genus includes one species this is the species tip number), and whether the genera form monophyletic or paraphyletic clades.

Author(s)

Silvia Castiglione, Pasquale Raia, Carmela Serio

Examples

DataCetaceans$treecet->treecet

getGenus(treecet)->gg1
getGenus(treecet,c("Mesoplodon","Balaenoptera"))->gg2

Description

This function is a wrapper around phytools getDescendants (Revell 2012). It returns the node path from a given node or species to the root of the phylogeny.

Usage

getMommy(tree,N)

Arguments

Value

The function produces a vector of node numbers as integers, collated from a node or a tip towards the tree root.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

References

Revell, L. J. (2012). phytools: An R package for phylogenetic comparative biology (and other things). Methods in Ecology and Evolution, 3: 217-223.doi:10.1111/j.2041-210X.2011.00169.x

Examples

data("DataApes")
DataApes$Tstage->Tstage

getMommy(tree=Tstage,N=12)->gm

Description

The function identifies and returns the sister clade of a given node/tip.

Usage

getSis(tree,n,printZoom=TRUE)

Arguments

Value

The sister node number or sister tip name. In case of polytomies, the function returns a vector.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

data(DataOrnithodirans)
DataOrnithodirans$treedino->treedino
getSis(tree=treedino,n=677,printZoom=FALSE)->gs1
getSis(tree=treedino,n="Shenzhoupterus_chaoyangensis",printZoom=FALSE)->gs2

Description

The function generates lollipop or dumbbell dots charts.

Usage

lollipoPlot(values, type = "v", pt.lwd = NULL, pt.col = NULL, ...)

Arguments

Details

If a dumbbell dots chart is plotted, different parameters (i.e. col/cex/pch/bg/lwd) for starting and ending points can be supplied. See example for further details.

Author(s)

Silvia Castiglione, Carmela Serio, Pasquale Raia

Examples

require(emmeans)

lollipoPlot(values=feedlot[,4],pt.col="green",pt.lwd=2,lwd=0.8,col="gray20",
            ylab="swt",xlab="samples")

line.col<-sample(colors()[-1],length(levels(feedlot[,1])))
line.col<-rep(line.col,times=table(feedlot[,1]))

lollipoPlot(values=feedlot[order(feedlot[,1]),3],ylab="ewt",xlab="samples",
            bg=as.numeric(as.factor(feedlot[order(feedlot[,1]),2])),
            cex=1.2,pch=21,col=line.col)



lollipoPlot(values=feedlot[order(feedlot[,1]),3:4],type="h",ylab="ewt",xlab="samples",
            pt.col=c("blue","cyan"),cex=1.2,pch=c(3,4),col=line.col)

lollipoPlot(values=feedlot[order(feedlot[,1]),3:4],type="h",ylab="ewt",xlab="samples",
            bg=cbind(line.col,line.col),cex=c(1.2,1),pch=c(21,22))

Description

This function takes an object of class 'phylo' and randomly changes the lengths of the leaves.

Usage

makeFossil(tree,p=0.5,ex=0.5)

Arguments

Value

The function produces a phylogeny having the same backbone of the original one.

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

data("DataApes")
DataApes$Tstage->Tstage

makeFossil(tree=Tstage)->mf

Description

This function produces a $n * m$ matrix, where n=number of tips and m=number of branches (i.e. n + number of nodes). Each row represents the branch lengths aligned along a root-to-tip path.

Usage

makeL(tree)

Arguments

Value

The function returns a $n * m$ matrix of branch lengths for all root-to-tip paths in the tree (one per species).

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

data("DataApes")
DataApes$Tstage->Tstage

makeL(tree=Tstage)->ml

Description

This function produces a $n * n$ matrix, where n=number of internal branches. Each row represents the branch lengths aligned along a root-to-node path.

Usage

makeL1(tree)

Arguments

Value

The function returns a $n * n$ matrix of branch lengths for all root-to-node paths (one per each node of the tree).

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

data("DataApes")
DataApes$Tstage->Tstage

makeL1(tree=Tstage)->ml1

Description

Move a single tip or an entire clade to a different position within the tree.

Usage

move.lineage(tree,focal,sister,poly=FALSE,rescale=TRUE,rootage=NULL)

Arguments

Value

The phylogenetic tree with required topological changes.

Author(s)

Silvia Castiglione, Pasquale Raia

Examples

require(phytools)
DataCetaceans$tree->treecet

### Case 1. Moving a single tip
# sister to a tip
move.lineage(treecet,focal="Orcinus_orca",sister="Balaenoptera_musculus")->mol1
# sister to a clade
move.lineage(treecet,focal="Orcinus_orca",sister=131)->mol2
# sister to a clade by using treecet$node.label
move.lineage(treecet,focal="Balaenoptera_musculus",sister="Clade Delphinida")->mol3
# sister to a specific genus
move.lineage(treecet,focal="Orcinus_orca",sister="Genus Balaenoptera")->mol4
# sister to the tree root with and without rootage
move.lineage(treecet,focal="Balaenoptera_musculus",sister=117)->mol5
move.lineage(treecet,focal="Balaenoptera_musculus",sister=117,rootage=max(diag(vcv(treecet))))->mol6

### Case 2. Moving a clade
# sister to a tip
move.lineage(treecet,focal="Genus Mesoplodon",sister="Balaenoptera_musculus")->mol7
move.lineage(treecet,focal="Clade Delphinida",sister="Balaenoptera_musculus")->mol8
move.lineage(treecet,focal=159,sister="Balaenoptera_musculus")->mol9
# sister to a clade
move.lineage(treecet,focal="Genus Mesoplodon",sister=131)->mol10
move.lineage(treecet,focal="Clade Delphinida",sister=131)->mol11
move.lineage(treecet,focal=159,sister=131)->mol12
# sister to a clade by using treecet$node.label
move.lineage(treecet,focal="Genus Mesoplodon",sister="Clade Plicogulae")->mol13
move.lineage(treecet,focal="Clade Delphinida",sister="Clade Plicogulae")->mol14
move.lineage(treecet,focal=159,sister="Clade Plicogulae")->mol15
# sister to a specific genus
move.lineage(treecet,focal="Genus Mesoplodon",sister="Genus Balaenoptera")->mol16
move.lineage(treecet,focal="Clade Delphinida",sister="Genus Balaenoptera")->mol17
move.lineage(treecet,focal=159,sister="Genus Balaenoptera")->mol18
# sister to the tree root with and without rootage
move.lineage(treecet,focal="Genus Mesoplodon",sister=117)->mol19
move.lineage(treecet,focal="Clade Delphinida",sister=117)->mol20
move.lineage(treecet,focal=159,sister=117)->mol21
move.lineage(treecet,focal="Genus Mesoplodon",
             sister=117,rootage=max(diag(vcv(treecet))))->mol22
move.lineage(treecet,focal="Clade Delphinida",
             sister=117,rootage=max(diag(vcv(treecet))))->mol23
move.lineage(treecet,focal=159,sister=117,rootage=max(diag(vcv(treecet))))->mol24

Description

The function cross-references two vectors of species names checking for possible synonyms, misspelled names, and genus-species or species-subspecies correspondence.

Usage

namesCompare(vec1,vec2,proportion=0.15,
  focus=c("genus","subspecies","epithet","misspelling"))

Arguments

Value

The function returns a list including (according to focus):

$genus if vec1 includes genera names which miss specific epithet, this object lists all the species in vec2 belonging to each of the genera.

$subspecies if vec1 includes subspecies (i.e. two epithets after genus name), this object lists species in vec2 possibly corresponding to each of the subspecies.

$epithet lists species with matching epithets as possible synonyms.

$misspelling lists possible misspelled names. For each proposed mismatched names pair the proportion of characters in the vec1 differing from the string in vec2 is returned.

Author(s)

Silvia Castiglione, Carmela Serio, Antonella Esposito

Examples

## Not run: 
names(DataFelids$statefel)->nams.fel
nams.fel[c(19,12,37,80,43)]<-c("Puma_yagouaroundi","Felis_manul","Catopuma",
                           "Pseudaelurus","Panthera_zdansky")
nams<-nams.fel[-81]

namesCompare(nams,names(DataFelids$statefel))->nc1
namesCompare(names(DataFelids$statefel),nams)->nc2

## End(Not run)

Description

Given a vector of nodes, the function collates nodes along individual lineages from the youngest (i.e. furthest from the tree root) to the oldest.

Usage

node.paths(tree, vec)

Arguments

Value

A list of node paths, each starting from the youngest node (i.e. furthest from the tree root) and ending to the oldest along the path.

Author(s)

Silvia Castiglione, Pasquale Raia

Examples

require(ape)

rtree(100)->tree
sample(seq(Ntip(tree)+1,Ntip(tree)+Nnode(tree)),20)->nods
plot(tree,show.tip.label=FALSE)
nodelabels(node=nods,frame="n",col="red")
node.paths(tree=tree, vec=nods)->np

Description

Testing the robustness of PGLS_fossil results to sampling effects and phylogenetic uncertainty.

Usage

overfitPGLS(modform,oveRR=NULL,phylo.list=NULL,data=NULL,...)

Arguments

Value

The function returns a list containing two 'RRphyloList' objects including results of PGLS_fossil performed by using the phylogeny as it is ($tree) and/or rescaled according to RRphylo rates ($RR). The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Carmela Serio, Giorgia Girardi, Pasquale Raia

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P. (2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

See Also

overfitPGLS vignette ; Alternative-trees vignette

Examples

## Not run: 
cc<- 2/parallel::detectCores()
library(phytools)
library(ape)

# generate fictional data to test the function
rtree(100)->tree
fastBM(tree)->resp
fastBM(tree,nsim=3)->resp.multi
fastBM(tree)->pred1
fastBM(tree)->pred2
data.frame(y1=resp,x2=pred1,x1=pred2)->dat

# perform RRphylo and PGLS_fossil with univariate/multivariate phenotypic data
PGLS_fossil(modform=y1~x1+x2,data=dat,tree=tree)->pgls_noRR
RRphylo(tree,resp,clus=cc)->RR
PGLS_fossil(modform=resp~pred1+pred2,RR=RR)->pgls_RR

PGLS_fossil(modform=y1~x1+x2,data=list(y1=resp.multi,x2=pred1,x1=pred2),tree=tree)->pgls2_noRR
RRphylo(tree,resp.multi,clus=cc)->RR2
PGLS_fossil(modform=resp.multi~pred1+pred2,tree=tree,RR=RR2)->pgls2_RR

# overfitPGLS routine
# generate a list of subsampled and swapped phylogenies to test
tree.list<-resampleTree(RR$tree,s = 0.25,swap.si=0.1,swap.si2=0.1,nsim=10)

# test the robustnes of PGLS_fossil with univariate/multivariate phenotypic data
ofRR<-overfitRR(RR = RR,y=resp,phylo.list=tree.list,clus=cc)
ofPGLS<-overfitPGLS(oveRR = ofRR,phylo.list=tree.list,modform = y1~x1+x2,data=dat)

ofRR2<-overfitRR(RR = RR2,y=resp.multi,phylo.list=tree.list,clus=cc)
ofPGLS2<-overfitPGLS(oveRR = ofRR2,phylo.list=tree.list,modform = y1~x1+x2,
                     data=list(y1=resp.multi,x2=pred1,x1=pred2))

## End(Not run)

Description

Testing the robustness of RRphylo results to sampling effects and phylogenetic uncertainty.

Usage

overfitRR(RR,y, phylo.list, aces=NULL,x1=NULL, aces.x1=NULL, cov=NULL,
  rootV=NULL, clus=0.5, s = NULL, swap.args = NULL, nsim=NULL , trend.args =
  NULL, shift.args = NULL, conv.args = NULL, pgls.args = NULL)

Arguments

Details

Methods using a large number of parameters risk being overfit. This usually translates in poor fitting with data and trees other than the those originally used. With RRphylo methods this risk is usually very low. However, the user can assess how robust the results of RRphylo are by running resampleTree and overfitRR. The former is used to subsample the tree according to a s parameter (that is the proportion of tips to be removed from the tree) and to alter tree topology by means of swapONE. The list of altered topologies is fed to overfitRR, which cross-references each tree with the phenotypic data and performs RRphylo on them. Thereby, both the potential for overfit and phylogenetic uncertainty are accounted for straight away.

Otherwise, a list of alternative phylogenies can be supplied to overfitRR. In this case subsampling and swapping arguments are ignored, and robustness testing is performed on the alternative topologies as they are.

Value

The function returns a 'RRphyloList' object containing:

$RR.list a 'RRphyloList' including the results of each RRphylo performed within overfitRR.

$root.est the estimated root value per simulation.

$rootCI the 95% confidence interval around the root value.

$ace.regressions a 'RRphyloList' including the results of linear regression between ancestral state estimates before and after the subsampling.

The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Carmela Serio, Giorgia Girardi, Pasquale Raia

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P. (2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

Castiglione, S., Serio, C., Mondanaro, A., Di Febbraro, M., Profico, A., Girardi, G., & Raia, P. (2019a) Simultaneous detection of macroevolutionary patterns in phenotypic means and rate of change with and within phylogenetic trees including extinct species. PLoS ONE, 14: e0210101. https://doi.org/10.1371/journal.pone.0210101

See Also

overfitRR vignette ;

Examples

## Not run: 
cc<- 2/parallel::detectCores()
library(ape)

## overfitRR routine
# load the RRphylo example dataset including Ornithodirans tree and data
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
DataOrnithodirans$statedino->statedino

# extract Pterosaurs tree and data
extract.clade(treedino,746)->treeptero
massdino[match(treeptero$tip.label,names(massdino))]->massptero
massptero[match(treeptero$tip.label,names(massptero))]->massptero

# peform RRphylo on body mass
RRphylo(tree=treeptero,y=log(massptero),clus=cc)->RRptero

# generate a list of subsampled and swapped phylogenies to test
treeptero.list<-resampleTree(RRptero$tree,s = 0.25,swap.si = 0.1,swap.si2 = 0.1,nsim=10)

# test the robustness of RRphylo
ofRRptero<-overfitRR(RR = RRptero,y=log(massptero),phylo.list=treeptero.list,clus=cc)


## overfitRR routine on multiple RRphylo
# load the RRphylo example dataset including Cetaceans tree and data
data("DataCetaceans")
DataCetaceans$treecet->treecet
DataCetaceans$masscet->masscet
DataCetaceans$brainmasscet->brainmasscet
DataCetaceans$aceMyst->aceMyst

# cross-reference the phylogenetic tree and body and brain mass data. Remove from
# both the tree and vector of body sizes the species whose brain size is missing
drop.tip(treecet,treecet$tip.label[-match(names(brainmasscet),treecet$tip.label)])->treecet.multi
masscet[match(treecet.multi$tip.label,names(masscet))]->masscet.multi

# peform RRphylo on the variable (body mass) to be used as additional predictor
RRphylo(tree=treecet.multi,y=masscet.multi,clus=cc)->RRmass.multi
RRmass.multi$aces[,1]->acemass.multi

# create the predictor vector: retrieve the ancestral character estimates
# of body size at internal nodes from the RR object ($aces) and collate them
# to the vector of species' body sizes to create
c(acemass.multi,masscet.multi)->x1.mass

# peform RRphylo on brain mass by using body mass as additional predictor
RRphylo(tree=treecet.multi,y=brainmasscet,x1=x1.mass,clus=cc)->RRmulti

# generate a list of subsampled and swapped phylogenies to test
treecet.list<-resampleTree(RRmulti$tree,s = 0.25,swap.si=0.1,swap.si2=0.1,nsim=10)

# test the robustness of multiple RRphylo
ofRRcet<-overfitRR(RR = RRmulti,y=brainmasscet,phylo.list=treecet.list,clus=cc,x1 =x1.mass)

## End(Not run)

Description

Testing the robustness of search.conv (Castiglione et al. 2019b) results to sampling effects and phylogenetic uncertainty.

Usage

overfitSC(RR,y.list,phylo.list,s=0.25,
  nodes=NULL,state=NULL,declust=FALSE,
  aces=NULL,x1=NULL,aces.x1=NULL,cov=NULL,rootV=NULL, clus=0.5)

Arguments

Details

Methods using a large number of parameters risk being overfit. This usually translates in poor fitting with data and trees other than the those originally used. With RRphylo methods this risk is usually very low. However, the user can assess how robust the results of search.conv are by running resampleTree and overfitSC. The former is used to subsample the tree according to a s parameter (that is the proportion of tips to be removed from the tree) and to alter tree topology by means of swapONE. Once a list of new phylogenetic trees (phylo.list) is generated, in case the shape data to feed to search.conv are reduced (e.g. via SVD), it is necessary to recompute data reduction, thus obtaining a list of multivariate phenotypes related to the phylogenetic trees (y.list). Finally, overfitSC performs RRphylo and search.conv on each new set of tree and data. Thereby, both the potential for overfit and phylogenetic uncertainty are accounted for straight away.

Otherwise, a list of alternative phylogenies can be supplied to overfitSC. In this case subsampling and swapping arguments are ignored, and robustness testing is performed on the alternative topologies as they are. If a clade has to be tested in search.conv, the function scans each alternative topology searching for the corresponding clade. If the species within such clade on the alternative topology differ more than 10% from the species within the clade in the original tree, the identity of the clade is considered disrupted and the test is not performed.

Value

The function returns a 'RRphyloList' object containing:

$RR.list a 'RRphyloList' including the results of each RRphylo performed within overfitSC

$SCnode.list a 'RRphyloList' including the results of each search.conv - clade condition performed within overfitSC

$SCstate.list a 'RRphyloList' including the results of each search.conv - state condition performed within overfitSC

$conv.results a list including results for search.conv performed under clade and state conditions. If a node pair is specified within conv.args, the $clade object contains the percentage of simulations producing significant p-values for convergence between the clades, and the proportion of tested trees (i.e. where the clades identity was preserved; always 1 if no phylo.list is supplied). If a state vector is supplied within conv.args, the object $state contains the percentage of simulations producing significant p-values for convergence within (single state) or between states (multiple states).

The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Giorgia Girardi, Carmela Serio

References

Castiglione, S., Serio, C., Tamagnini, D., Melchionna, M., Mondanaro, A., Di Febbraro, M., Profico, A., Piras, P.,Barattolo, F., & Raia, P. (2019b). A new, fast method to search for morphological convergence with shape data. PLoS ONE, 14, e0226949. https://doi.org/10.1371/journal.pone.0226949

See Also

search.conv vignette; overfit vignette; Alternative-trees vignette

Examples

## Not run: 
require(phytools)
require(Morpho)
require(ape)

cc<- 2/parallel::detectCores()

DataFelids$treefel->treefel
DataFelids$statefel->statefel
DataFelids$landfel->feldata

# perform data reduction via Procrustes superimposition (in this case) and RRphylo
procSym(feldata)->pcafel
pcafel$PCscores->PCscoresfel

RRphylo(treefel,PCscoresfel,clus=cc)->RRfelids

# apply search.conv under nodes and state condition
search.conv(RR=RRfelids, y=PCscoresfel, min.dim=5, min.dist="time38", clus=cc)->sc.clade.time

search.conv(tree=treefel, y=PCscoresfel, state=statefel, declust=TRUE, clus=cc)->sc.state

# select converging clades returned in sc.clade.time
felnods<-rbind(c(85,155),c(85,145))

## overfitSC routine

# generate a list of subsampled and swapped phylogenies to test for search.conv
# robustness. Use as reference tree the phylogeny returned by RRphylo.
# Set the nodes and the categories under testing as arguments of
# resampleTree so that it maintains no less than 5 species at least in each
# clade/state.
treefel.list<-resampleTree(RRfelids$tree,s=0.15,nodes=unique(c(felnods)),categories=statefel,
                        nsim=15,swap.si=0.1,swap.si2=0.1)

# match the original data with each subsampled-swapped phylogeny in treefel.list
#  and repeat data reduction
y.list<-lapply(treefel.list,function(k){
  treedataMatch(k,feldata)[[1]]->ynew
  procSym(ynew)$PCscores
})

# test for robustness of search.conv results by overfitSC
oSC<-overfitSC(RR=RRfelids,phylo.list=treefel.list,y.list=y.list,
               nodes = felnods,state=statefel,clus=cc)


## End(Not run)

Description

Testing the robustness of search.shift (Castiglione et al. 2018) results to sampling effects and phylogenetic uncertainty.

Usage

overfitSS(RR,oveRR,node=NULL,state=NULL)

Arguments

Value

The function returns a 'RRphyloList' object containing:

$SSclade.list a 'RRphyloList' including the results of each search.shift - clade condition performed within overfitSS.

$SSsparse.list a 'RRphyloList' including the results of each search.shift - sparse condition performed within overfitSS.

$shift.results a list including results for search.shift performed under clade and sparse conditions. If one or more nodes are specified, the $clade$single.clades object contains the proportion of simulations producing significant and positive or significant and negative rate shifts for each single node, either compared to the rest of the tree ($singles) or to the rest of the tree after removing other shifting clades ($no.others). The object $clade$all.clades.together includes the same proportions obtained by testing all the specified clades as a whole (i.e. considering them as evolving under a single rate regime). For each node the proportion of tested trees (i.e. where the clade identity was preserved) is also indicated. If a state vector is supplied, the object $sparse contains the percentage of simulations producing significant p-value separated by shift sign ($p.states).

The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Carmela Serio, Giorgia Girardi, Pasquale Raia

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P. (2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

See Also

overfitSS vignette ; search.shift vignette ; Alternative-trees vignette

Examples

## Not run: 
cc<- 2/parallel::detectCores()
# load the RRphylo example dataset including Ornithodirans tree and data
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
log(DataOrnithodirans$massdino)->massdino
DataOrnithodirans$statedino->statedino

# peform RRphylo on Ornithodirans tree and data
RRphylo(tree=treedino,y=massdino,clus=cc)->dinoRates

# perform search.shift under both "clade" and "sparse" condition
search.shift(RR=dinoRates, status.type= "clade")->SSauto
search.shift(RR=dinoRates, status.type= "sparse", state=statedino)->SSstate

## overfitSS routine
# generate a list of subsampled and swapped phylogenies, setting as categories/node
# the state/node under testing
treedino.list<-resampleTree(dinoRates$tree,s = 0.25,categories=statedino,
                        node=rownames(SSauto$single.clades),swap.si = 0.1,swap.si2 = 0.1,nsim=10)

# test the robustness of search.shift
ofRRdino<-overfitRR(RR = dinoRates,y=massdino,phylo.list=treedino.list,clus=cc)
ofSS<-overfitSS(RR = dinoRates,oveRR = ofRRdino,state=statedino,node=rownames(SSauto$single.clades))


## End(Not run)

Description

Testing the robustness of search.trend (Castiglione et al. 2019a) results to sampling effects and phylogenetic uncertainty.

Usage

overfitST(RR,y,oveRR,x1=NULL,x1.residuals=FALSE,node=NULL,cov=NULL,clus=0.5)

Arguments

Value

The function returns a 'RRphyloList' object containing:

$ST.list a 'RRphyloList' including the results of each search.trend performed within overfitST.

$trend.results a list including the percentage of simulations showing significant p-values for phenotypes versus age and absolute rates versus age regressions for the entire tree separated by slope sign ($tree). If one or more nodes are specified within trend.args, the list also includes the same results at nodes ($node) and the results for comparison between nodes ($comparison). For each node the proportion of tested trees (i.e. where the clade identity was preserved; always 1 if no phylo.list is supplied) is also indicated.

The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Carmela Serio, Giorgia Girardi, Pasquale Raia

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P. (2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

Castiglione, S., Serio, C., Mondanaro, A., Di Febbraro, M., Profico, A., Girardi, G., & Raia, P. (2019a) Simultaneous detection of macroevolutionary patterns in phenotypic means and rate of change with and within phylogenetic trees including extinct species. PLoS ONE, 14: e0210101. https://doi.org/10.1371/journal.pone.0210101

See Also

overfitST vignette ; search.trend vignette ; Alternative-trees vignette

Examples

## Not run: 
cc<- 2/parallel::detectCores()
library(ape)

## Case 1
# load the RRphylo example dataset including Ornithodirans tree and data
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
DataOrnithodirans$statedino->statedino

# extract Pterosaurs tree and data
extract.clade(treedino,746)->treeptero
massdino[match(treeptero$tip.label,names(massdino))]->massptero
massptero[match(treeptero$tip.label,names(massptero))]->massptero

# perform RRphylo and search.trend on body mass data
RRphylo(tree=treeptero,y=log(massptero),clus=cc)->RRptero
search.trend(RR=RRptero, y=log(massptero),node=143,clus=cc)->st2

## overfitST routine
# generate a list of subsampled and swapped phylogenies setting as node
# the clade under testing
treeptero.list<-resampleTree(RRptero$tree,s = 0.25,node=143,
                             swap.si = 0.1,swap.si2 = 0.1,nsim=10)

# test the robustness of search.trend
ofRRptero<-overfitRR(RR = RRptero,y=log(massptero),phylo.list=treeptero.list,clus=cc)
ofSTptero<-overfitST(RR=RRptero,y=log(massptero),oveRR=ofRRptero,node=143,clus=cc)


## Case 2
# load the RRphylo example dataset including Cetaceans tree and data
data("DataCetaceans")
DataCetaceans$treecet->treecet
DataCetaceans$masscet->masscet
DataCetaceans$brainmasscet->brainmasscet

# cross-reference the phylogenetic tree and body and brain mass data. Remove from
# both the tree and vector of body sizes the species whose brain size is missing
drop.tip(treecet,treecet$tip.label[-match(names(brainmasscet),
                                               treecet$tip.label)])->treecet.multi
masscet[match(treecet.multi$tip.label,names(masscet))]->masscet.multi

# peform RRphylo on the variable (body mass) to be used as additional predictor
RRphylo(tree=treecet.multi,y=masscet.multi,clus=cc)->RRmass.multi
RRmass.multi$aces[,1]->acemass.multi

# create the predictor vector: retrieve the ancestral character estimates
# of body size at internal nodes from the RR object ($aces) and collate them
# to the vector of species' body sizes to create
c(acemass.multi,masscet.multi)->x1.mass

# peform RRphylo and search.trend on brain mass by using body mass as additional predictor
RRphylo(tree=treecet.multi,y=brainmasscet,x1=x1.mass,clus=cc)->RRmulti
search.trend(RR=RRmulti, y=brainmasscet,x1=x1.mass,clus=cc)->STcet

## overfitST routine
# generate a list of subsampled and swapped phylogenies to test
treecet.list<-resampleTree(RRmulti$tree,s = 0.25,swap.si=0.1,swap.si2=0.1,nsim=10)

# test the robustness of search.trend with and without x1.residuals
ofRRcet<-overfitRR(RR = RRmulti,y=brainmasscet,phylo.list=treecet.list,clus=cc,x1 =x1.mass)
ofSTcet1<-overfitST(RR=RRmulti,y=brainmasscet,oveRR=ofRRcet,x1 =x1.mass,clus=cc)
ofSTcet2<-overfitST(RR=RRmulti,y=brainmasscet,oveRR=ofRRcet,x1 =x1.mass,x1.residuals = TRUE,clus=cc)

## End(Not run)

Description

The function performs pgls for non-ultrametric trees using a variety of evolutionary models or RRphylo rates to change the tree correlation structure.

Usage

PGLS_fossil(modform,data=NULL,tree=NULL,RR=NULL,GItransform=FALSE,
  intercept=FALSE,model="BM",method=NULL,permutation="none",...)

Arguments

Details

The function is meant to work with both univariate or multivariate data, both low- or high-dimensional. In the first case, PGLS_fossil uses phylolm, returning an object of class "phylolm". In the latter, regression coefficients are estimated by mvgls, and statistical significance is obtained by means of permutations within manova.gls. In this case, PGLS_fossil returns a list including the output of both analyses. In all cases, for both univariate or multivariate data, if GItransform = TRUE the functions returns a standard lm output. In the latter case, the output additionally includes the result of manova applied on the multivariate linear model.

Value

Fitted pgls parameters and significance. The class of the output object depends on input data (see details). The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Pasquale Raia, Carmela Serio, Gabriele Sansalone, Giorgia Girardi

References

Garland, Jr, T., & Ives, A. R. (2000). Using the past to predict the present: confidence intervals for regression equations in phylogenetic comparative methods. The American Naturalist, 155: 346-364. doi:10.1086/303327

See Also

RRphylo vignette;

overfitPGLS; overfitPGLS vignette

mvgls ; manova.gls

phylolm

Examples

## Not run: 
library(ape)
library(phytools)
cc<- 2/parallel::detectCores()

rtree(100)->tree
fastBM(tree)->resp
fastBM(tree,nsim=3)->resp.multi
fastBM(tree)->pred1
fastBM(tree)->pred2

PGLS_fossil(modform=resp~pred1+pred2,tree=tree)->pgls_noRR
PGLS_fossil(modform=resp~pred1+pred2,tree=tree,GItransform=TRUE)->GIpgls_noRR

RRphylo(tree,resp,clus=cc)->RR
PGLS_fossil(modform=resp~pred1+pred2,RR=RR)->pgls_RR
PGLS_fossil(modform=resp~pred1+pred2,tree=tree,RR=RR,GItransform=TRUE)->GIpgls_RR

# To derive log-likelihood and AIC for outputs of PGLS_fossil applied on univariate
# response variables the function AIC can be applied
AIC(pgls_noRR)
AIC(pgls_RR)
AIC(GIpgls_noRR)
AIC(GIpgls_RR)


PGLS_fossil(modform=resp.multi~pred1+pred2,tree=tree)->pgls2_noRR
PGLS_fossil(modform=resp.multi~pred1+pred2,tree=tree,GItransform=TRUE)->GIpgls2_noRR

# To evaluate statistical significance of multivariate models, the '$manova'
# object must be inspected
pgls2_noRR$manova
summary(GIpgls2_noRR$manova)

RRphylo(tree,resp.multi,clus=cc)->RR2
PGLS_fossil(modform=resp.multi~pred1+pred2,RR=RR2)->pgls2_RR
PGLS_fossil(modform=resp.multi~pred1+pred2,tree=tree,RR=RR2,GItransform=TRUE)->GIpgls2_RR

# To evaluate statistical significance of multivariate models, the '$manova'
# object must be inspected
pgls2_noRR$manova
summary(GIpgls2_noRR$manova)
pgls2_RR$manova
summary(GIpgls2_RR$manova)

logLik(pgls2_noRR$pgls)
logLik(pgls2_RR$pgls)

## End(Not run)

Description

The function tests the presence of phylogenetic clustering for species within a focal state.

Usage

phyloclust(tree,state,focal,nsim=100)

Arguments

Details

To test for phylogenetic clustering, the function computes the mean cophenetic (i.e. evolutionary time) distance between all the species under the focal state. Such value is compared to a random distribution of time distances obtained by sampling nsim times as many random tips as those under the focal state. In the presence of significant phylogenetic clustering, tips under the focal state are randomly removed until the p becomes >0.05 or only 3 tips are left.

Value

The function returns a list including the p-value ($p) for the test of phylogenetic clustering and a $declusterized object containing the declusterized versions of the original tree and state vector (i.e. tips are removed as to make p>0.05) and the vector of removed species.

Author(s)

Silvia Castiglione, Pasquale Raia

Examples

data("DataFelids")
DataFelids$treefel->treefel
DataFelids$statefel->statefel

phyloclust(tree=treefel,state=statefel,focal="saber")->pcl

Description

This function generates customized functions to produce plots out of search.conv results.

Usage

plotConv(SC,y,variable,RR=NULL,state=NULL,aceV=NULL)

Arguments

Value

If convergence between clades was tested, plotConv returns a list of four functions:

$plotHistTips shows the mean Euclidean distance computed between phenotypic vectors of all the tips belonging to the converging clades as compared to the distribution of distances between all possible pair of tips across the rest of the tree. The usage is: ...$plotHistTips(hist.args=NULL,line.args=NULL), where hist.args is a list of further arguments passed to the function hist, and line.args is a list of further arguments passed to the function lines.

$plotHistAces shows the Euclidean distance computed between phenotypic vectors of the MRCAs of the converging clades as compared to the distribution of distances between all possible pairs of nodes across the rest of the tree. The usage is identical to $plotHistTips.

$plotPChull generates a PC1/PC2 plot obtained by performing a PCA of the species phenotypes. Convergent clades are indicated by colored convex hulls. Large dots represent the mean phenotypes per clade (i.e. their group centroids) and asterisks (customizable) represent the ancestral phenotypes of the individual clades. The usage is: ...$plotPChull(plot.args=NULL,chull.args=NULL,means.args=NULL, ace.args=NULL,legend.args=list(),where plot.args is a list of further arguments passed to the function plot, chull.args is a list of further arguments passed to the function polygon, means.args and ace.args are lists of further argument passed to the function points to customize the dots representing the centroids and the ancestral phenotypes respectively, and legend.args is a list of additional arguments passed to the function legend (if = NULL the legend is not plotted).

$plotTraitgram produces a modified traitgram plot (see package picante) highlighting the branches of the clades found to converge. The usage is: plotTraitgram(colTree=NULL,colNodes=NULL,...), where colTree is the color to represent the traitgram lines not pertaining the converging clades, colNodes is the color (or the vector of colors) to represent the traitgram lines pertaining the converging clades, and ... are further arguments passed to the function plot to plot lines.

If convergence between states was tested, plotConv returns a list of two functions:

$plotPChull generates a PC1/PC2 plot obtained by performing a PCA of the species phenotypes, with colored convex hulls enclosing species belonging to different states. The usage is: ...$plotPChull(plot.args=NULL,chull.args=NULL,points.args=NULL, legend.args=list(), where plot.args is a list of further arguments passed to the function plot, chull.args is a list of further arguments passed to the function polygon, points.args is a list of further argument passed to the function points, and legend.args is a list of additional arguments passed to the function legend (if = NULL the legend is not plotted).

$plotPolar produces a polar plot of the mean angle within/between state/s as compared to the 95 angles. The usage is: ...$plotPolar(polar.args=NULL,polygon.args=NULL,line.args=NULL), where polar.args is a list of further arguments passed to the function polar.plot to set the plot basics (i.e. radial.lim, start, and so on), polygon.args is a list of further arguments passed to the function polar.plot under the condition rp.type="p" (see plotrix::polar.plot for details) to set the angles distribution graphics, and line.args is a list of further arguments passed to the function polar.plot under the condition rp.type="r" to set the mean angle graphics.

Author(s)

Silvia Castiglione

References

Castiglione, S., Serio, C., Tamagnini, D., Melchionna, M., Mondanaro, A., Di Febbraro, M., Profico, A., Piras, P.,Barattolo, F., & Raia, P. (2019). A new, fast method to search for morphological convergence with shape data. PLoS ONE, 14, e0226949. https://doi.org/10.1371/journal.pone.0226949

See Also

search.conv vignette

plotConv vignette

Examples

## Not run: 
data("DataFelids")
DataFelids$PCscoresfel->PCscoresfel
DataFelids$treefel->treefel
DataFelids$statefel->statefel->state2
state2[sample(which(statefel=="nostate"),20)]<-"st2"
cc<- 2/parallel::detectCores()

RRphylo(treefel,PCscoresfel,clus=cc)->RRfel

search.conv(RR=RRfel, y=PCscoresfel, min.dim=5, min.dist="node9",clus=cc)->sc.clade
plotConv(sc.clade,PCscoresfel,variable=2,RR=RRfel)->pc.clade

pc.clade$plotHistTips(hist.args = list(col="gray80",yaxt="n",cex.axis=0.8,cex.main=1.5),
                line.args = list(lwd=3,lty=4,col="purple"))
pc.clade$plotHistAces(hist.args = list(col="gray80",cex.axis=0.8,cex.main=1.5),
                line.args = list(lwd=3,lty=4,col="gold"))
pc.clade$plotPChull(chull.args = list(border=c("cyan","magenta"),lty=1),
              means.args = list(pch=c(23,22),cex=3,bg=c("cyan2","magenta2")),
              ace.args=list(pch=9),legend.args = NULL)
pc.clade$plotTraitgram(colTree = "gray70",colNodes = c("cyan","magenta"))


search.conv(tree=treefel, y=PCscoresfel, state=statefel,declust=TRUE,clus=cc)->sc.state
plotConv(sc.state,PCscoresfel,variable=1,state=statefel)->pc.state
pc.state$plotPChull(chull.args = list(border=c("gray70","blue"),lty=1),
              points.args = list(pch=c(23,22),bg="gray"),
              legend.args = list(pch=c(23,22),x="top"))

pc.state$plotPolar(polar.args = list(clockwise=TRUE,start=0,rad.col="black",grid.col="black"),
             polygon.args = list(line.col="green",poly.col=NA,lwd=2),
             line.args = list(line.col="deeppink",lty=2,lwd=3))

    
## End(Not run)

Description

This function generates customized functions to produce histograms and lollipop charts of the RRphylo rates computed for a given clade as compared to the rates computed for the rest of the tree.

Usage

plotRates(RR,node)

Arguments

Value

The function returns a list of functions:

$plotHist returns the histograms of rates (in ln absolute values) computed for the focal clade against rates computed the rest of the tree. The usage is: ...$plotHist(hist.args=list(col1,col2),legend.args=list()), where legend.args is a list of additional arguments passed to the function legend (if = NULL the legend is not plotted) and hist.args is a list of further arguments passed to the function plot.histogram. hist.args default arguments include histogram colors for background rates (col1) and rates of the clade under inspection (col2).

$plotLollipop returns the lollipop chart of the rates of individual branches of the focal clade collated in increasing rate value, and contrasted to the average rate computed over the rest of the tree branches (the vertical line). The usage is: ...$plotLollipop(lollipop.args=NULL,line.args=NULL), where lollipop.args is a list of further arguments passed to the function lollipoPlot and line.args is a list of additional arguments passed to the function line. This function additionally returns the vector of rates for the focal clade, collated in increasing order.

Author(s)

Silvia Castiglione, Pasquale Raia

See Also

RRphylo vignette

plotRates vignette

RRphylo vignette

plotRates vignette

Examples

data("DataApes")
DataApes$PCstage->PCstage
DataApes$Tstage->Tstage
cc<- 2/parallel::detectCores()

RRphylo(tree=Tstage,y=PCstage,clus=cc)->RRstage

plotRates(RRstage,node=72)->pR
pR$plotHist(hist.args=list(col1="cyan1",col2="blue"),legend.args=list(x="topright"))
pR$plotLollipop(lollipop.args=list(col="chartreuse",bg="chartreuse"),
                line.args=list(col="deeppink",lwd=2))

Description

This function generates customized functions to plot the phylogenetic tree (as returned by RRphylo) with branches colored according to phenotypic values or phenotypic evolutionary rates.

Usage

plotRR(RR,y,multivariate=NULL)

Arguments

Value

The function returns a list of functions:

$plotRRphen charts phenotypic values along the tree branches. Phenotypes at tips are taken as they are from the y object. Phenotypic values for internal branches are derived from the RR$aces object. The usage is: ...$plotRRphen(variable=NULL,tree.args=NULL,color.pal=NULL,colorbar.args=list()), where variable is the index or name of the variable to be plotted in case of multivariate data, tree.args is a list of further arguments passed to the function plot.phylo plus a logical indicating whether the tree should be ladderized before plotting (see examples below), color.pal is a function to generate the color palette, and colorbar.args is a list of further arguments passed to the function colorbar (if = NULL the bar is not plotted).

$plotRRrates charts evolutionary rate values along the tree branches. The usage is identical to $plotRRphen. In case of multivariate data and multivariate = "rates", the argument variable can be left unspecified.

Author(s)

Silvia Castiglione, Pasquale Raia

See Also

RRphylo vignette

plotRR vignette

RRphylo vignette

plotRR vignette

Examples

## Not run: 
data("DataApes")
DataApes$PCstage->PCstage
DataApes$Tstage->Tstage
cc<- 2/parallel::detectCores()

RRphylo(tree=Tstage,y=PCstage,clus=cc)->RRstage

plotRR(RRstage,y=PCstage,multivariate="multiple.rates")->pRR1
pRR1$plotRRphen(variable=1,tree.args=list(edge.width=2),color.pal=rainbow,
               colorbar.args = list(x="bottomleft",labs.adj=0.7,xpd=TRUE))
pRR1$plotRRrates(variable=2,tree.args=list(edge.width=2,direction="leftwards",ladderize=TRUE),
                color.pal=rainbow,colorbar.args = list(x="topright",labs.adj=0.7,xpd=TRUE))


plotRR(RRstage,y=PCstage,multivariate="rates")->pRR2
pRR2$plotRRrates(tree.args=list(edge.width=2),
                color.pal=hcl.colors,
                colorbar.args = list(x="topleft",labs.adj=0.7,xpd=TRUE,title.pos="bottom"))

## End(Not run)

Description

plotShift generates customized functions to produce plots out of search.shift results. addShift adds circles to highlight shifting clades onto the currently plotted tree.

Usage

plotShift(RR,SS,mode,state=NULL)

addShift(SS,symbols.args=NULL)

Arguments

Details

Using ...$plotClades() or plotting the tree and applying addShift() returns the same plot. The latter function might be useful in combination with plotRR to add the shifts information to the branch-wise plot of evolutionary rate values.

Value

The function returns a function to generate a customizable plot of search.shift results.

If search.shift was performed under status.type = "clade", plotShift returns a $plotClades function which highlights the shifting clades onto the phylogenetic tree. The usage is: ...$plotClades(tree.args=NULL,symbols.args=NULL), where tree.args is a list of further arguments passed to the function plot.phylo, and symbols.args is a list of further arguments passed to the function symbols (n.b. the shape of the symbol is not customizable). The function automatically plots red circles for negative shifts and blue circles for positive shifts, in each cases with the radium proportional to the absolute value of rate difference. The user can choose different color options for positive/negative shifts by setting symbols.args=list(fg=c(pos="color for positive shift",neg="color for negative shift")), or provide a vector of as many colors as the number of shifting clades. The same applies to the argument "bg".

If search.shift was performed under status.type = "sparse", plotShift returns a $plotStates function which plots the comparison between the real difference and the distributions of random differences (see search.shift vignette#sparse). The usage is: ...$plotStates(plot.args=NULL,points.args=NULL,legend.args=list()), where plot.args is a list of further arguments passed to the function plot (used in the form: plot(y~x)), points.args is a list of further arguments passed to the function points, and legend.args is a list of additional arguments passed to the function legend (if = NULL the legend is not plotted). If as many colors/pch values as the number of different states are provided in points.args, each of them is assigned to each states taken in the same alphabetical order.

Author(s)

Silvia Castiglione, Giorgia Girardi

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P.(2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

See Also

search.shift vignette

plotShift vignette

Examples

## Not run: 
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
DataOrnithodirans$statedino->statedino
cc<- 2/parallel::detectCores()

RRphylo(tree=treedino,y=massdino,clus=cc)->dinoRates

search.shift(RR=dinoRates,status.type="clade")->SSauto
plotShift(RR=dinoRates,SS=SSauto)->plotSSauto
plotSSauto$plotClades()

plot(dinoRates$tree)
addShift(SS=SSauto)

search.shift(RR=dinoRates,status.type="clade",node=c(696,746))->SSnode
plotShift(RR=dinoRates,SS=SSnode,mode=2)->plotSSnode
plotSSnode$plotClades(tree.args=list(no.margin=TRUE),
                  symbols.args=list(fg=NA,bg=c(pos="cyan",neg="magenta")))


search.shift(RR=dinoRates,status.type= "sparse",state=statedino)->SSstate
plotShift(RR=dinoRates,SS=SSstate,state=statedino)->plotSSstate
plotSSstate$plotStates(points.args=list(bg=c("gold","forestgreen","royalblue","white"),
                                   col=c("black","black","black","orangered"),
                                   pch=c(21,22,24,11)),legend.args=list())
    
## End(Not run)

Description

This function generates customized functions to produce plots of phenotype versus time and absolute evolutionary rates versus time regressions for the entire phylogeny and individual clades. Each custom function takes as first argument the index or name of the variable (as in the search.trend output in $trends.data$phenotypeVStime) to be plotted.

Usage

plotTrend(ST)

Arguments

Value

The function returns a list of functions:

$plotSTphen returns the plot of rescaled phenotype versus age regression. The 95% confidence intervals of slopes produced by regressing phenotypes simulated under the Brownian motion are plotted as a polygon. The usage is ...$plotSTphen(variable,plot.args=NULL,polygon.args=NULL,line.args=NULL), where variable is the index or name of the variable to be plotted, plot.args is a list of further arguments passed to the function plot, polygon.args is a list of further arguments passed to the function polygon, and line.args is a list of further arguments passed to the function lines. The functions automatically plots white points for internal nodes, red points for tips, a blue regression line, and a gray shaded polygon to represent the 95% confidence intervals of Brownian motion slopes.

$plotSTrates returns the plot of log rescaled rates versus age regression. The 95% confidence intervals of slopes produced by regressing rates simulated under the Brownian motion are plotted as a shaded area. The arguments are the same as described for $plotSTphen. In the case of multivariate y, the 2-norm vector of multiple rates (see RRphylo for details) can be plotted by setting variable = "rate" or variable = the number of actual variables + 1.

$plotSTphenNode returns plots of rescaled phenotype versus age regression for individual clades. The usage is ...$plotSTphenNode(variable,node,plot.args=NULL,lineTree.args=NULL, lineNode.args=NULL,node.palette=NULL), where variable is the same as plotSTphen and node is the vector of indices or numbers (as inputted to search.trend, to be indicated as character) of nodes to be plotted. The function allows up to nine nodes at the same time. plot.args is a list of further arguments passed to the function plot, including pch.node, a custom argument to set individual pch at nodes (its length can be one or as long as the number of nodes). lineTree.args is a list of further arguments passed to the function lines used to plot the regression line for the entire tree lineNode.args is a list of further arguments passed to the function lines used to plot the regression line for individual nodes. node.palette is the vector of colors specific to nodes points and lines. Its length can be one or as long as the number of nodes.

$plotSTratesNode returns plots of absolute rates versus age regression for individual clades. The arguments are the same as described for $plotSTphenNode. In the case of multivariate y, the 2-norm vector of multiple rates (see RRphylo for details) can be plotted by setting variable = "rate" or variable = the number of actual variables + 1.

Author(s)

Silvia Castiglione, Carmela Serio

References

Castiglione, S., Serio, C., Mondanaro, A., Di Febbraro, M., Profico, A., Girardi, G., & Raia, P. (2019) Simultaneous detection of macroevolutionary patterns in phenotypic means and rate of change with and within phylogenetic trees including extinct species. PLoS ONE, 14: e0210101. https://doi.org/10.1371/journal.pone.0210101

See Also

search.trend vignette

plotTrend vignette

Examples

## Not run: 
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
cc<- 2/parallel::detectCores()

# Extract Pterosaurs tree and data
library(ape)
extract.clade(treedino,746)->treeptero
massdino[match(treeptero$tip.label,names(massdino))]->massptero
massptero[match(treeptero$tip.label,names(massptero))]->massptero

RRphylo(tree=treeptero,y=log(massptero),clus=cc)->RRptero

search.trend(RR=RRptero, y=log(massptero), nsim=100, node=143, clus=cc,cov=NULL)->st2

plotTrend(st2)->plotST

plotST$plotSTphen(1) # to plot phenotypic trend through time for entire tree
plotST$plotSTphen("log(massptero)",plot.args=list(cex=1.2,col="blue")) # equivalent to above

plotST$plotSTrates(1) # to plot rates trend through time for entire tree

# to plot phenotypic trend through time for the clade
plotST$plotSTphenNode("log(massptero)",plot.args=list(xlab="Age",main="Phenotypic trend"),
                    lineTree.args=list(lty=1,col="pink"),lineNode.args=list(lwd=3),
                    node.palette=c("chartreuse"))

# to plot rates trend through time for the clade
plotST$plotSTratesNode("rate")

   
## End(Not run)

Description

The function is a wrapper around the function MeanMatrixStatistics from the package evolqg (Melo et al. 2015). It estimates ancestral character at internal nodes either according to Brownian Motion or by means of RRphylo (see the argument node.estimation), then performs MeanMatrixStatistics to calculate: Mean Squared Correlation, ICV, Autonomy, ConditionalEvolvability, Constraints, Evolvability, Flexibility, Pc1Percent, and Respondability. To assess the importance of phylogenetic structuring (signal) on Respondability Evolvability, and Flexibility. The function performs a randomization test by randomly shuffling the species on tree and replicating the analyses nsim times. A p-value is computed by contrasting the real metrics to the ones derived by randomization.

Usage

random.evolvability.test(tree,data,node.estimation=c("RR","BM"),
  aces=NULL,iterations=1000,nsim=100,clus=0.5)

Arguments

Value

The function returns a list object including ($means) the mean values for all statistics as produced by MeanMatrixStatistics and ($means) the significance levels for Respondability, Evolvability, and Flexibility. The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Gabriele Sansalone, Pasquale Raia

References

Melo, D., Garcia, G., Hubbe, A., Assis, A. P., & Marroig, G. (2015). EvolQG-An R package for evolutionary quantitative genetics. F1000Research, 4.

Revell, L. J. (2012) phytools: An R package for phylogenetic comparative biology (and other things). Methods in Ecology and Evolution, 3, 217-223.

See Also

RRphylo vignette

Examples

## Not run: 
 library(ape)
 library(phytools)

 rtree(30)->phy
 fastBM(phy,nsim=4)->phen

 random.evolvability.test(tree=phy,data=phen,node.estimation="RR")->rEvTest

    
## End(Not run)

Description

The function is deprecated, please check the new version of rate.map in package RRmorph.

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, PCscores, pcs, mshape, out.rem = TRUE,
  shape.diff=FALSE, show.names=TRUE)

Arguments

Details

After selecting the 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). Then, it compares the area differences between corresponding triangles of the 3D surfaces reconstructed for the species and surface of the mrca. Finally, rate.map returns a 3D plot showing such comparisons displayed on shape of the mrca used as the reference.The colour gradient goes from blue to red, where blue areas represent expansion of the mesh, while the red areas represent contractions of the mesh triangles. In the calculation of the differences of areas we supply the possibility to find and remove outliers from the vectors of areas calculated on the reference and target surfaces. We suggest considering this possibility if the mesh may contain degenerate facets. Additionally, rate.map allows to investigate the pure morphological comparison of shapes by excluding the evolutionary rate component by setting the argument show.diff = TRUE. In this case, a second 3D plot will be displayed highlighting area differences in terms of expansion (green) and contraction (yellow).

Value

The function returns a list including:

• $selected a list of PCs axes selected for higher evolutionary rates for each species.

• $surfaces a list of reconstructed coloured surfaces of the given species and of the most recent common ancestor.

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. doi:10.1111/pala.12582

See Also

RRphylo vignette ; relWarps ; procSym

Examples

## Not run: 
  data(DataSimians)
  DataSimians$pca->pcasim
  DataSimians$tree->treesim
  cc<- 2/parallel::detectCores()

  RRphylo(treesim,pcasim$PCscores,clus=cc)->RRsim

  Rmap<-rate.map(x=c("Pan_troglodytes","Gorilla_gorilla"),RR=RRsim, PCscores=pcasim$PCscores,
                 pcs=pcasim$PCs, mshape=pcasim$mshape, shape.diff = TRUE)

  
## End(Not run)

Description

The function calculates historical rates for each tip of the tree. Historical rates represent the sum of rates along subsequent branches of a lineage. The product of these rates multiplied by the relative branch lengths represents the phenotypic transformation from one node to the next one along the path. The function also provides the sum of rate modulus along lineages. This represents the total amount of evolutionary change per lineage.

Usage

rateHistory(RR)

Arguments

Value

The function returns the vector of net historical rates ($rateHistory$net.rate) and the sum of rate modulus for each tip ($rateHistory$norm.rate), and the matrix of phenotypic changes from one node to the next along each lineage (phen.path).

Author(s)

Pasquale Raia, Silvia Castiglione

Examples

## Not run: 
data("DataCetaceans")
DataCetaceans$treecet->treecet
DataCetaceans$masscet->masscet
cc<- 2/parallel::detectCores()

RRphylo(tree=treecet,y=masscet,clus=cc)->RRcet

rateHistory(RR=RRcet)->rh

    
## End(Not run)

Description

The function alters the topology and randomly removes a user-specified proportion of species from a phylogenetic tree.

Usage

resampleTree(tree,s=0.25,sdata=NULL,nodes=NULL,categories=NULL,
             swap.si=0.1,swap.si2=0.1,swap.node=NULL,nsim=1)

Arguments

Value

The function returns phylo or multiPhylo object. The output always has an attribute "Call" which returns an unevaluated call to the function.

Author(s)

Silvia Castiglione, Giorgia Girardi

See Also

search.conv vignette; overfitRR vignette; Alternative-trees vignette

Examples

## Not run: 
DataCetaceans$treecet->treecet
plot(treecet,show.tip.label = FALSE,no.margin = TRUE)
nodelabels(frame="n",col="red")

# Select two clades for stratified random sampling
clanods=c("crown_Odo"=150,"crown_Mysti"=131)
sdata1<-do.call(rbind,lapply(1:length(clanods),function(w)
  data.frame(species=tips(treecet,clanods[w]),group=names(clanods)[w])))

# generate a vector of probabilities based on body mass
prdata<-max(DataCetaceans$masscet)-DataCetaceans$masscet

# select two nodes to be preserved
nn=c(180,159)

# generate two fictional categorical vectors to be preserved
cat1<-sample(rep(c("a","b","c"),each=39),Ntip(treecet))
names(cat1)<-treecet$tip.label
cat2<-rep(c("d","e"),each=100)
names(cat2)<-sample(treecet$tip.label,100)

# 1. Random sampling
resampleTree(treecet,s=0.25,swap.si=0.3)->treecet1

# 1.1 Random sampling preserving clades
resampleTree(treecet,s=0.25,nodes=nn)->treecet2

# 2. Stratified random sampling
resampleTree(treecet,sdata = sdata1,s=0.25)->treecet3

# 2.1 Stratified random sampling preserving clades and categories
resampleTree(treecet,sdata = sdata1,s=0.25,nodes=nn,categories = list(cat1,cat2))->treecet4

# 3. Sampling conditioned on probability
resampleTree(treecet,sdata = prdata,s=0.25,nsim=5)->treecet5

## End(Not run)

Description

The function rescales all branches and leaves of the phylogenetic tree.

Usage

rescaleRR(tree,RR=NULL,height=NULL,trend=NULL,delta=NULL,kappa=NULL,lambda=NULL)

Arguments

Value

Rescaled phylogenetic tree.

Author(s)

Silvia Castiglione, Pasquale Raia

References

Castiglione, S., Serio, C., Piccolo, M., Mondanaro, A., Melchionna, M., Di Febbraro, M., Sansalone, G., Wroe, S., & Raia, P. (2020). The influence of domestication, insularity and sociality on the tempo and mode of brain size evolution in mammals. Biological Journal of the Linnean Society,132: 221-231. doi:10.1093/biolinnean/blaa186

Pagel, M. (1999). Inferring the historical patterns of biological evolution. Nature, 401:877-884.

Examples

## Not run: 
ape::rtree(100)->tree
phytools::fastBM(tree)->y
max(diag(vcv(tree)))->Hmax

RRphylo(tree,y,clus=0)->RRy
rescaleRR(tree,RR=RRy)->treeRR

rescaleRR(tree,height=Hmax/3)->tree_height

rescaleRR(tree,trend=5)->tree_trend

rescaleRR(tree,delta=0.5)->tree_delta05
rescaleRR(tree,delta=2)->tree_delta2

rescaleRR(tree,kappa=0.5)->tree_kappa

rescaleRR(tree,lambda=0.5)->tree_lambda

## End(Not run)

Description

This function takes the result list produced by evo.dir as the input, and extracts a specific subset of it. The user may specify whether to extract the set of angles between species resultant vectors and the MRCA, the size of resultant vectors, or the set of angles between species.

Usage

retrieve.angles(angles.res,wishlist=c("anglesMRCA","angleDir","angles.between.species"),
  random=c("yes","no"),focus=c("node","species","both","none"),
 node=NULL,species=NULL,csvfile=NULL)

Arguments

Details

retrieve.angles allows to focalize the extraction to a particular node, species, or both. Otherwise it returns the whole dataset.

Value

retrieve.angles outputs an object of class 'data.frame'.

If wishlist = "anglesMRCA", the data frame includes:

• MRCA the most recent common ancestor the angle is computed to

• species species ID

• angle the angle between the resultant vector of species and the MRCA

• vector.size the size of the resultant vector computed from species to MRCA

If wishlist = "angleDir", the data frame includes:

• MRCA the most recent common ancestor the vector is computed to

• species species ID

• angle.direction the angle between the vector of species and a fixed reference

• vector.size the size of the vector of species

If wishlist = "angles.between.species", the data frame includes:

• MRCA the most recent common ancestor the vector is computed from

• species pair IDs of the species pair the "angle between species" is computed for

• angleBTWspecies2MRCA angle between species resultant vectors to MRCA

• anglesBTWspecies angle between species resultant vectors

Author(s)

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Examples

## Not run: 
    data("DataApes")
    DataApes$PCstage->PCstage
    DataApes$Tstage->Tstage

    cc<- 2/parallel::detectCores()
    RRphylo(tree=Tstage,y=PCstage,clus=cc)->RRstage

# Case 1. "evo.dir" without performing randomization
    evo.dir(RRstage,angle.dimension="rates",pair.type="node",
    node=  57,random="no")->ed1

 # Case 1.1 angles and sizes of resultant vectors between individual species and the MRCA:
  # for a focal node
    retrieve.angles(ed1,wishlist="anglesMRCA",random="no",focus="node",
    node=68)->ra1
  # for a focal species
    retrieve.angles(ed1,wishlist="anglesMRCA",random="no",focus="species",
    species="Sap")->ra2
  # for both focal node and species
    retrieve.angles(ed1,wishlist="anglesMRCA",random="no",focus="both",
    node=68,species="Sap")->ra3
  # without any specific requirement
    retrieve.angles(ed1,wishlist="anglesMRCA",random="no",focus="none")->ra4

 # Case 1.2 angles and sizes of vectors between individual species
 #and a fixed reference vector:
  # for a focal node
    retrieve.angles(ed1,wishlist="angleDir",random="no",focus="node",
    node=68)->ra5
  # for a focal species
    retrieve.angles(ed1,wishlist="angleDir",random="no",focus="species",
    species="Sap")->ra6
  # for both focal node and species
    retrieve.angles(ed1,wishlist="angleDir",random="no",focus="both",
    node=68,species="Sap")->ra7
  # without any specific requirement
    retrieve.angles(ed1,wishlist="angleDir",random="no",focus="none")->ra8

 # Case 1.3 angles between species resultant vectors:
  # for a focal node
    retrieve.angles(ed1,wishlist="angles.between.species",random="no",
    focus="node", node=68)->ra9
  # for a focal species
    retrieve.angles(ed1,wishlist="angles.between.species",random="no",
    focus="species", species="Sap")->ra10
  # for both focal node and species
    retrieve.angles(ed1,wishlist="angles.between.species",random="no",
    focus="both",node=68,species="Sap")->ra11
  # without any specific requirement
    retrieve.angles(ed1,wishlist="angles.between.species",random="no",
    focus="none")->ra12


# Case 2. "evo.dir" with performing randomization
    evo.dir(RRstage,angle.dimension="rates",pair.type="node",node=57,
    random="yes",nrep=10)->ed7

 # Case 2.1 angles and sizes of resultant vectors between individual species and the MRCA:
  # for a focal node
    retrieve.angles(ed7,wishlist="anglesMRCA",random="yes",focus="node",
    node=68)->ra13
  # for a focal species
    retrieve.angles(ed7,wishlist="anglesMRCA",random="yes", focus="species",
    species="Sap")->ra14
  # for both focal node and species
    retrieve.angles(ed7,wishlist="anglesMRCA",random="yes",focus="both",
    node=68,species="Sap")->ra15
  # without any specific requirement
    retrieve.angles(ed7,wishlist="anglesMRCA",random="yes",focus="none")->ra16

 # Case 2.2 angles and sizes of vectors between individual species and a fixed reference vector:
  # for a focal node
    retrieve.angles(ed7,wishlist="angleDir",random="yes",focus="node",
    node=68)->ra17
  # for a focal species
    retrieve.angles(ed7,wishlist="angleDir",random="yes",focus="species",
    species="Sap")->ra18
  # for both focal node and species
    retrieve.angles(ed7,wishlist="angleDir",random="yes",focus="both",
    node=68, species="Sap")->ra19
  # without any specific requirement
    retrieve.angles(ed7,wishlist="angleDir",random="yes",focus="none")->ra20

 # Case 2.3 retrieve angles between species resultant vectors:
  # for a focal node
    retrieve.angles(ed7,wishlist="angles.between.species",random="yes",
    focus="node", node=68)->ra21
  # for a focal species
    retrieve.angles(ed7,wishlist="angles.between.species",random="yes",
    focus="species", species="Sap")->ra22
  # for both focal node and species
    retrieve.angles(ed7,wishlist="angles.between.species",random="yes",
    focus="both",node=68,species="Sap")->ra23
  # without any specific requirement
    retrieve.angles(ed7,wishlist="angles.between.species",random="yes",
    focus="none")->ra24
    
## End(Not run)

Description

The function RRphylo (Castiglione et al. 2018) performs the phylogenetic ridge regression. It takes a tree and a vector of tip data (phenotypes) as entries, calculates the regularization factor, produces the matrices of tip to root (makeL), and node to root distances (makeL1), the vector of ancestral state estimates, the vector of predicted phenotypes, and the rates vector for all the branches of the tree. For multivariate data, rates are given as both one vector per variable, and as a multivariate vector obtained by computing the Euclidean Norm of individual rate vectors.

Usage

RRphylo(tree,y,cov=NULL,rootV=NULL,aces=NULL,x1=NULL,
  aces.x1=NULL,clus=0.5,verbose=FALSE)

Arguments