plotConv function

Graphical representation of search.conv results

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

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

Arguments

• SC: an object produced by search.conv.
• y: the multivariate phenotype used to perform search.conv.
• variable: the index of result to plot. If convergence between clades is inspected, this is the position within the SC$'average distance from group centroids' vector of the clade pair to be plotted. In the case of convergence between states, this is the number of the line of SC$state.res where results for the state pair are returned.
• RR: the object produced by RRphylo used to perform search.conv. This is not indicated if convergence between states is tested.
• state: the named vector of tip states used to perform search.conv. This is not indicated if convergence between clades is tested.
• aceV: phenotypic values at internal nodes to be provided if used to perform search.conv.

Returns

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.argsis a list of further arguments passed to the functionhist, and line.argsis a list of further arguments passed to the functionlines`.

‘$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.

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)

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

c("list("search.conv")", " vignette")

c("list("plotConv")", " vignette")

Author(s)

Silvia Castiglione