distribution: Plot the distribution of Colless-Like, Sackin and cophenetic...
In LuciaRG/CollessLike: Distribution and Percentile of Sackin, Cophenetic and Colless-Like Balance Indices of Phylogenetic Trees

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

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())

`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.

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 ≤ 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.

A numeric vector with the three percentiles.

Lucia Rotger

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.

legend, indices.simulation, balance.indices

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

## Different ways to introduce the tree
#From a newick string
distribution("(1,2,3,4,5);",0.5,0.3,db.path=folder)
distribution("(1,(2,(3,(4,5))));",0.5,0.3,db.path=folder)

#From a phylo object
require(ape)
random.tree = rtree(5,rooted=TRUE)
distribution(random.tree,0.5,0.3,db.path=folder)

#An example of a tree generated by the alpha-gamma model (igraph object)
a.g.tree = a.g.model(5,0.5,0.3)
distribution(a.g.tree,0.5,0.3,db.path=folder)

## Different indices data
# From our data base
distribution(a.g.tree,0.5,0.3,db.path=folder)

# From a data.frame generated by 'indices.simulation'
# ('Repetitions' set as 10 for a fast example)
indices.data = indices.simulation(5,0.5,0.3,10)
distribution(a.g.tree,0.5,0.3,set.indices=indices.data) 

# Allow the function to do a new generation of data and compute their indices
distribution(a.g.tree,0.5,0.3,new.simulation=TRUE,repetitions=10)
# WARNING! it might take a long time, it depends on the parameters 
# 'n' (number of leaves) and 'repetition' (number of repetitions)