CollessLike (version 2.0)

distribution: Plot the distribution of Colless-Like, Sackin and cophenetic normalized balance indices under the alpha-gamma model and computes the percentile of a tree from previous distributions.

Description

Given alpha, gamma and a phylogenetic tree, plot the distribution of the Colless-Like, Sackin and cophenetic normalized balance indices under the alpha-gamma model and computes the percentile of that tree of the previous normalized balance indices under the alpha-gamma model.

Usage

distribution(tree, alpha = NA, gamma = NA, set.indices = NULL,
  new.simulation = FALSE, repetitions = 1000,
  legend.location = "topright", cex = 0.75, percentile.plot = FALSE,
  db.path = getwd())

Arguments

tree

a single phylogenetic tree. It can be entered as a string in Newick format, as a "phylo" object (ape package) or as an "igraph" object (igraph package).

alpha

parametrer of the alpha-gamma model, between 0 and 1.

gamma

parametrer of the alpha-gamma model, between 0 and alpha.

set.indices

If NULL (default) the values of the balance indices are taken from stored data or from a new simulated data (See "Details"). If not, it must be a 3-column data.frame with the three balance indices (Colles-like, Sackin, Cophenetic). See indices.simulation.

new.simulation

if FALSE(default) the values of the balance indices are taken from a data.frame entered by the user or from our database. If TRUE, the values of the balance indices are computed from a new simulation. See indices.simulation.

repetitions

if the value of the new.simulation parameter is TRUE, the number of trees to be generated.

legend.location

location of the legend. See "Details".

cex

expansion factor of the legend. See "Details".

percentile.plot

if FALSE (default), density plots of the normalized balance indices are shown. if TRUE, percentiles plots of the normalized balance indices are shown.

db.path

the current working directory. If our database is used, the db.path parameter should be the directory where the database is located.

Value

A numeric vector with the three percentiles.

Details

Two plots are available: one represents the percentile plots of the normalized balance indices (percentile.plot=TRUE), and the other one represents the density plots of the normalized balance indices (percentile.plot=FALSE).

The trees stored in our database have between 3 and 50 leaves and the values of the parameters alpha and gamma are in {0,0.1,...,1} such that gamma \(\le\) alpha. If the introduced parameters are not in the list, a new computation is done with them and a new dataset of trees is generated, and their indices are also computed. The number of trees generated can be modified by the parameter repetitions (see indices.simulation for more information). This computation may take some time, therefore you can computate them separately with indices.simulation, save their values and then call this function by setting the parameter set.indices=NULL.

Our database is available to download at https://github.com/LuciaRotger/CollessLike/tree/master/CollessLikeDataBase.

The legend is placed with the graphics function legend(), so its location can be specified by setting legend.position to a single keyword from the list "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right" and "center". The expansion factor for the legend is controlled by the parameter cex, by default cex=1. See legend.

References

B. Chen, D. Ford, M. Winkel, A new family of Markov branching trees: the alpha-gamma model. Electr. J. Probab. 14 (2009), 400-430.

A. Mir, F. Rossello, L.Rotger, Sound Colless-like balance indices for multifurcating phylogenetic trees.PloS ONE 13 (2018), e0203401.

A. Mir, F. Rossello, L.Rotger, A new balance index for phylogenetic trees. Mathematical Biosciences 241 (2013), 125-136.

M. J. Sackin, "Good" and "bad" phenograms. Sys. Zool, 21 (1972), 225-226.

See Also

legend, indices.simulation, balance.indices

Examples

# NOT RUN {
#The parameter folder contains the location of the database
#If not specified folder=getwd()

## Different ways to introduce the tree
#From a newick string
# }
# NOT RUN {
distribution("(1,2,3,4,5);",0.5,0.3,db.path=folder)
# }
# NOT RUN {
distribution("(1,(2,(3,(4,5))));",0.5,0.3,db.path=folder)
# }
# NOT RUN {
#From a phylo object
# }
# NOT RUN {
require(ape)
# }
# NOT RUN {
random.tree = rtree(5,rooted=TRUE)
# }
# NOT RUN {
distribution(random.tree,0.5,0.3,db.path=folder)
# }
# NOT RUN {
#An example of a tree generated by the alpha-gamma model (igraph object)
# }
# NOT RUN {
a.g.tree = a.g.model(5,0.5,0.3)
# }
# NOT RUN {
distribution(a.g.tree,0.5,0.3,db.path=folder)
# }
# NOT RUN {
## Different indices data
# From our data base
# }
# NOT RUN {
distribution(a.g.tree,0.5,0.3,db.path=folder)
# }
# NOT RUN {
# From a data.frame generated by 'indices.simulation'
# ('Repetitions' set as 10 for a fast example)
# }
# NOT RUN {
indices.data = indices.simulation(5,0.5,0.3,10)
# }
# NOT RUN {
distribution(a.g.tree,0.5,0.3,set.indices=indices.data) 
# }
# NOT RUN {
# Allow the function to do a new generation of data and compute their indices
# }
# NOT RUN {
distribution(a.g.tree,0.5,0.3,new.simulation=TRUE,repetitions=10)
# }
# NOT RUN {
# WARNING! it might take a long time, it depends on the parameters 
# 'n' (number of leaves) and 'repetition' (number of repetitions)

# }