diff --git a/R/tm_g_response.R b/R/tm_g_response.R index 3ca9acdf0..855ba6070 100644 --- a/R/tm_g_response.R +++ b/R/tm_g_response.R @@ -1,31 +1,47 @@ -#' Response Plots -#' @md +#' Response plot module +#' +#' Generates a response plot for a given `response` and `x` variables. +#' This module allows users customize and add annotations to the plot depending +#' via the module's arguments. +#' It supports showing the counts grouped by other variable facets (by row / column), +#' swapping the coordinates, show count annotations and displaying the response plot +#' as frequency or density. #' #' @inheritParams teal::module #' @inheritParams shared_params #' @param response (`data_extract_spec` or `list` of multiple `data_extract_spec`) -#' Which variable to use as the response. You can define one fixed column by using the -#' setting `fixed = TRUE` inside the `select_spec`. -#' `data_extract_spec` must not allow multiple selection in this case. +#' Which variable to use as the response. +#' You can define one fixed column by using the setting `fixed = TRUE` inside the `select_spec`. +#' +#' The `data_extract_spec` must not allow multiple selection in this case. #' @param x (`data_extract_spec` or `list` of multiple `data_extract_spec`) -#' Which variable to use on the X-axis of the response plot. Allow the user to select multiple -#' columns from the `data` allowed in teal. -#' `data_extract_spec` must not allow multiple selection in this case. -#' @param row_facet optional, (`data_extract_spec` or `list` of multiple `data_extract_spec`) -#' Which data columns to use for faceting rows. -#' @param col_facet optional, (`data_extract_spec` or `list` of multiple `data_extract_spec`) -#' Which data to use for faceting columns. -#' @param coord_flip optional, (`logical`) Whether to flip coordinates between `x` and `response`. -#' @param count_labels optional, (`logical`) Whether to show count labels. -#' Defaults to `TRUE`. -#' @param freq optional, (`logical`) Whether to display frequency (`TRUE`) or density (`FALSE`). -#' Defaults to density (`FALSE`). +#' Specifies which variable to use on the X-axis of the response plot. +#' Allow the user to select multiple columns from the `data` allowed in teal. +#' +#' The `data_extract_spec` must not allow multiple selection in this case. +#' @param row_facet (optional `data_extract_spec` or `list` of multiple `data_extract_spec`) +#' Specifies the data variable(s) to use for faceting rows. +#' @param col_facet (optional `data_extract_spec` or `list` of multiple `data_extract_spec`) +#' Specifies the data variable(s) to use for faceting columns. +#' @param coord_flip (optional `logical`) +#' Indicates whether to flip coordinates between `x` and `response`. +#' The default value is `FALSE` and it will show the `x` variable on the x-axis +#' and the `response` variable on the y-axis. +#' @param count_labels (optional `logical`) +#' Indicates whether to show count labels. +#' Defaults to `TRUE`. +#' @param freq (optional `logical`) +#' Indicates whether to display frequency (`TRUE`) or density (`FALSE`). +#' Defaults to density (`FALSE`). +#' +#' @return Object of class `teal_module` to be used in `teal` applications. #' #' @note For more examples, please see the vignette "Using response plot" via -#' \code{vignette("using-response-plot", package = "teal.modules.general")}. -#' @export +#' `vignette("using-response-plot", package = "teal.modules.general")`. +#' #' @examples #' # Response plot with selected response (BMRKR1) and selected x variable (RACE) +#' library(teal.widgets) #' #' data <- teal_data() #' data <- within(data, { @@ -36,32 +52,32 @@ #' datanames(data) <- datanames #' join_keys(data) <- default_cdisc_join_keys[datanames] #' -#' app <- teal::init( +#' app <- init( #' data = data, -#' modules = teal::modules( -#' teal.modules.general::tm_g_response( +#' modules = modules( +#' tm_g_response( #' label = "Response Plots", -#' response = teal.transform::data_extract_spec( +#' response = data_extract_spec( #' dataname = "ADSL", -#' select = teal.transform::select_spec( +#' select = select_spec( #' label = "Select variable:", -#' choices = teal.transform::variable_choices(data[["ADSL"]], c("BMRKR2", "COUNTRY")), +#' choices = variable_choices(data[["ADSL"]], c("BMRKR2", "COUNTRY")), #' selected = "BMRKR2", #' multiple = FALSE, #' fixed = FALSE #' ) #' ), -#' x = teal.transform::data_extract_spec( +#' x = data_extract_spec( #' dataname = "ADSL", -#' select = teal.transform::select_spec( +#' select = select_spec( #' label = "Select variable:", -#' choices = teal.transform::variable_choices(data[["ADSL"]], c("SEX", "RACE")), +#' choices = variable_choices(data[["ADSL"]], c("SEX", "RACE")), #' selected = "RACE", #' multiple = FALSE, #' fixed = FALSE #' ) #' ), -#' ggplot2_args = teal.widgets::ggplot2_args( +#' ggplot2_args = ggplot2_args( #' labs = list(subtitle = "Plot generated by Response Module") #' ) #' ) @@ -70,6 +86,8 @@ #' if (interactive()) { #' shinyApp(app$ui, app$server) #' } +#' @export +#' tm_g_response <- function(label = "Response Plot", response, x, @@ -144,6 +162,7 @@ tm_g_response <- function(label = "Response Plot", ) } +# UI function for the response module ui_g_response <- function(id, ...) { ns <- NS(id) args <- list(...) @@ -219,6 +238,7 @@ ui_g_response <- function(id, ...) { ) } +# Server function for the response module srv_g_response <- function(id, data, reporter, diff --git a/man/tm_g_response.Rd b/man/tm_g_response.Rd index 6d0986c2f..6a231d813 100644 --- a/man/tm_g_response.Rd +++ b/man/tm_g_response.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/tm_g_response.R \name{tm_g_response} \alias{tm_g_response} -\title{Response Plots} +\title{Response plot module} \usage{ tm_g_response( label = "Response Plot", @@ -27,30 +27,37 @@ tm_g_response( For \code{modules()} defaults to \code{"root"}. See \code{Details}.} \item{response}{(\code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) -Which variable to use as the response. You can define one fixed column by using the -setting \code{fixed = TRUE} inside the \code{select_spec}. -\code{data_extract_spec} must not allow multiple selection in this case.} +Which variable to use as the response. +You can define one fixed column by using the setting \code{fixed = TRUE} inside the \code{select_spec}. + +The \code{data_extract_spec} must not allow multiple selection in this case.} \item{x}{(\code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) -Which variable to use on the X-axis of the response plot. Allow the user to select multiple -columns from the \code{data} allowed in teal. -\code{data_extract_spec} must not allow multiple selection in this case.} +Specifies which variable to use on the X-axis of the response plot. +Allow the user to select multiple columns from the \code{data} allowed in teal. + +The \code{data_extract_spec} must not allow multiple selection in this case.} -\item{row_facet}{optional, (\code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) -Which data columns to use for faceting rows.} +\item{row_facet}{(optional \code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) +Specifies the data variable(s) to use for faceting rows.} -\item{col_facet}{optional, (\code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) -Which data to use for faceting columns.} +\item{col_facet}{(optional \code{data_extract_spec} or \code{list} of multiple \code{data_extract_spec}) +Specifies the data variable(s) to use for faceting columns.} -\item{coord_flip}{optional, (\code{logical}) Whether to flip coordinates between \code{x} and \code{response}.} +\item{coord_flip}{(optional \code{logical}) +Indicates whether to flip coordinates between \code{x} and \code{response}. +The default value is \code{FALSE} and it will show the \code{x} variable on the x-axis +and the \code{response} variable on the y-axis.} -\item{count_labels}{optional, (\code{logical}) Whether to show count labels. +\item{count_labels}{(optional \code{logical}) +Indicates whether to show count labels. Defaults to \code{TRUE}.} \item{rotate_xaxis_labels}{optional, (\code{logical}) Whether to rotate plot X axis labels. Does not rotate by default (\code{FALSE}).} -\item{freq}{optional, (\code{logical}) Whether to display frequency (\code{TRUE}) or density (\code{FALSE}). +\item{freq}{(optional \code{logical}) +Indicates whether to display frequency (\code{TRUE}) or density (\code{FALSE}). Defaults to density (\code{FALSE}).} \item{plot_height}{optional, (\code{numeric}) A vector of length three with \verb{c(value, min and max)} @@ -73,8 +80,16 @@ with text placed before the output to put the output into context. For example a \item{post_output}{(\code{shiny.tag}, optional) with text placed after the output to put the output into context. For example the \code{\link[shiny:helpText]{shiny::helpText()}} elements are useful.} } +\value{ +Object of class \code{teal_module} to be used in \code{teal} applications. +} \description{ -Response Plots +Generates a response plot for a given \code{response} and \code{x} variables. +This module allows users customize and add annotations to the plot depending +via the module's arguments. +It supports showing the counts grouped by other variable facets (by row / column), +swapping the coordinates, show count annotations and displaying the response plot +as frequency or density. } \note{ For more examples, please see the vignette "Using response plot" via @@ -82,6 +97,7 @@ For more examples, please see the vignette "Using response plot" via } \examples{ # Response plot with selected response (BMRKR1) and selected x variable (RACE) +library(teal.widgets) data <- teal_data() data <- within(data, { @@ -92,32 +108,32 @@ datanames <- c("ADSL") datanames(data) <- datanames join_keys(data) <- default_cdisc_join_keys[datanames] -app <- teal::init( +app <- init( data = data, - modules = teal::modules( - teal.modules.general::tm_g_response( + modules = modules( + tm_g_response( label = "Response Plots", - response = teal.transform::data_extract_spec( + response = data_extract_spec( dataname = "ADSL", - select = teal.transform::select_spec( + select = select_spec( label = "Select variable:", - choices = teal.transform::variable_choices(data[["ADSL"]], c("BMRKR2", "COUNTRY")), + choices = variable_choices(data[["ADSL"]], c("BMRKR2", "COUNTRY")), selected = "BMRKR2", multiple = FALSE, fixed = FALSE ) ), - x = teal.transform::data_extract_spec( + x = data_extract_spec( dataname = "ADSL", - select = teal.transform::select_spec( + select = select_spec( label = "Select variable:", - choices = teal.transform::variable_choices(data[["ADSL"]], c("SEX", "RACE")), + choices = variable_choices(data[["ADSL"]], c("SEX", "RACE")), selected = "RACE", multiple = FALSE, fixed = FALSE ) ), - ggplot2_args = teal.widgets::ggplot2_args( + ggplot2_args = ggplot2_args( labs = list(subtitle = "Plot generated by Response Module") ) )