% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distance.R
\name{focal_distances}
\alias{focal_distances}
\title{Compute distances from a focal taxon to a community of taxa}
\usage{
focal_distances(focal, community, verbose = FALSE, progress = TRUE)
}
\arguments{
\item{focal}{A character string giving the focal taxon name.}

\item{community}{A character vector of community taxon names to compare
against. The focal taxon may be included — it will receive a distance
of \code{0}.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages. Default \code{FALSE}.}

\item{progress}{Logical. If \code{TRUE}, shows a progress bar. Default \code{TRUE}.}
}
\value{
A data frame of class \code{"taxodist_focal"} with columns:
\describe{
\item{\code{taxon}}{Character. Community taxon name.}
\item{\code{distance}}{Numeric. Taxonomic distance to the focal taxon.}
\item{\code{mrca}}{Character. Name of the most recent common ancestor.}
\item{\code{mrca_depth}}{Integer. Depth of the MRCA node.}
}
Rows are sorted by \code{distance} ascending (closest relatives first).
Returns \code{NULL} if the focal taxon cannot be found. An empty community
returns an empty object with the same columns and class.
}
\description{
Given a focal taxon and a vector of community taxa, retrieves all lineages
and computes the taxonomic distance from the focal taxon to each member of
the community. Returns a sorted data frame that also reports the most recent
common ancestor (MRCA) for each pair, making it easy to interpret \emph{why} a
taxon is close or distant.
}
\examples{
\donttest{
community <- c("Velociraptor", "Triceratops", "Brachiosaurus",
               "Allosaurus", "Homo", "Quercus")
focal_distances("Tyrannosaurus", community)
}
}
\seealso{
\code{\link[=closest_relative]{closest_relative()}}, \code{\link[=distance_matrix]{distance_matrix()}}, \code{\link[=taxo_distance]{taxo_distance()}}
}
