% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sampleTrees.R
\name{sampleTrees}
\alias{sampleTrees}
\title{Extract a cloud of trees from the complete Avian Phylogeny for a set of species}
\usage{
sampleTrees(
  species = "all_species",
  label_type = "scientific",
  taxonomy_year = "2025",
  version = "1.6",
  count = 100,
  data_path = FALSE
)
}
\arguments{
\item{species}{A character vector either of scientific names (directly as they come out of the
eBird taxonomy, i.e. without underscores) or of six-letter eBird species codes. Any elements of
the species vector that do not match a species-level taxon in the specified eBird taxonomy
will result in an error. Default is set to "all_species".}

\item{label_type}{Either "scientific" or "code". Default is set to "scientific".}

\item{taxonomy_year}{The eBird taxonomy year the tree should be output in. Current options
include 2021, 2022, and 2023. Both numeric and character inputs are acceptable here. Any value
aside from these years will result in an error. Default is set 2023.}

\item{version}{The desired version of the tree. Default to the most recent
version of the tree. Other versions available are listed in data object as clootl_data$versions
Verson can be passed as a character string or as numeric.}

\item{count}{Work in progress, can only sample 100 for now. Eventually: The desired number of sampled trees.}

\item{data_path}{Default to FALSE. Data_path is not necessary if the path has been stored in the
environment, as occurs when the data was downloaded using get_avesdata_repo.
Otherwise, pass in the path to the directory where the AvesData repo was downloaded.}
}
\value{
A set of phylogenies determined in \code{count} of the specified taxa in the specified eBird taxonomy version and clootl
tree version.
}
\description{
Extract a cloud of trees from the complete Avian Phylogeny for a set of species
}
\details{
This function first ensures that the requested output species overlap with species-level
taxa in the requested eBird taxonomy. If they do not, the function will error out. The onus is
on the user to ensure the requested taxa are valid. This is critical to ensure no unexpected
analysis hiccups later--you don't want to find out many steps later that your dataset doesn't
match your phylogeny. The eBird database is currently (as of Mar 2025) in 2024 taxonomy.
Trees available in 2024 taxonomy will be available by June 2025. The 2025 taxonomy will be released
to the public in October or November 2025. The intention is to release a tree in 2025 taxonomy
concurrently with the publication of the taxonomy itself.
}
\examples{
if (Sys.getenv("AVESDATA_PATH") != "") {
  ex2 <- sampleTrees(species=c("Turdus migratorius",
                             "Setophaga dominica",
                             "Setophaga ruticilla",
                             "Sitta canadensis"))
 }
}
\author{
Eliot Miller, Luna Sanchez Reyes, Emily Jane McTavish
}
