phyMap3ax: Summarize three traits or axes as RGB colors and map them on...

View source: R/phyMap3ax.R

phyMap3axR Documentation

Summarize three traits or axes as RGB colors and map them on a phylogeny

Description

This functions first rescales three given traits are RGB color codes, then map them on a phylogeny, estimating or using given ancestral estimates.

Usage

phyMap3ax(tree, data, method, method.opt, anc.states, res, plot.opt)

Arguments

tree

The tree of format phylo to map the data on

data

The data to map on the tree. Must be a data frame or a matrix with three columns.

method

Optional. The method to use to reconstruct the ancestral states, if those are not provided. Available methods are: RRphylo (the default), ace, anc.ML, anc.trend, anc.Bayes, and fastAnc. See details for these methods.

method.opt

Optional. The options to the method used if some customization is desired. Must be a list of named elements, and these names should be the options of the previously called method.

anc.states

Optional. The ancestral states to the data. As for data, must be a three-columned data frame or matrix.

res

Optional. The resolution of the coloring of the tree edges (i.e., the highest the resolution, the smoothest the color gradient). Default is 1000.

plot.opt

Optional. Options to be passed for the plot. See contMap and plot.contMap help pages.

Details

The aim of this function is to provide a visually intuitive summary of the information given by three traits or three axes (for instance, the three first axes of a PCA). To do this, the three variables are rescaled as 0-255 RGB values to summarize each point as a color code. Then, the aim is to give the color information of each taxon on a phylogeny, to be able to visually compare the phylogenetic (i.e., according to branches) and the statistical (i.e., according to colours) clusterings. To have a smooth effect, it is better to also have ancestral estimates. These can be given as parameters of the function, or they can be estimated using different methods.
The method for reconstructing ancestral states (if not provided) is by default the phylogenetic ridge regression (see RRphylo). Other methods are available, especially those relying on maximum lilkelihood estimations, such as ace (ML estimation under Brownian motion model), fastAnc (ML estimation using Felsenstein's contrasts), anc.ML (ML estimation under various models such as Brownian motion, Ornstein-Uhlenbeck process, "early burst" model...), anc.trend (ML estimation under Brownian motion model with a trend), anc.Bayes (using Bayesian MCMC under adjustable Brownian motion model).

Examples

# Simulate three traits, then summarize and map then on a phylogeny

n<-50 # Number of tips
require(ape)
require(phytools)
tree<-rtree(n) # Generating random tree
a<-runif(n,min=10,max=50) # Generating three different trait within a given range
b<-runif(n,min=1,max=5)
c<-runif(n,min=10,max=20)
a<-sort(a) # Sorting values is actually adding a phylogenetic effect that will be visually from bottom to top of the phylogram; not sorting them allows for non-phylogenetic distribution
b<-sort(b)
# c<-sort(c)
names(a)<-names(b)<-names(c)<-tree$tip.label # Assigning tip names to data
data<-data.frame(a,b,c) # Generating dataset
method<-"fastAnc" # Choosing a method for reconstructing ancestral states

phyMap3ax(tree,data,method) # And here is the phylogram with the branches coloured according to the values of the three traits

# Simulate a general phylogenetic effect with some "outliers"

require(RRphylo)
n<-50 # Number of tips
tree<-rtree(n) # Generating random tree
a<-setBM(tree,s2=2,a=10,type="brown") # Generating three different traits with phylogenetic effect under Brownian motion regime
b<-setBM(tree,s2=20,a=1,type="brown")
c<-setBM(tree,s2=0.2,a=0,type="brown")
out<-sample(1:n,round(n/10,0),replace=FALSE) # Randomly choose 10% of taxa that have weird values
a[out]<-runif(length(out),min=min(a)-(max(a)-min(a))*2,max=max(a)+(max(a)-min(a))*2) # Assign to the 'weird taxa' values within a larger range than the original trait range
b[out]<-runif(length(out),min=min(b)-(max(b)-min(b))*2,max=max(b)+(max(b)-min(b))*2)
c[out]<-runif(length(out),min=min(c)-(max(c)-min(c))*2,max=max(c)+(max(c)-min(c))*2)
names(a)<-names(b)<-names(c)<-tree$tip.label # Assigning tip names to data
data<-data.frame(a,b,c) # Generating dataset
method<-"fastAnc" # Choosing a method for reconstructing ancestral states

phyMap3ax(tree,data,method) # Here is the plot of the three traits
if(require(ULT)){tiplabels(ULT::binarize(c(1:n)%in%out,zero=FALSE,one=TRUE,output=c("","< HERE")),adj=-0.5,frame="none",col="red",font=2)} # And here are the 'weird taxa'

# Simulate a general phylogenetic effect with some convergent taxa

require(RRphylo)
n<-50 # Number of tips
tree<-rtree(n) # Generating random tree
a<-setBM(tree,s2=2,a=10,type="brown") # Generating three different traits with phylogenetic effect under Brownian motion regime
b<-setBM(tree,s2=20,a=1,type="brown")
c<-setBM(tree,s2=0.2,a=0,type="brown")
conv<-sample(1:n,round(n/10,0),replace=FALSE) # Randomly choose 10% of taxa that converge
out_a<-sample(c(runif(1,min=min(a)-(max(a)-min(a))*2,max=min(a)),runif(1,min=max(a),max=max(a)+(max(a)-min(a))*2)),1) # Choosing an extreme (i.e., largely outside from the variation range) of the trait 'a'
a[conv]<-out_a+runif(length(conv),min=out_a-(max(a)-min(a))/2,max=out_a+(max(a)-min(a))/2) # Randomly assign to the convergent taxa values floating around the extreme value
out_b<-sample(c(runif(1,min=min(b)-(max(b)-min(b))*2,max=min(b)),runif(1,min=max(b),max=max(b)+(max(b)-min(b))*2)),1)
b[conv]<-out_b+runif(length(conv),min=out_b-(max(b)-min(b))/2,max=out_b+(max(b)-min(b))/2)
out_c<-sample(c(runif(1,min=min(c)-(max(c)-min(c))*2,max=min(c)),runif(1,min=max(c),max=max(c)+(max(c)-min(c))*2)),1)
c[conv]<-out_c+runif(length(conv),min=out_c-(max(c)-min(c))/2,max=out_c+(max(c)-min(c))/2)
names(a)<-names(b)<-names(c)<-tree$tip.label # Assigning tip names to data
data<-data.frame(a,b,c) # Generating dataset
method<-"fastAnc" # Choosing a method for reconstructing ancestral states

phyMap3ax(tree,data,method) # Here is the plot of the three traits
if(require(ULT)){tiplabels(ULT::binarize(c(1:n)%in%conv,zero=FALSE,one=TRUE,output=c("","< HERE")),adj=-0.5,frame="none",col="red",font=2)} # And here are the convergent taxa


jacobmaugoust/ULT documentation built on May 16, 2023, 1:29 p.m.