% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distance.R
\name{taxo_distance}
\alias{taxo_distance}
\title{Compute the phylogenetic distance between two taxa}
\usage{
taxo_distance(taxon_a, taxon_b, verbose = FALSE)
}
\arguments{
\item{taxon_a}{A character string giving the first taxon name.}

\item{taxon_b}{A character string giving the second taxon name.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages. Default \code{FALSE}.}
}
\value{
A named list of class \code{"taxodist_result"} with the following elements:
\describe{
\item{\code{distance}}{Numeric. The distance between the two taxa. Returns 0
if one taxon is an ancestor of the other.}
\item{\code{mrca}}{Character. The name of the most recent common ancestor.}
\item{\code{mrca_depth}}{Integer. The depth of the MRCA node.}
\item{\code{depth_a}}{Integer. The lineage depth of taxon A.}
\item{\code{depth_b}}{Integer. The lineage depth of taxon B.}
\item{\code{taxon_a}}{Character. Name of the first taxon.}
\item{\code{taxon_b}}{Character. Name of the second taxon.}
}
Returns \code{NULL} if either taxon cannot be found.
}
\description{
Given two taxon names, retrieves their lineages from The Taxonomicon and
computes a taxonomic distance based on the depth of their most recent
common ancestor (MRCA):
}
\details{
\deqn{d(A, B) = \frac{1}{\text{depth}(\text{MRCA}(A,B))}}

The deeper the shared ancestor, the smaller (closer to zero) the distance.
This metric ensures that taxa diverging at the same node are always
equidistant from any third taxon, regardless of lineage depth differences
below the split.
}
\examples{
\donttest{
# Distance between two theropods
taxo_distance("Tyrannosaurus", "Velociraptor")

# Distance between very distantly related taxa
taxo_distance("Tyrannosaurus", "Quercus")

# Distance between two oviraptorid genera
taxo_distance("Nomingia", "Huanansaurus")
}
}
\references{
Brands, S.J. (1989 onwards). Systema Naturae 2000. Amsterdam, The
Netherlands. Retrieved from The Taxonomicon,
\url{http://taxonomicon.taxonomy.nl}.
}
\seealso{
\code{\link[=mrca]{mrca()}}, \code{\link[=distance_matrix]{distance_matrix()}}, \code{\link[=get_lineage]{get_lineage()}}
}
