% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RoguePlot.R
\name{RoguePlot}
\alias{RoguePlot}
\title{Visualize position of rogue taxa}
\usage{
RoguePlot(
  trees,
  tip,
  p = 1,
  plot = TRUE,
  Palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab"),
  nullCol = rgb(colorRamp(unlist(par(c("fg", "bg"))), space = "Lab")(0.8)/255),
  edgeLength = NULL,
  thin = par("lwd"),
  fat = thin + 1L,
  outgroupTips,
  sort = FALSE,
  legend = "none",
  legend.inset = 0,
  ...
)
}
\arguments{
\item{trees}{List or \code{multiPhylo} object containing phylogenetic trees
of class \code{phylo} to be summarized.}

\item{tip}{Numeric or character identifying rogue leaf, in format accepted
by \code{\link[=DropTip]{DropTip()}}.}

\item{p}{A numeric value between 0.5 and 1 giving the proportion for a clade
to be represented in the consensus tree (see \code{\link[=Consensus]{Consensus()}}).}

\item{plot}{Logical specifying whether to plot the tree.}

\item{Palette}{Function that takes a parameter \code{n} and generates a colour
palette with \code{n} entries.}

\item{nullCol}{Colour to paint regions of the tree on which the rogue is
never found.}

\item{edgeLength}{Numeric specifying edge lengths of consensus tree;
\code{NULL} aligns tips by scaling edges proportional to clade size; \code{1} sets
all edges to unit length.}

\item{thin, fat}{Numeric specifying width to plot edges if the rogue tip
never / sometimes does attach to them.}

\item{outgroupTips}{Vector of type character, integer or logical, specifying
the names or indices of the tips to include in the outgroup.
If \code{outgroupTips} is a of type character, and a tree contains multiple tips
with a matching label, the first will be used.}

\item{sort}{Logical specifying whether to sort consensus tree using
\code{\link[=SortTree]{SortTree()}}.}

\item{legend}{Character vector specifying position of legend (e.g.
\code{"bottomleft"}), or \code{"none"} to suppress legend.
For fine-grained control of legend, use \code{\link[PlotTools:SpectrumLegend]{PlotTools::SpectrumLegend()}}.}

\item{legend.inset}{Numeric specifying fraction of plot width / height
by which the legend's position should be inset.}

\item{\dots}{Additional parameters to \code{plot.phylo()}.}
}
\value{
\code{RoguePlot()} invisibly returns a list whose elements are:
\itemize{
\item \code{cons}: The reduced consensus tree, sorted if \code{sort = TRUE}, otherwise
in preorder;
\item \code{onEdge}: a vector of integers specifying the number of
trees in \code{trees} in which the rogue leaf is attached to each edge in turn
of the consensus tree;
\item \code{atNode}: a vector of integers specifying the number of trees in \code{trees}
in which the rogue leaf is attached to an edge collapsed into each node
of the consensus tree.
\item \code{legendLabels}: A character vector suggesting labels for a plot legend;
suitable for \code{PlotTools::SpectrumLegend(legend = x$legendLabels)}.
}
}
\description{
Plots a consensus of trees with a rogue taxon omitted, with edges coloured
according to the proportion of trees in which the taxon attaches to that
edge, after \insertCite{Klopfstein2019;textual}{TreeTools}.
}
\details{
Rogue taxa can be identified using the package \pkg{Rogue}
\insertCite{SmithCons}{TreeTools}.
}
\examples{
trees <- list(read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"),
              read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"),
              read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"),
              read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"),
              read.tree(text = "(rogue, (a, (b, (c, (d, (e, f))))));"),
              read.tree(text = "((rogue, a), (b, (c, (d, (e, f)))));"),
              read.tree(text = "(a, (b, ((c, d), (rogue, (e, f)))));"),
              read.tree(text = "(a, (b, ((c, (rogue, d)), (e, f))));"),
              read.tree(text = "(a, (b, (c, (d, (rogue, (e, f))))));"))
plotted <- RoguePlot(trees, "rogue", legend = "topleft", legend.inset = 0.02)
PlotTools::SpectrumLegend(
  "bottomleft",
  palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab")(100),
  legend = plotted$legendLabels,
  cex = 0.4
)
}
\references{
\insertAllCited{}
}
\seealso{
Other consensus tree functions:
\code{\link[=Consensus]{Consensus()}},
\code{\link[=ConsensusWithout]{ConsensusWithout()}}
}
\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{consensus tree functions}
