% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_one_tree.R
\name{get_one_tree}
\alias{get_one_tree}
\title{Derive a phylogeny from a mega-tree}
\usage{
get_one_tree(
  sp_list,
  tree,
  taxon,
  scenario = c("at_basal_node", "random_below_basal"),
  show_grafted = FALSE,
  tree_by_user = FALSE,
  .progress = "text",
  dt = TRUE
)
}
\arguments{
\item{sp_list}{A character vector or a data frame with at least three columns: species, genus, family. Species column
holds the species for which we want to have a phylogeny. It can also have two optional columns:
close_sp and close_genus. We can specify the closest species/genus of the species based on
expert knowledge. If specified, the new species will be grafted to that particular location.

It can also be a string vector if \code{taxon} is specified. Though it probably is a better idea
to prepare your data frame with \code{\link[=sp_list_df]{sp_list_df()}}. The string vector can also have the same format
as that required by Phylomatic (i.e., family/genus/genus_sp).}

\item{tree}{A mega-tree with class \code{phylo} or a list of mega-trees with class \code{multiPhylo}.
Optional if \code{taxon} is specified, in which case, a default
mega-phylogeny (or a set of 100 randomly selected posterior phylogenies) will be used
(see their own documentations from the \code{megatrees} package).
\itemize{
\item For amphibian, the mega-trees are loaded via \code{\link[megatrees:get_tree_amphibian_n100]{megatrees::get_tree_amphibian_n100()}}.
\item For bee, the mega-tree is \link[megatrees:tree_bee]{megatrees::tree_bee}, with the bootstrap option loaded via \code{\link[megatrees:get_tree_bee_n100]{megatrees::get_tree_bee_n100()}}.
\item For butterfly, the mega-tee is \link[megatrees:tree_butterfly]{megatrees::tree_butterfly}.
\item For bird, the mega-trees are loaded via \code{\link[megatrees:get_tree_bird_n100]{megatrees::get_tree_bird_n100()}}.
\item For fish, the mega-tree is \link[megatrees:tree_fish_12k]{megatrees::tree_fish_12k}, with the all-taxon option loaded via \code{\link[megatrees:get_tree_fish_32k_n50]{megatrees::get_tree_fish_32k_n50()}}.
\item For mammal, the default mega-trees are loaded via \code{\link[megatrees:get_tree_mammal_n100_vertlife]{megatrees::get_tree_mammal_n100_vertlife()}}, with \code{\link[megatrees:get_tree_mammal_n100_phylacine]{megatrees::get_tree_mammal_n100_phylacine()}} be the other option.
\item For plant, the default mega-tree is \link[megatrees:tree_plant_otl]{megatrees::tree_plant_otl} (Smith and Brown 2018);
\link[megatrees:tree_plant_Carruthers]{megatrees::tree_plant_Carruthers} (Carruthers et al. 2026) is also available; 100 posterior trees are loaded via
\code{\link[megatrees:get_tree_plant_n100_Carruthers]{megatrees::get_tree_plant_n100_Carruthers()}}.
\item For reptile, the mega-trees are loaded via \code{\link[megatrees:get_tree_reptile_n100]{megatrees::get_tree_reptile_n100()}}.
\item For shark, ray, and chimaeras, the mega-trees are loaded via \code{\link[megatrees:get_tree_shark_ray_n100]{megatrees::get_tree_shark_ray_n100()}}.
}}

\item{taxon}{The taxon of species in the \code{sp_list}. Currently, can be \code{amphibian}, \code{bird}, \code{fish}, \code{mammal}, \code{plant}, \code{reptile}, or \code{shark_ray}.}

\item{scenario}{How to insert a species into the mega-tree?
\itemize{
\item In both scenarioes, if there is only 1 species in the genus or family, a new node will be inserted to
the middle point of this only species' branch length and the new species will be attached to this new
node.
\item If \code{scenario = "at_basal_node"}, a species is attached to the basal node of the same genus or the same family
if the mega-tree does not have any species of this genus.
\item If \code{scenario = "random_below_basal"}, a species is attached to a randomly selected node that is at or below the
basal node of the same genus of the same family if the mega-tree does not have any species in this genus.
The probability of node been selected is proportional to its branch length.
Because of the random sampling involved, you may want to run several times to get a collection of
derived phylogenies.
}}

\item{show_grafted}{Whether to indicate which species was grafted onto the mega-tree.
If \code{TRUE}, a \code{*} will be appended to the species name on the tip if it was grafted within
the same genus; \verb{**} will be appended if it was grafted within the same family.}

\item{tree_by_user}{Is the mega-tree provided by user? Default is \code{FALSE} but it will be automatically set to \code{TRUE} when the class of \code{tree} is
\code{multiPhylo} since we don't provide any such mega-trees here.}

\item{.progress}{Form of progress bar, default to be text.}

\item{dt}{Whether to use data.table version to bind tips \link{bind_tip}. The default is \code{TRUE} as it maybe slightly faster.}
}
\value{
A phylogeny for the species required, with class \code{phylo}.
}
\description{
For a list of species, generate a phylogeny from a provided mega-tree. If a species is
not in the mega-tree, it will be grafted to the mega-tree with three scenarioes.
}
