# Visualize data in dimensional reduction coordinates

Source: `R/visualization.R`
`plot_dimensional_reduction.Rd`

Visualize proportions or expression in dimensional reduction coordinates.

    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

dturtle | `dturtle` result object of `posthoc_and_stager()`.
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 `reduction_to_use` will be pulled from the object.
genes | Character vector of genes to plot. If `NULL`, defaults to all found significant genes (`sig_genes`).
plot | Specify what values should be plotted. Can be `'proportions'` or `'expression'`.
include_gene | If `plot='expression'`, define if summarized gene expression should be plotted alongside.
log_expression | If `plot='expression'`, define if expression counts should be log transformed.
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.
reduction_to_use | Only relevant if a Seurat object is provided to `reduction_df`. Specify the name of the reduction to use in the object.
indicate_significant_tx | Specify if significant transcripts should be indicated in the plot by a colored strip. Converts the resulting plots to `grob`.
plot_colors | Specify a vector of minimum 2 colors that build the color scale.
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.
point_alpha | Specify an alpha level for the single cells / samples.
point_size | Specify the size of the points representing a single cell / sample. If `NULL`, chosen automatically.
text_size | Specify basic text size (in pt) to use in plot.
label_size | If `include_labels=TRUE`, set size of labels (in mm).
label_colors | If `include_labels=TRUE`, set color of labels of positive or negative proportional differences.
label_y_expansion | If `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.
savepath | If you want your files to be saved to disk, specify a save path here. The directories will be created if necessary.
filename_ext | Optionally specify a file name extension here, which also defines the save image format. The file name will be 'gene_name+extension'.
add_to_table | If a `savepath` is provided, add the filepaths of the created plots to the corresponding entries in `dtu_table`. The name of the column that shall be created can be specified here.
BPPARAM | If multicore processing should be used, specify a `BiocParallelParam` object here. Among others, can be `SerialParam()` (default) for non-multicore processing or `MulticoreParam('number_cores')` for multicore processing. See `BiocParallel` for more information.

...

Arguments passed on to `ggplot2::ggsave`

`filename`

  File name to create on disk.

`device`

  Device to use. Can either be a device function (e.g. `png()`), or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only).

`path`

  Path of the directory to save plot to: `path` and `filename` are combined to create the fully qualified file name. Defaults to the working directory.

`scale`

  Multiplicative scaling factor.

`width`

  Plot size in `units` ("in", "cm", or "mm"). If not supplied, uses the size of current graphics device.

`height`

  Plot size in `units` ("in", "cm", or "mm"). If not supplied, uses the size of current graphics device.

`units`

  Plot size in `units` ("in", "cm", or "mm"). If not supplied, uses the size of current graphics device.

`dpi`

  Plot resolution. Also accepts a string input: "retina" (320), "print" (300), or "screen" (72). Applies only to raster output types.

`limitsize`

  When `TRUE` (the default), `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 `savepath` is provided, returns a list of the created plots for further processing. If `indicate_significant_tx` is TRUE, a list of `grob` objects will be returned, otherwise a list of `ggplot` objects. `grob` can be visualized for example with `grid::grid.draw()`.

## 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.

## See also

`run_drimseq()` and `posthoc_and_stager()` for DTU object creation. `create_dtu_table()` and `plot_dtu_table()` for table visualization.

Other DTUrtle visualization: `create_dtu_table()`, `plot_proportion_barplot()`, `plot_proportion_pheatmap()`, `plot_transcripts_view()`