updating tm_a_regression documentation

R/tm_a_regression.R

@@ -1,20 +1,27 @@
-#' Scatterplot and Regression Model
-#' @md
+#' Scatterplot and regression model
+#'
+#' Module for visualizing regression analysis, including scatterplots and
+#' various regression diagnostics plots.
+#' It allows users to explore the relationship between a set of regressors and a response variable,
+#' visualize residuals, and identify outliers.
+#'
+#' @note For more examples, please see the vignette "Using regression plots" via
+#' `vignette("using-regression-plots", package = "teal.modules.general")`.
 #'
 #' @inheritParams teal::module
 #' @inheritParams shared_params
 #' @param regressor (`data_extract_spec` or `list` of multiple `data_extract_spec`)
-#'  Regressor variables from an incoming dataset with filtering and selecting.
+#' Regressor variables from an incoming dataset with filtering and selecting.
 #' @param response (`data_extract_spec` or `list` of multiple `data_extract_spec`)
-#'  Response variables from an incoming dataset with filtering and selecting.
-#' @param alpha optional, (`numeric`) If scalar then the plot points will have a fixed opacity. If a
-#'   slider should be presented to adjust the plot point opacity dynamically then it can be a vector of
-#'   length three with `c(value, min, max)`.
-#' @param size optional, (`numeric`) If scalar then the plot point sizes will have a fixed size
-#'   If a slider should be presented to adjust the plot point sizes dynamically then it can be a
-#'   vector of length three with `c(value, min, max)`.
-#' @param default_outlier_label optional, (`character`) The default column selected to label outliers.
-#' @param default_plot_type optional, (`numeric`) Defaults to Response vs Regressor.
+#' Response variables from an incoming dataset with filtering and selecting.
+#' @param alpha (`numeric`, optional) Specifies point opacity.
+#' - If vector of `length==1` then the plot points will have a fixed opacity.
+#' - while vector of `value`, `min`, and `max` allows dynamic adjustment.
+#' @param size (`numeric`, optional) Specifies point size.
+#' - If vector of `length==1` then the plot point sizes will have a fixed size
+#' - while vector of `value`, `min`, and `max` allows dynamic adjustment.
+#' @param default_outlier_label (`character`, optional) The default column selected to label outliers.
+#' @param default_plot_type (`numeric`, optional) Defaults to Response vs Regressor.
 #' 1. Response vs Regressor
 #' 2. Residuals vs Fitted
 #' 3. Normal Q-Q
@@ -26,13 +33,13 @@
 #' @templateVar ggnames `r regression_names`
 #' @template ggplot2_args_multi
 #'
-#' @note For more examples, please see the vignette "Using regression plots" via
-#'   `vignette("using-regression-plots", package = "teal.modules.general")`.
-#' @export
+#' @return Object of class `teal_module` to be used in `teal` applications,
+#' enabling the visualization of regression analysis including various diagnostic plots.
 #'
 #' @examples
 #' # Regression graphs from selected response variable (BMRKR1) and
 #' # selected regressors (AGE)
+#' library(teal.widgets)
 #'
 #' data <- teal_data()
 #' data <- within(data, {
@@ -43,32 +50,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_a_regression(
+#'   modules = modules(
+#'     tm_a_regression(
 #'       label = "Regression",
-#'       response = teal.transform::data_extract_spec(
+#'       response = data_extract_spec(
 #'         dataname = "ADSL",
-#'         select = teal.transform::select_spec(
+#'         select = select_spec(
 #'           label = "Select variable:",
 #'           choices = "BMRKR1",
 #'           selected = "BMRKR1",
 #'           multiple = FALSE,
 #'           fixed = TRUE
 #'         )
 #'       ),
-#'       regressor = teal.transform::data_extract_spec(
+#'       regressor = data_extract_spec(
 #'         dataname = "ADSL",
-#'         select = teal.transform::select_spec(
+#'         select = select_spec(
 #'           label = "Select variables:",
-#'           choices = teal.transform::variable_choices(data[["ADSL"]], c("AGE", "SEX", "RACE")),
+#'           choices = variable_choices(data[["ADSL"]], c("AGE", "SEX", "RACE")),
 #'           selected = "AGE",
 #'           multiple = TRUE,
 #'           fixed = FALSE
 #'         )
 #'       ),
-#'       ggplot2_args = teal.widgets::ggplot2_args(
+#'       ggplot2_args = ggplot2_args(
 #'         labs = list(subtitle = "Plot generated by Regression Module")
 #'       )
 #'     )
@@ -77,6 +84,9 @@
 #' if (interactive()) {
 #'   shinyApp(app$ui, app$server)
 #' }
+#'
+#' @export
+#'
 tm_a_regression <- function(label = "Regression Analysis",
                             regressor,
                             response,
@@ -143,6 +153,7 @@ tm_a_regression <- function(label = "Regression Analysis",
   )
 }
 
+# UI function for the regression module.
 ui_a_regression <- function(id, ...) {
   ns <- NS(id)
   args <- list(...)
@@ -230,7 +241,7 @@ ui_a_regression <- function(id, ...) {
   )
 }
 
-
+# Server function for the regression module.
 srv_a_regression <- function(id,
                              data,
                              reporter,
@@ -824,12 +835,12 @@ srv_a_regression <- function(id,
       } else {
         plot_base_q <- plot_base()
         switch(input_type,
-          "Residuals vs Fitted" = plot_base_q %>% plot_type_1(),
-          "Normal Q-Q" = plot_base_q %>% plot_type_2(),
-          "Scale-Location" = plot_base_q %>% plot_type_3(),
-          "Cook's distance" = plot_base_q %>% plot_type_4(),
-          "Residuals vs Leverage" = plot_base_q %>% plot_type_5(),
-          "Cook's dist vs Leverage" = plot_base_q %>% plot_type_6()
+               "Residuals vs Fitted" = plot_base_q %>% plot_type_1(),
+               "Normal Q-Q" = plot_base_q %>% plot_type_2(),
+               "Scale-Location" = plot_base_q %>% plot_type_3(),
+               "Cook's distance" = plot_base_q %>% plot_type_4(),
+               "Residuals vs Leverage" = plot_base_q %>% plot_type_5(),
+               "Cook's dist vs Leverage" = plot_base_q %>% plot_type_6()
         )
       }
       qenv
@@ -851,7 +862,7 @@ srv_a_regression <- function(id,
       req(iv_r()$is_valid())
       req(iv_out$is_valid())
       paste(utils::capture.output(summary(teal.code::dev_suppress(fitted())))[-1],
-        collapse = "\n"
+            collapse = "\n"
       )
     })