% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distance.R
\name{taxo_distance}
\alias{taxo_distance}
\title{Compute the taxonomic hierarchy 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
only when their complete lineages are identical.}
\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,A) = 0}{d(A,A) = 0}
\deqn{d(A,B) = 1 / h(A,B)}{d(A,B) = 1 / h(A,B)}

Here, \code{h(A,B)} is the depth of the MRCA of \code{A} and \code{B}. The deeper the
shared ancestor, the smaller (closer to zero) the distance.
Distinct nodes always have positive distance, including when one taxon is
an ancestor of the other. This makes the measure an ultrametric on each
connected taxonomic hierarchy. Use \code{\link[=is_member]{is_member()}} when the question is
whether one taxon belongs to a clade rather than how far apart the two
hierarchy nodes are.
}
\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()}}, \code{\link[=is_member]{is_member()}},
\code{\link[=taxo_path]{taxo_path()}}
}
