% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/visualization.R
\name{plot_dimensional_reduction}
\alias{plot_dimensional_reduction}
\title{Visualize data in dimensional reduction coordinates}
\usage{
plot_dimensional_reduction(
  dturtle,
  reduction_df,
  genes = NULL,
  plot = "proportions",
  include_gene = TRUE,
  log_expression = TRUE,
  include_labels = TRUE,
  reduction_to_use = "umap",
  indicate_significant_tx = TRUE,
  plot_colors = c("grey", "#9ECAE1", "#6BAED6", "#4292C6", "#2171B5", "#08519C",
    "#08306B"),
  plot_scale = "fixed",
  point_alpha = 1,
  point_size = NULL,
  text_size = 11,
  label_size = 3,
  label_colors = c("#7CAE00", "#00BFC4"),
  label_y_expansion = 0.2,
  savepath = NULL,
  filename_ext = "_dim_reduce.png",
  add_to_table = FALSE,
  BPPARAM = BiocParallel::SerialParam(),
  ...
)
}
\arguments{
\item{dturtle}{\code{dturtle} result object of \code{posthoc_and_stager()}.}

\item{reduction_df}{Provide the reduction coordinates for each cell, either as a two column data frame or matrix (with cell identifiers as row names) or a Seurat object. If a Seurat object is provided, the reduction \code{reduction_to_use} will be pulled from the object.}

\item{genes}{Character vector of genes to plot. If \code{NULL}, defaults to all found significant genes (\code{sig_genes}).}

\item{plot}{Specify what values should be plotted. Can be \code{'proportions'} or \code{'expression'}.}

\item{include_gene}{If \code{plot='expression'}, define if summarized gene expression should be plotted alongside.}

\item{log_expression}{If \code{plot='expression'}, define if expression counts should be log transformed.}

\item{include_labels}{Specify if labels of mean fitted proportional difference shall be included. The numbers in the labels are in regard to comparison group2 vs group1, in contrast to the dtu table.}

\item{reduction_to_use}{Only relevant if a Seurat object is provided to \code{reduction_df}. Specify the name of the reduction to use in the object.}

\item{indicate_significant_tx}{Specify if significant transcripts should be indicated in the plot by a colored strip. Converts the resulting plots to \code{grob}.}

\item{plot_colors}{Specify a vector of minimum 2 colors that build the color scale.}

\item{plot_scale}{Specify how the scales of each facet should act. Values are "fixed", "free_x", "free_y" or "free", to either have the same fixed scale, a free x- or y-axis or both axis free.}

\item{point_alpha}{Specify an alpha level for the single cells / samples.}

\item{point_size}{Specify the size of the points representing a single cell / sample. If \code{NULL}, chosen automatically.}

\item{text_size}{Specify basic text size (in pt) to use in plot.}

\item{label_size}{If \code{include_labels=TRUE}, set size of labels (in mm).}

\item{label_colors}{If \code{include_labels=TRUE}, set color of labels of positive or negative proportional differences.}

\item{label_y_expansion}{If \code{include_labels=TRUE}, define the factor the y-axis is extended by. This extension is performed to avoid overlapping of labels and cells / samples.
Labels are added to bottom of the plots of the second comparison group.}

\item{savepath}{If you want your files to be saved to disk, specify a save path here. The directories will be created if necessary.}

\item{filename_ext}{Optionally specify a file name extension here, which also defines the save image format. The file name will be 'gene_name+extension'.}

\item{add_to_table}{If a \code{savepath} is provided, add the filepaths of the created plots to the corresponding entries in \code{dtu_table}. The name of the column that shall be created can be specified here.}

\item{BPPARAM}{If multicore processing should be used, specify a \code{BiocParallelParam} object here. Among others, can be \code{SerialParam()} (default) for non-multicore processing or \code{MulticoreParam('number_cores')} for multicore processing. See \code{\link[BiocParallel:BiocParallel-package]{BiocParallel}} for more information.}

\item{...}{
  Arguments passed on to \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}
  \describe{
    \item{\code{filename}}{File name to create on disk.}
    \item{\code{device}}{Device to use. Can either be a device function
(e.g. \code{\link[=png]{png()}}), or one of "eps", "ps", "tex" (pictex),
"pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only).}
    \item{\code{path}}{Path of the directory to save plot to: \code{path} and \code{filename}
are combined to create the fully qualified file name. Defaults to the
working directory.}
    \item{\code{scale}}{Multiplicative scaling factor.}
    \item{\code{width}}{Plot size in \code{units} ("in", "cm", or "mm").
If not supplied, uses the size of current graphics device.}
    \item{\code{height}}{Plot size in \code{units} ("in", "cm", or "mm").
If not supplied, uses the size of current graphics device.}
    \item{\code{units}}{Plot size in \code{units} ("in", "cm", or "mm").
If not supplied, uses the size of current graphics device.}
    \item{\code{dpi}}{Plot resolution. Also accepts a string input: "retina" (320),
"print" (300), or "screen" (72). Applies only to raster output types.}
    \item{\code{limitsize}}{When \code{TRUE} (the default), \code{ggsave} will not
save images larger than 50x50 inches, to prevent the common error of
specifying dimensions in pixels.}
  }}
}
\value{
Returns list of saved plots, for adding to the DTU table. If no \code{savepath} is provided, returns a list of the created plots for further processing.
If \code{indicate_significant_tx} is TRUE, a list of \code{grob} objects will be returned, otherwise a list of \code{ggplot} objects. \code{grob} can be visualized for example with \code{grid::grid.draw()}.
}
\description{
Visualize proportions or expression in dimensional reduction coordinates.
}
\details{
Needs a pre-computed dimensional reduction with at least 2 dimensions. Currently only able to visualize in 2D. Sorts values to show highest expressing cells/samples on top.
}
\seealso{
\code{\link[=run_drimseq]{run_drimseq()}} and \code{\link[=posthoc_and_stager]{posthoc_and_stager()}} for DTU object creation. \code{\link[=create_dtu_table]{create_dtu_table()}} and \code{\link[=plot_dtu_table]{plot_dtu_table()}} for table visualization.

Other DTUrtle visualization: 
\code{\link{create_dtu_table}()},
\code{\link{plot_proportion_barplot}()},
\code{\link{plot_proportion_pheatmap}()},
\code{\link{plot_transcripts_view}()}
}
\concept{DTUrtle visualization}
