docs: update tm_g_response for pre-release

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,