From eb7a2835f18868f105476e4cebbfb89630ba5738 Mon Sep 17 00:00:00 2001 From: Yunuuuu Date: Thu, 7 Nov 2024 22:29:20 +0800 Subject: [PATCH] Docs update --- R/layout-quad-operator.R | 38 ++++++++++++++++--------------- man/with_quad.Rd | 38 ++++++++++++++++--------------- vignettes/heatmap-layout.Rmd | 43 ++++++++++++++++++++++++------------ vignettes/plot-options.Rmd | 13 +++++++---- 4 files changed, 78 insertions(+), 54 deletions(-) diff --git a/R/layout-quad-operator.R b/R/layout-quad-operator.R index f11adcbf..e4c016c5 100644 --- a/R/layout-quad-operator.R +++ b/R/layout-quad-operator.R @@ -1,24 +1,26 @@ -#' Modify `-` Operator Context in `quad_layout()` +#' Modify Context for the `-` Operator in `quad_layout()` #' #' @description -#' `r lifecycle::badge('experimental')` Wrapping objects with `with_quad` -#' allows you to change the context of the subtraction `-` operator in -#' `quad_layout()`. +#' `r lifecycle::badge('experimental')` The `with_quad` function allows you to +#' adjust the context in which the subtraction `-` operator is applied within +#' `quad_layout()`. This function wraps objects to specify their target layout +#' contexts when using `-` in `quad_layout()`. #' -#' @param x Objects to add to the layout using the `-` operator. -#' @param position A string containing one or more of `r oxford_and(.tlbr)` -#' indicating which annotation stack should be used as the context. If `NULL`, -#' the context will default to the [`quad_layout()`] itself. By default, -#' `waiver()` is used, which triggers the following behavior: If the current -#' active context in [`quad_layout()`] is `top` or `bottom`, the operator will -#' also act on the corresponding `bottom` or `top` annotation. If the context is -#' `left` or `right`, the operator will also act on the `right` or `left` -#' annotation, respectively. If there is no active annotation stack, it defaults -#' to `NULL`. -#' @param main A single boolean value indicates whether to apply `x` for the -#' main plot. -#' @return The input object with an additional attribute that specifies the -#' selected context. +#' @param x The object to be added to the layout using the `-` operator. +#' @param position A string specifying one or more positions— +#' `r oxford_and(.tlbr)`— to indicate the annotation stack context for the +#' operator [`-`][layout-operator]. By default, `waiver()` is used, which sets +#' the behavior as follows: if the active context in `quad_layout()` is `top` or +#' `bottom`, the operator will also apply to the corresponding `bottom` or `top` +#' annotation, respectively. Similarly, if the context is `left` or `right`, the +#' operator applies to the `right` or `left` annotation. When no annotation +#' stack is active, the context defaults to `NULL`. +#' @param main A single boolean value indicating whether `x` should apply to the +#' main plot, used only when `position` is not `NULL`. By default, if `position` +#' is `waiver()` and the active context of `quad_layout()` is an annotation +#' stack, `main` will be set to `TRUE`; otherwise, it defaults to `FALSE`. +#' @return The original object with an added attribute that sets the specified +#' layout context. #' @export with_quad <- function(x, position = waiver(), main = NULL) { assert_layout_position(position) diff --git a/man/with_quad.Rd b/man/with_quad.Rd index b0a0f3d0..ca96c705 100644 --- a/man/with_quad.Rd +++ b/man/with_quad.Rd @@ -2,32 +2,34 @@ % Please edit documentation in R/layout-quad-operator.R \name{with_quad} \alias{with_quad} -\title{Modify \code{-} Operator Context in \code{quad_layout()}} +\title{Modify Context for the \code{-} Operator in \code{quad_layout()}} \usage{ with_quad(x, position = waiver(), main = NULL) } \arguments{ -\item{x}{Objects to add to the layout using the \code{-} operator.} +\item{x}{The object to be added to the layout using the \code{-} operator.} -\item{position}{A string containing one or more of \code{"t"}, \code{"l"}, \code{"b"}, and \code{"r"} -indicating which annotation stack should be used as the context. If \code{NULL}, -the context will default to the \code{\link[=quad_layout]{quad_layout()}} itself. By default, -\code{waiver()} is used, which triggers the following behavior: If the current -active context in \code{\link[=quad_layout]{quad_layout()}} is \code{top} or \code{bottom}, the operator will -also act on the corresponding \code{bottom} or \code{top} annotation. If the context is -\code{left} or \code{right}, the operator will also act on the \code{right} or \code{left} -annotation, respectively. If there is no active annotation stack, it defaults -to \code{NULL}.} +\item{position}{A string specifying one or more positions— +\code{"t"}, \code{"l"}, \code{"b"}, and \code{"r"}— to indicate the annotation stack context for the +operator \code{\link[=layout-operator]{-}}. By default, \code{waiver()} is used, which sets +the behavior as follows: if the active context in \code{quad_layout()} is \code{top} or +\code{bottom}, the operator will also apply to the corresponding \code{bottom} or \code{top} +annotation, respectively. Similarly, if the context is \code{left} or \code{right}, the +operator applies to the \code{right} or \code{left} annotation. When no annotation +stack is active, the context defaults to \code{NULL}.} -\item{main}{A single boolean value indicates whether to apply \code{x} for the -main plot.} +\item{main}{A single boolean value indicating whether \code{x} should apply to the +main plot, used only when \code{position} is not \code{NULL}. By default, if \code{position} +is \code{waiver()} and the active context of \code{quad_layout()} is an annotation +stack, \code{main} will be set to \code{TRUE}; otherwise, it defaults to \code{FALSE}.} } \value{ -The input object with an additional attribute that specifies the -selected context. +The original object with an added attribute that sets the specified +layout context. } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Wrapping objects with \code{with_quad} -allows you to change the context of the subtraction \code{-} operator in -\code{quad_layout()}. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} The \code{with_quad} function allows you to +adjust the context in which the subtraction \code{-} operator is applied within +\code{quad_layout()}. This function wraps objects to specify their target layout +contexts when using \code{-} in \code{quad_layout()}. } diff --git a/vignettes/heatmap-layout.Rmd b/vignettes/heatmap-layout.Rmd index 44f1d24e..6e994f34 100644 --- a/vignettes/heatmap-layout.Rmd +++ b/vignettes/heatmap-layout.Rmd @@ -341,34 +341,49 @@ my_plot + Along with the `-` operator, `with_quad()` can be used to modify the operated context in `ggheatmap()`/`quad_layout()`. -It accepts three arguments: the object operated on by the `-` operator and the -operated context, and a single boolean value indicates whether we should operate -on the main plot of `ggheatmap()`/`quad_layout()`. - -By default, if the current active context in `ggheatmap()`/`quad_layout()` is -`top` or `bottom`, the operator will also act on the corresponding `bottom` or -`top` annotation. If the context is `left` or `right`, the operator will also -act on the `right` or `left` annotation, respectively. If there is no active -annotation stack, it defaults to `NULL` (this behavior differs in -`stack_layout()`; refer to `vignette("stack-layout")` for more details). +This function accepts three arguments: + 1. **x**: The object to be applied using the `-` operator. + 2. **position**: A string indicating the annotation stack to target (`top`, + `bottom`, `left`, `right`, or combinations thereof). This specifies the + context for applying `x`. + 3. **main**: A boolean that determines whether `x` should also apply to the main + plot within `ggheatmap()`/`quad_layout()`. + +By default, when the active context in `ggheatmap()`/`quad_layout()` is set to +`top` or `bottom`, the `-` operator will apply changes not only to that +annotation but also to the opposite one (i.e., bottom if top is active, and vice +versa). The same principle applies to the left and right contexts. In these +cases, the object will also be applied to the main plot by default unless +specified otherwise. If no annotation stack is active, `with_quad()` defaults to +`NULL`. (this behavior differs in `stack_layout()`; refer to +`vignette("stack-layout")` for more details) + ```{r} my_plot + # Change the active layout to the left annotation anno_left() - # Modify the background of all plots in the left and the opposite annotation + # in this way, the `main` argument by default would be `TRUE` with_quad(theme(plot.background = element_rect(fill = "red"))) ``` -The second argument can be a string containing one or more of `r +The `position` argument can be a string containing one or more of `r ggalign:::oxford_and(ggalign:::.tlbr)`, indicating which annotation stack should -be used as the context. The above example is equivalent to: +be used as the context. When the `position` argument is manually set, the +default value of the main argument will be `FALSE`. The example above is +equivalent to: ```{r} my_plot - # Modify the background of all plots in the left and right annotation - with_quad(theme(plot.background = element_rect(fill = "red")), "lr") + # and the main plot + with_quad( + theme(plot.background = element_rect(fill = "red")), + "lr", main = TRUE + ) ``` -If it is `NULL`, it removes any active annotation stack: +Setting `position` to `NULL` removes any active annotation stack, meaning the +object will apply to all plots in the layout, including annotation stacks: ```{r} my_plot - # Modify the background of all plots diff --git a/vignettes/plot-options.Rmd b/vignettes/plot-options.Rmd index 59b665b3..a54f7aec 100644 --- a/vignettes/plot-options.Rmd +++ b/vignettes/plot-options.Rmd @@ -14,14 +14,19 @@ knitr::opts_chunk$set( ) ``` -Waiting for complete ... +Plot options control the action of plots in the layout, they can be set at the +layout level to define global options for all plots in the layout, or they can +be applied to individual plots. + + - To set a plot option for a single plot, simply use the `+` operator + - To set a plot aption in the layout level, simply use the `-` operator. Currently, the package provides three actions (each prefixed with `plot_`): + - `plot_theme`: Sets the default theme for the plot. - `plot_data`: Transforms the plot data. Many functions in this package require a specific data format to align observations, `plot_data()` helps - reformat data frames as needed. + reformat data frames as needed. - `plot_align`: Defines alignment specifications for plots within the layout. - - `plot_theme`: Sets the default theme for the plot. ```{r setup} library(ggalign) @@ -215,7 +220,7 @@ heatmap_collect_all_guides + plot_align(guides = "l", free_spaces = "l") ``` -In `ggheatmap()` and `quad_layout()`, the behavior of the `free_spaces` and +In `ggheatmap()`/`quad_layout()`, the behavior of the `free_spaces` and `free_labs` arguments differs from other arguments in `plot_align()` when inheriting from the parent layout: - For `top` and `bottom` annotations, it inherits from the left ("l") and