% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tree_distance_transfer.R
\name{TransferDist}
\alias{TransferDist}
\alias{TransferDistance}
\alias{TransferDistSplits}
\title{Transfer dissimilarity between phylogenetic trees}
\usage{
TransferDist(
  tree1,
  tree2 = NULL,
  scale = TRUE,
  normalize = FALSE,
  reportMatching = FALSE
)

TransferDistance(
  tree1,
  tree2 = NULL,
  scale = TRUE,
  normalize = FALSE,
  reportMatching = FALSE
)

TransferDistSplits(
  splits1,
  splits2,
  nTip = attr(splits1, "nTip"),
  scale = TRUE,
  reportMatching = FALSE
)
}
\arguments{
\item{tree1, tree2}{Trees of class \code{phylo}, with leaves labelled identically,
or lists of such trees to undergo pairwise comparison.  Where implemented,
\code{tree2 = NULL} will compute distances between each pair of trees in the list
\code{tree1} using a fast algorithm based on
\insertCite{Day1985;textual}{TreeDist}.}

\item{scale}{Logical; if \code{TRUE} (default), use the scaled transfer
dissimilarity.  If \code{FALSE}, use the unscaled transfer dissimilarity.}

\item{normalize}{If a numeric value is provided, this will be used as a
maximum value against which to rescale results.
If \code{TRUE}, results will be rescaled against a maximum value calculated from
the specified tree sizes and topology, as specified in the "Normalization"
section below.
If \code{FALSE}, results will not be rescaled.}

\item{reportMatching}{Logical specifying whether to return the clade
matchings as an attribute of the score.}

\item{splits1, splits2}{Logical matrices where each row corresponds to a leaf,
either listed in the same order or bearing identical names (in any sequence),
and each column corresponds to a split, such that each leaf is identified as
a member of the ingroup (\code{TRUE}) or outgroup (\code{FALSE}) of the respective
split.}

\item{nTip}{(Optional) Integer specifying the number of leaves in each split.}
}
\value{
\code{TransferDist()} returns an object of class \code{dist} (if \code{tree2} is
\code{NULL}), a numeric matrix (if both \code{tree1} and \code{tree2} are lists), or a
numeric value (for a single pair).  If \code{reportMatching = TRUE}, the
return value carries \code{matching} and \code{pairScores} attributes.
}
\description{
Compute the transfer dissimilarity between phylogenetic trees, as defined
by \insertCite{Takazawa2026;textual}{TreeDist}.
The transfer dissimilarity uses the transfer distance
\insertCite{Lemoine2018}{TreeDist} to compare bipartitions, providing a
finer-grained measure than the Robinson--Foulds distance.  Each split in
each tree is scored by how many taxa must be moved to match its closest
counterpart in the other tree, and these scores are summed.
}
\details{
The \code{scaled} variant divides each split's contribution by its depth minus
one, giving equal weight to all splits regardless of their depth (analogous
to the Robinson--Foulds distance).  The \code{unscaled} variant uses raw transfer
distances, giving more weight to deep splits.  Neither variant satisfies
the triangle inequality for trees with six or more tips.
}
\section{Normalization}{


When \code{normalize = TRUE}, the scaled transfer dissimilarity is divided by
\code{2 * (n - 3)}, placing it in the range [0, 1].  The unscaled version is
divided by the maximum possible unscaled dissimilarity
(following \insertCite{Takazawa2026;textual}{TreeDist}).
}

\examples{
library(TreeTools)
TransferDist(BalancedTree(8), PectinateTree(8))
TransferDist(BalancedTree(8), PectinateTree(8), scale = FALSE)

# All-pairs
TransferDist(as.phylo(0:5, 8))

}
\references{
\insertAllCited{}
}
\seealso{
Other tree distances:
\code{\link[=HierarchicalMutualInfo]{HierarchicalMutualInfo()}},
\code{\link[=JaccardRobinsonFoulds]{JaccardRobinsonFoulds()}},
\code{\link[=KendallColijn]{KendallColijn()}},
\code{\link[=MASTSize]{MASTSize()}},
\code{\link[=MatchingSplitDistance]{MatchingSplitDistance()}},
\code{\link[=NNIDist]{NNIDist()}},
\code{\link[=NyeSimilarity]{NyeSimilarity()}},
\code{\link[=PathDist]{PathDist()}},
\code{\link{Robinson-Foulds}},
\code{\link[=SPRDist]{SPRDist()}},
\code{\link[=TreeDistance]{TreeDistance()}}
}
\concept{tree distances}
