% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bind_tip.R
\name{bind_tip}
\alias{bind_tip}
\title{Bind a tip to a phylogeny}
\usage{
bind_tip(
  tree = NULL,
  where,
  tip_label,
  frac = 0.5,
  new_node_above = FALSE,
  node_label = NULL,
  return_tree = TRUE,
  tree_tbl = NULL,
  node_heights = NULL,
  use_castor = TRUE,
  sequential = TRUE
)
}
\arguments{
\item{tree}{A phylogeny, with class of "phylo".}

\item{where}{Location where to insert the tip. It can be either tip label or node label, but must be characters. If the location does not have a name, assign it first.}

\item{tip_label}{Name of the new tip inserted.}

\item{frac}{The fraction of branch length, must be between 0 and 1. This only applies when location is a tip or \code{new_node_above = TRUE}. The distance from the new inserted node to the location (a node or a tip) is the branch length of the location * (1 - frac).}

\item{new_node_above}{Whether to insert the new node above when the location is a node? Default is \code{FALSE}, which will attach the new tip to the location node.}

\item{node_label}{Name of the new node created. This only applies when location is a tip or \code{new_node_above = TRUE}.}

\item{return_tree}{Whether to return a phylogeny with class "phylo?" Default is \code{TRUE}. Otherwise, it will return a data frame.}

\item{tree_tbl}{A tibble version of the tree, optional.}

\item{node_heights}{A named numeric vector of node hieghts of the tree, generated by \code{\link[ape:branching.times]{ape::branching.times()}}. It is also optional if \code{tree} is specified; but required if \code{tree_tbl} is specified.}

\item{use_castor}{Whether to use package \code{castor} to get the phylogeny at a node; it is faster than \code{tidytree::offspring} to figure out what are the tip offsprings at a node.}

\item{sequential}{Whether to add the tip with sequential node number in the edge matrix. For example, if we want to bind a tip to a clade and the node number of the tips of this clade is from 101 to 150. We can set the node id of the new tip to 151 and push all the remaining node id to 1 after their current values. This will require us to find out the node ids of all tips that are descents of the node where we want to bind the new tip to, and it can be time costly. Yet I am still not sure whether this is necessary. Normally, the node ids of the \code{phylo} class are sequential. Therefore, the default value here is \code{TRUE}. If set to \code{FALSE}, we can just assign the id of the new tip to Ntip + 1 to save time. In addition, we probably don't need to order the node column of the edge matrix every time.}
}
\value{
Either a phylogeny or a data frame, which can be then converted to a phylogeny later.
}
\description{
Graft a tip to a phylogeny at location specified.
}
\examples{
tr <- ape::read.tree(text = "((A:1,B:1):1,C:2);")
tr$node.label <- c("root", "N1")
bind_tip(tr, where = "N1", tip_label = "D")
tr_tbl <- tidytree::as_tibble(tr)
node_hts <- ape::branching.times(tr)
bind_tip(tree_tbl = tr_tbl, where = "N1",
         tip_label = "D", node_heights = node_hts)
}
