% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tree-force-layout.R
\name{plotTreeForce}
\alias{plotTreeForce}
\title{Plot force-directed layout of tree}
\usage{
plotTreeForce(
  object,
  label,
  label.type = "search",
  view = "default",
  alpha = 0.8,
  alpha.fade = 0.1,
  size = 5,
  title = NULL,
  title.cex = 3,
  title.line = 0,
  label.tips = (!is.null(object@tree$segment.names) |
    !is.null(object@tree$segment.names.short)),
  use.short.names = !is.null(object@tree$segment.names.short),
  seg.show = NULL,
  cells.show = NULL,
  fade.below = (2/9),
  density.alpha = T,
  label.spacing = 5,
  text.cex = 0.8,
  colors = NULL,
  discrete.colors = NULL,
  color.limits = NULL,
  symmetric.color.scale = NULL
)
}
\arguments{
\item{object}{An URD object}

\item{label}{(Character) Data to use for coloring tree (see \link{data.for.plot})}

\item{label.type}{(Character) Where to find data for label (default \code{"search"} auto-detects, see \link{data.for.plot})}

\item{view}{(Character) Name of view to use (i.e. the name of an entry in \code{@tree$force.view.list}) created by \link{plotTreeForceStore3DView}. Default is last view created.}

\item{alpha}{(Numeric) Maximum transparency of points}

\item{alpha.fade}{(Numeric) Minimum transparency of points}

\item{size}{(Numeric) Size of points in the plot}

\item{title}{(Character) Title to add to the plot. (This is sensitive to resizing the window after plotting, but if a view is stored, the window will be resized before the title is added, so it will be acceptable resolution for figures.)}

\item{title.cex}{(Numeric) Adjust the title font size}

\item{title.line}{(Numeric) Adjust the position of the title. Positive numbers move the title upward.}

\item{label.tips}{(Logical) Should text identifying the tips of the tree be placed in the force directed layout? Defaults to TRUE if \code{@tree$segment.names} has been set.}

\item{use.short.names}{(Logical) Should short names from \code{@tree$segment.names.short} be used? Defaults to TRUE if those values have been set.}

\item{seg.show}{(Character vector) Segments of the tree to put on the plot (Default \code{NULL} is all segments)}

\item{cells.show}{(Character vector) Cells of the tree to show (Default \code{NULL} is all cells)}

\item{fade.below}{(Numeric) If desired, transparency can be lowered for points with low expression values (thereby highlighting the portions of the tree with expression). This value is the portion of the range of expression values to fade. (The default, 2/9, fades the bottom two-ninths of the expression values.) A fully 'faded' point will have alpha of \code{alpha.fade}.}

\item{density.alpha}{(Logical) Should points with short distance to nearest neighbors (i.e. in denser regions of the plot) be more transparent?}

\item{label.spacing}{(Numeric) How far should labels be from the detected tips}

\item{text.cex}{(Numeric) Size of the label text}

\item{colors}{(Character vector) Vector of colors to use if plotting continuous data}

\item{discrete.colors}{(Character vector) Vector of colors to use if plotting discrete data}

\item{color.limits}{(Numeric vector, length 2) Minimum and maximum values for color scale. Default \code{NULL} auto-detects.}

\item{symmetric.color.scale}{(Logical) Should the color scale be symmetric and centered around 0? (Default \code{NULL} is \code{FALSE} if all values are positive, and \code{TRUE} if both positive and negative values are present.)}
}
\value{
Nothing. Produces a plot using the \code{rgl} package, displayed in an X11 window.
}
\description{
This plots data on the force-directed layout of an URD tree, generated by
\code{\link{treeForceDirectedLayout}}. Once the tree is rotated into a
perspective that is appealing, \code{\link{plotTreeForceStore3DView}} can be
used to store that view in the URD object for additional plots.
}
\details{
The transparency of points is typically adjusted in two ways: (1) Points with
low expression are made more transparent, which is controlled through the
\code{fade.below} and \code{alpha.fade} parameters. (2) Points in higher
density regions of the plot are made more transparent, which is controlled by
the \code{density.alpha} parameter (and the local density is determined by
the \code{density.neighbors} parameter of \code{\link{treeForceDirectedLayout}},
and can be adjusted after the fact by re-running \code{\link{fdlDensity}}).

Plots can be easily saved using \code{\link{rgl:rgl.snapshot}} and plots 
can be closed with \code{\link{rgl:rg.close}} if plotting many genes
using a loop.
}
\examples{
# Define the colors used below
stage.colors <- c("#CCCCCC", RColorBrewer::brewer.pal(9, "Set1")[9], RColorBrewer::brewer.pal(12, "Paired")[c(9,10,7,8,5,6,3,4,1,2)])
fire.with.grey <- c("#CECECE", "#DDC998", RColorBrewer::brewer.pal(9, "YlOrRd")[3:9])
branch.colors <- c("#CECECE", "#E6298B")

# Plot a discrete characteristic like stage or clustering results
plotTreeForce(object, "stage.nice", title="STAGE", title.line=1, discrete.colors = stage.colors, alpha=0.4)

# Plot gene expression
plotTreeForce(object, "NOTO", title="NOTO expression", title.line=1, colors = fire.with.grey)

Define a 'clustering' based on whether or not cells are in a given trajectory then plot it
object <- groupFromCells(object, group.id="lineage_Tailbud", cells=cellsAlongLineage(object, "Tailbud", remove.root=F))
plotTreeForce(object, "lineage_Tailbud", title="Tailbud", title.line=1, discrete.colors=branch.colors, alpha=0.4)

}
