search.conv  R Documentation 
The function scans a phylogenetic tree looking for morphological convergence between entire clades or species evolving under specific states.
search.conv(RR=NULL,tree=NULL,y,nodes=NULL,state=NULL,aceV=NULL, min.dim=NULL,max.dim=NULL,min.dist=NULL,declust=FALSE,nsim=1000,rsim=1000, clus=.5,filename)
RR 
an object produced by 
tree 
a phylogenetic tree. The tree needs not to be ultrametric or fully dichotomous. This is not indicated if convergence among clades is tested. 
y 
a multivariate phenotype. The object 
nodes 
node pair to be tested. If unspecified, the function
automatically searches for convergence among clades. Notice the node number
must refer to the dichotomic version of the original tree, as produced by

state 
the named vector of tip states. The function tests for convergence within a single state or among different states (this latter case is especially meant to test for iterative evolution as for example the appearance of repeated morphotypes into different clades). In both cases, the state for nonfocal species (i.e. not belonging to any convergent group) must be indicated as "nostate". 
aceV 
phenotypic values at internal nodes. The object 
min.dim 
the minimum size of the clades to be compared. When

max.dim 
the maximum size of the clades to be compared. When

min.dist 
the minimum distance between the clades to be compared. When

declust 
if species under a given state (or a pair of states) to be
tested for convergence are phylogenetically closer than expected by chance,
trait similarity might depend on proximity rather than true convergence. In
this case, by setting 
nsim 
number of simulations to perform sampling within the theta random distribution. It is set at 1000 by default. 
rsim 
number of simulations to be performed to produce the random distribution of theta values. It is set at 1000 by default. 
clus 
the proportion of clusters to be used in parallel computing. To
run the singlethreaded version of 
filename 
a character indicating the name of the pdf file and the path where it is to be saved. If no path is indicated the file is stored in the working directory 
Regardless the case (either 'state' or 'clade'), the function stores
a plot into the folder specified by filename
. If convergence among
clades is tested, the clade pair plotted corresponds to those clades with
the smallest $average distance from group centroid
. The figure shows
the Euclidean distances computed between the MRCAs of the clades and the
mean Euclidean distance computed between all the tips belonging to the
converging clades, as compared to the distribution of these same figures
across the rest of the tree. Furthermore, the function stores the PC1/PC2
plot obtained by PCA of the species phenotypes. Convergent clades are
indicated by colored convex hulls. Large colored dots represent the mean
phenotypes per clade (i.e. their group centroids). Eventually, a modified
traitgram plot is produced, highlighting the branches of the clades found
to converge. In both PCA and traitgram, asterisks represent the ancestral
phenotypes of the individual clades. If convergence among states is tested,
the function produces a PC plot with colored convex hulls enclosing species
belonging to different states. Furthermore, it generates circular plots of
the mean angle between states (blue lines) and the range of random angles
(gray shaded area). The pvalue for the convergence test is printed within
the circular plots.
If convergence between clades is tested, the function returns a list including:
$node pairs: a dataframe containing for each pair of nodes:
ang.bydist.tip: the mean theta angle between clades divided by the time distance.
ang.conv: the mean theta angle between clades plus the angle between aces, divided by the time distance.
ang.ace: the angle between aces.
ang.tip: the mean theta angle between clades.
nod.dist: the distance intervening between clades in terms of number of nodes.
time.dist: the time distance intervening between the clades.
p.ang.bydist: the pvalue computed for ang.bydist.tip.
p.ang.conv: the pvalue computed for ang.conv.
clade.size: the size of clades.
$node pairs comparison: pairwise comparison between significantly convergent pairs (all pairs if no instance of significance was found) performed on the distance from group centroids (the mean phenotype per clade).
$average distance from group centroids: smaller average distances mean less variable phenotypes within the pair.
If convergence between (or within a single state) states is tested, the function returns a dataframe including for each pair of states (or single state):
ang.state: the mean theta angle between species belonging to different states (or within a single state).
ang.state.time: the mean of theta angle between species belonging to different states (or within a single state) divided by time distance.
p.ang.state: the pvalue computed for ang.state.
p.ang.state.time: the pvalue computed for ang.state.time.
Silvia Castiglione, Carmela Serio, Pasquale Raia, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto, Paolo Piras, Davide Tamagnini
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
## Not run: data("DataFelids") DataFelids$PCscoresfel>PCscoresfel DataFelids$treefel>treefel DataFelids$statefel>statefel cc< 2/parallel::detectCores() RRphylo(treefel,PCscoresfel,clus=cc)>RRfel ## Case 1. searching convergence between clades # by setting min.dist as node distance search.conv(RR=RRfel, y=PCscoresfel, min.dim=5, min.dist="node9", filename = paste(tempdir(), "SCclade_nd", sep="/"),clus=cc) # by setting min.dist as time distance search.conv(RR=RRfel, y=PCscoresfel, min.dim=5, min.dist="time38", filename = paste(tempdir(), "SCclade_td", sep="/"),clus=cc) ## Case 2. searching convergence within a single state search.conv(tree=treefel, y=PCscoresfel, state=statefel,declust=TRUE, filename = paste(tempdir(), "SCstate", sep="/"),clus=cc) ## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.