% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rspr.R
\name{RSPRDist}
\alias{RSPRDist}
\title{Calculate rSPR distance between rooted trees}
\usage{
RSPRDist(
  tree1,
  tree2 = NULL,
  allPairs = is.null(tree2),
  checks = TRUE,
  approx = FALSE,
  maf = FALSE
)
}
\arguments{
\item{tree1, tree2}{Trees of class \code{phylo}, or lists thereof.
All trees must be rooted and bear identical sets of tip labels.}

\item{allPairs}{Logical; if \code{TRUE}, compare each tree in \code{tree1}
with each tree in \code{tree2}; if \code{FALSE}, compare corresponding
pairs.  Defaults to \code{TRUE} when \code{tree2} is not supplied.}

\item{checks}{Logical; validate tree labels and dimensions before
computation.  Set \code{FALSE} at your peril—improper input is likely
to crash R.}

\item{approx}{Logical; if \code{TRUE} return the linear-time
3-approximation instead of the exact distance.}

\item{maf}{Logical; if \code{TRUE} return the maximum agreement forest
alongside the exact distance (implies \code{approx = FALSE}).}
}
\value{
By default, an integer vector of rSPR distances (one per tree pair), or a
\code{dist} object when \code{allPairs = TRUE} and \code{tree2 = NULL}.

If \code{maf = TRUE}, a named list with elements:
\describe{
\item{\code{exact}}{Integer vector of rSPR distances.}
\item{\code{maf_1}, \code{maf_2}}{Character vectors giving the maximum
agreement forest for each pair of trees, expressed as space-separated
Newick components.}
}
}
\description{
Calculate rooted Subtree Prune-and-Regraft (rSPR) distances between pairs
of rooted binary trees using the algorithms of Whidden, Beiko & Zeh (2013).
}
\details{
This function wraps the \pkg{rspr} C++ library by Chris Whidden. It handles
rooted trees and is substantially more efficient than
\code{\link{USPRDist}()} for large trees: it can handle pairs with 200+
leaves and distances > 50.

Note that these distances are NP-hard to compute exactly; running time
scales as O(2^k n) where k is the rSPR distance and n is the number of
leaves. The built-in cluster decomposition (enabled by default) provides a
large practical speedup. Use \code{approx = TRUE} for a guaranteed
linear-time 3-approximation.

Input trees must be \strong{rooted}. An error is raised if any tree is unrooted.
}
\examples{
library(ape)
set.seed(1)
tree1 <- rtree(8)
tree2 <- rtree(8)
tree1$tip.label <- tree2$tip.label <- paste0("t", 1:8)

RSPRDist(tree1, tree2)

# All pairwise distances among a list of trees
trees <- c(tree1, tree2)
RSPRDist(trees)

# Fast 3-approximation
RSPRDist(tree1, tree2, approx = TRUE)

# With maximum agreement forest
RSPRDist(tree1, tree2, maf = TRUE)

}
\references{
Whidden C, Beiko RG, Zeh N (2013).
Fixed-Parameter Algorithms for Maximum Agreement Forests.
\emph{SIAM Journal on Computing} \strong{42}:1431–1466.
\doi{10.1137/110845045}

Whidden C, Zeh N, Beiko RG (2014).
Supertrees based on the subtree prune-and-regraft distance.
\emph{Systematic Biology} \strong{63}:566–581.
\doi{10.1093/sysbio/syu023}
}
\seealso{
\code{\link{USPRDist}()} for unrooted trees.
}
