RRphylo (version 2.8.0)

tree.merger: Fast addition of tips and clades on an existing tree

Description

The function attaches new tips and/or clades derived from a source phylogeny to a pre-existing backbone tree.

Usage

tree.merger(backbone,data,source.tree=NULL,age.offset=NULL,tip.ages =
  NULL, node.ages = NULL,min.branch=NULL,plot=TRUE,filename=NULL)

Value

Merged phylogenetic tree.

Arguments

backbone

the backbone tree to attach tips/clades on.

data

a dataset including as columns:

1. reference = the reference tip or clade where 'bind' must be attached;

2. poly = logical specifying if 'bind' and 'reference' should form a polytomous clade.

See details for further explanations.

source.tree

the tree where 'bind' clades are to be extracted from. If no clade has to be attached, it can be left unspecified.

age.offset

if the most recent age (i.e. the maximum distance from the tree root) differs between the source and the backbone trees, the “age.offset” is the difference between them in this exact order (source minus backbone). It is positive when the backbone tree attains younger age than the source tree, and vice-versa.

tip.ages

as in scaleTree, a named vector including the ages (i.e. the time distance from the youngest tip within the tree) of the tips. If unspecified, the function assumes all the tips on the backbone tree are correctly placed and places all the new tips at the maximum distance from the tree root (i.e. the present if the tips are extant).

node.ages

as in scaleTree, a named vector including the ages (i.e. the time distance from the youngest tip within the tree) of the nodes. The nodes must be defined by collating the names of the two phylogenetically furthest tips it subtends to, separated by the "-" symbol (see examples). If no calibration date for nodes is supplied, the function may shift the node position back in time as to place new tips/clades and to fit tip ages.

min.branch

has been deprecated.

plot

if TRUE, the function produces an interactive plotting device to check the placing of each bind.

filename

if plot=TRUE and provided a filename (with or without the path), the function stores a pdf file showing the plot of the entire phylogeny.

Author

Silvia Castiglione, Carmela Serio, Pasquale Raia

Details

The function attaches tips and/or clades from the source tree to the backbone tree according to the data object. Within the latter, a clade, either to be bound or to be the reference, must be indicated by collating the names of the two phylogenetically furthest tips belonging to it, separated by the "-" symbol. Alternatively, if backbone$node.label/source.tree$node.label is not NULL, a bind/reference clade can be indicated as "Clade NAMEOFTHECLADE" when appropriate. Similarly, an entire genus on both the backbone and the source.tree can be indicated as "Genus NAMEOFTHEGENUS" (see examples below). Duplicated 'bind' produce error. Tips/clades set to be attached to the same 'reference' with 'poly=FALSE' are considered to represent a polytomy. Tips set as 'bind' which are already on the backbone tree are removed from the latter and placed according to the 'reference'. See examples and vignette for clarifications.

References

Castiglione, S., Serio, C., Mondanaro, A., Melchionna, M., & Raia, P. (2022). Fast production of large, time-calibrated, informal supertrees with tree.merger. Palaeontology, 65: e12588.https://doi.org/10.1111/pala.12588

See Also

tree.merger vignette; scaleTree vignette;

Examples

 if (FALSE) {
 require(ape)
 DataCetaceans$treecet->tree
 tree$node.label[131-Ntip(tree)]<-"Crown_Mysticeti"

 data.frame(bind=c("Clade Crown_Mysticeti",
                   "Aetiocetus_weltoni",
                   "Saghacetus_osiris",
                   "Zygorhiza_kochii",
                   "Ambulocetus_natans",
                   "Genus Kentriodon",
                   "Tursiops_truncatus-Delphinus_delphis",
                   "Kogia_sima",
                   "Eurhinodelphis_cristatus",
                   "Grampus_griseus",
                   "Eurhinodelphis_bossi"),
            reference=c("Fucaia_buelli-Aetiocetus_weltoni",
                        "Aetiocetus_cotylalveus",
                        "Fucaia_buelli-Tursiops_truncatus",
                        "Saghacetus_osiris-Fucaia_buelli",
                        "Dalanistes_ahmedi-Fucaia_buelli",
                        "Clade Delphinida",
                        "Stenella_attenuata-Stenella_longirostris",
                        "Kogia_breviceps",
                        "Eurhinodelphis_longirostris",
                        "Globicephala_melas-Pseudorca_crassidens",
                        "Eurhinodelphis_longirostris"),
            poly=c(FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE,
                   FALSE))->dato

 c(Aetiocetus_weltoni=28.0,
   Saghacetus_osiris=33.9,
   Zygorhiza_kochii=34.0,
   Ambulocetus_natans=40.4,
   Kentriodon_pernix=15.9,
   Kentriodon_schneideri=11.61,
   Kentriodon_obscurus=13.65,
   Eurhinodelphis_bossi=13.65,
   Eurhinodelphis_cristatus=5.33)->tip.ages
 c("Ambulocetus_natans-Fucaia_buelli"=52.6,
   "Balaena_mysticetus-Caperea_marginata"=21.5)->node.ages

 # remove some tips from the original tree and create a source tree
 drop.tip(tree,c(names(tip.ages),
                 tips(tree,131)[-which(tips(tree,131)%in%
                               c("Caperea_marginata","Eubalaena_australis"))],
                 tips(tree,195)[-which(tips(tree,195)=="Tursiops_aduncus")]))->backtree
 drop.tip(tree,which(!tree$tip.label%in%c(names(tip.ages),
                                          tips(tree,131),
                                          tips(tree,195))))->sourcetree

 plot(backtree,cex=.6)
 plot(sourcetree,cex=.6)

 tree.merger(backbone=backtree,data=dato,source.tree=sourcetree,
             tip.ages=tip.ages,node.ages = node.ages, plot=TRUE)->treeM
   }