Improves DimHeatmap documentation and default behavior when fast=FALSE (Issue #9810)

[dkcoxie]

Clarifies documentation to specify that figure legends are currently not displayed when fast=TRUE but added titles with PC numbers to ggplot outputs so that both PC number and figure legends can be displayed on the same plot, plus option to move position of shared patchwork legend when combine=TRUE to resolve Issue #9810

[dkcoxie]

In preparing teaching materials geared toward beginners, we found that the default behavior of DimHeatmap() either displays no figure legend but includes the PC number as panel titles (default fast=TRUE) OR allows the figure legend to be shown for the ggplot2 output doesn't display the PC number for each panel (when fast=FALSE).

The Proposed changes to theDimHeatmap() function clarify the documentation regarding when a figure legend will be displayed, add PC labels as individual figure titles for the ggplot2 outputs, and allow for the position of the figure legend to be moved when the ggplots are combined into a single patchwork output.

[dkcoxie]

The related issue was closed so I wanted to check if this improvement to make the output plots more consistent for DimHeatmap() when fast=TRUE and when fast=FALSE in still being considered for the next CRAN release. Thank you!

[anashen]

Thanks @dkcoxie for your PR & for the follow-up :) Yes, we have added this to the list of PRs to review.

[anashen]

Thank you @dkcoxie for opening this PR! These changes will definitely be helpful to add. I made a couple of suggestions & would appreciate it if you could take a look.

[anashen]

Suggested change

	#' @param combine Combine plots into a single \code{\link[patchwork]{patchwork}ed} with single shared figure legend when \code{fast=FALSE}
	#' ggplot object. If \code{FALSE}, return a list of ggplot objects
	#' @param combine Combine plots into a single \code{\link[patchwork]{patchwork}ed} ggplot object with
	#' single shared figure legend when \code{fast=FALSE}. If \code{FALSE}, return a list of ggplot objects

[anashen]

Suggested change

	#' @param leg.pos When \code{combine=TRUE}, allows legend position to be adjusted for \code{\link[patchwork]{patchwork}ed} output; defaults as \code{"right"}
	#' @param legend.position When \code{combine=TRUE}, allows legend position to be adjusted for \code{\link[patchwork]{patchwork}ed} output; defaults as \code{"right"}

Renaming this parameter to legend.position would make its purpose a bit more clear to users.

[anashen]

Suggested change

	leg.pos = "right"
	legend.position = "right"

[anashen]

Suggested change

	theme(legend.position = leg.pos)
	theme(legend.position = legend.position)

[anashen]

The function documentation will need to be updated to also import plot_layout (line 47):

#' @importFrom patchwork wrap_plots plot_layout

Otherwise, users will receive an error running DimHeatmap when the patchwork package isn't loaded (Error in plot_layout(guides = "collect") : could not find function "plot_layout").