% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PaintTree.R
\name{PaintTree}
\alias{PaintTree}
\title{Colour a tree by topology}
\usage{
PaintTree(tree, palette = "default")
}
\arguments{
\item{tree}{A tree of class \code{\link[ape:read.tree]{phylo}}.}

\item{palette}{Either a character string naming one of the built-in
palettes (\code{"default"}, \code{"protanopia"}, \code{"tritanopia"},
or a function \verb{function(h, s)} taking vectors of hues in
\verb{[0, 360]} and saturations in \verb{[0, 1]} and returning a character vector of
colours.  The \code{"protanopia"} and \code{"tritanopia"} palettes simulate
dichromatic perception of the default HCL spectrum using the
Viénot–Brettel–Mollon projection.}
}
\value{
A list with three character vectors of hex colours:
\describe{
\item{\code{edgeCol}}{One colour per edge in \code{tree$edge}, taken from the
child node's \verb{(hue, saturation)}.}
\item{\code{tipCol}}{One colour per leaf, indexed \code{1:NTip(tree)}.}
\item{\code{nodeCol}}{One colour per internal node, indexed so that entry \code{i}
corresponds to node \code{NTip(tree) + i}; the root (entry 1) is grey
because its saturation is zero.}
}
}
\description{
\code{PaintTree()} assigns a colour to every edge, leaf, and internal node of a
tree such that sister clades occupy adjacent hue bands proportional to their
tip counts, and saturation grows from zero at the root to one at every tip.
The result is a list of vectors that correspond to
\code{\link[ape:plot.phylo]{plot.phylo()}}'s
\code{edge.color}, \code{tip.color}, and \code{node.color} arguments.
}
\details{
Hue is allocated recursively from a 0–360° budget at the root.  At each
internal node, the parent's budget is partitioned across its descendant
edges in proportion to the number of leaves descended from each child; the
colour reported for an edge or node is the midpoint of its assigned range.
Saturation \code{s = (nTip - nDesc) / (nTip - 1)}, where \code{nDesc} is the number of
leaves descended from the node (including itself for tips), so the root is
achromatic (\code{s = 0}) and every leaf is fully saturated (\code{s = 1}).
}
\examples{
tree <- BalancedTree(1:8) + PectinateTree(9:14)
tree <- ape::bind.tree(BalancedTree(1:8), PectinateTree(9:12), 8, 4)
paint <- PaintTree(tree)
plot(tree,
     edge.color = paint$edgeCol,
     tip.color = paint$tipCol,
     edge.width = 3)

# Colour-blind-safe variants
paintP <- PaintTree(tree, "protanopia")
plot(tree,
     edge.color = paintP$edgeCol,
     tip.color = paintP$tipCol,
     edge.width = 3)

paintT <- PaintTree(tree, "tritanopia")
plot(tree,
     edge.color = paintT$edgeCol,
     tip.color = paintT$tipCol,
     edge.width = 3)

# User-supplied palette function (greyscale)
grey_pal <- function(h, s) grey(1 - s * 0.8)
paintG <- PaintTree(tree, grey_pal)
plot(tree, edge.color = paintG$edgeCol, edge.width = 3)

}
\seealso{
\code{\link[=CladeSizes]{CladeSizes()}}, \code{\link[=DescendantEdges]{DescendantEdges()}}

Other tree navigation:
\code{\link[=AncestorEdge]{AncestorEdge()}},
\code{\link[=CladeSizes]{CladeSizes()}},
\code{\link[=DescendantEdges]{DescendantEdges()}},
\code{\link[=EdgeAncestry]{EdgeAncestry()}},
\code{\link[=EdgeDistances]{EdgeDistances()}},
\code{\link[=ListAncestors]{ListAncestors()}},
\code{\link[=MRCA]{MRCA()}},
\code{\link[=MatchEdges]{MatchEdges()}},
\code{\link[=NDescendants]{NDescendants()}},
\code{\link[=NodeDepth]{NodeDepth()}},
\code{\link[=NodeNumbers]{NodeNumbers()}},
\code{\link[=NodeOrder]{NodeOrder()}},
\code{\link[=RootNode]{RootNode()}}
}
\author{
\href{https://orcid.org/0000-0001-5660-1727}{Martin R. Smith}
(\href{mailto:martin.smith@durham.ac.uk}{martin.smith@durham.ac.uk})
}
\concept{tree navigation}
