% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bind_tip.R
\name{bind_tip_df}
\alias{bind_tip_df}
\title{Bind a tip to a phylogeny (data frame version)}
\usage{
bind_tip_df(
  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 = FALSE
)
}
\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.}
}
\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_df(tr, where = "N1", tip_label = "D")
tr_tbl <- tidytree::as_tibble(tr)
node_hts <- ape::branching.times(tr)
bind_tip_df(tree_tbl = tr_tbl, where = "N1",
            tip_label = "D", node_heights = node_hts)
}
