Merge pull request #176 from Merck/Improve-documentation-style-#157

improve documentation

DESCRIPTION

@@ -42,4 +42,4 @@ Suggests:
     tidyr
 Config/testthat/edition: 3
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1

R/avg.R

@@ -19,13 +19,15 @@
 #' Average number of events
 #'
 #' Calculates average number of records per group and, if requested, parameter.
-#' Returns a list of means and sd of counts of records per group, ordered in
+#' Returns a list of means and SD of counts of records per group, ordered in
 #' the same way as the input datasets.
 #'
 #' @inheritParams n_subject
 #'
 #' @importFrom stats sd reshape
 #'
+#' @return A list of means and SD of counts of records per group.
+#'
 #' @noRd
 #'
 #' @examples
@@ -56,7 +58,7 @@ avg_event <- function(id, group, par = NULL) {
   } else {
     db <- data.frame(id = id, group = group, par = par)
 
-    # Count number of observations per group, par, and id.
+    # Count number of observations per group, par, and id
     tmp <- split(db, ~ group + par + id, drop = TRUE) |>
       lapply(FUN = function(X) {
         data.frame(
@@ -76,25 +78,25 @@ avg_event <- function(id, group, par = NULL) {
         )
       }) |>
       do.call(what = rbind) |>
-      # Spread to wide format so that group.statistics are column variables.
+      # Spread to wide format so that group.statistics are column variables
       reshape(timevar = "group", idvar = "par", direction = "wide", new.row.names = NULL)
 
-    # Sort the summarized data so that par is in the same order as input.
+    # Sort the summarized data so that par is in the same order as input
     tmp <- merge(data.frame(par = unique(db$par)), tmp, by = "par", sort = FALSE)
     if (any(unique(tmp$par) != unique(db$par))) stop("sorting is broken, try again")
 
-    # Remove rownames.
+    # Remove row names
     rownames(tmp) <- NULL
 
-    # Extract avg and se into separate datasets.
+    # Extract avg and se into separate datasets
     avg <- tmp[, grepl(names(tmp), pattern = "^avg")]
     names(avg) <- sub(names(avg), pattern = "avg\\.", replacement = "")
-    # Reorder columns (group) to be as input.
+    # Reorder columns (group) to be as input
     avg <- avg[, u_group]
 
     se <- tmp[, grepl(names(tmp), pattern = "^se")]
     names(se) <- sub(names(se), pattern = "se\\.", replacement = "")
-    # Reorder columns (group) to be as input.
+    # Reorder columns (group) to be as input
     se <- se[, u_group]
   }
 
@@ -106,7 +108,7 @@ avg_event <- function(id, group, par = NULL) {
 #' the same way as the input datasets.
 #'
 #' @inheritParams n_subject
-#' @param dur A numeric vector of AE duration.
+#' @param dur A numeric vector of adverse event duration.
 #'
 #' @importFrom stats sd reshape
 #'
@@ -121,7 +123,7 @@ avg_duration <- function(id, group, dur, par = NULL) {
   if (is.null(par)) {
     db <- data.frame(id = id, group = group, dur = dur)
 
-    # Compute average and se of dur by treatment group.
+    # Compute average and se of dur by treatment group
     res <- split(db, db$group) |>
       lapply(FUN = function(X) {
         data.frame(
@@ -140,7 +142,7 @@ avg_duration <- function(id, group, dur, par = NULL) {
   } else {
     db <- data.frame(id = id, group = group, dur = dur, par = par)
 
-    # summarize dur by group and par.
+    # summarize dur by group and par
     tmp <- split(db, ~ group + par, drop = TRUE) |>
       lapply(FUN = function(X) {
         data.frame(
@@ -152,23 +154,23 @@ avg_duration <- function(id, group, dur, par = NULL) {
       }) |>
       do.call(what = rbind) |>
       reshape(timevar = "group", idvar = "par", direction = "wide")
-    # Sort the summarized data so that par is in the same order as input.
+    # Sort the summarized data so that par is in the same order as input
     tmp <- merge(data.frame(par = unique(db$par)), tmp, by = "par", sort = FALSE)
     if (any(unique(tmp$par) != unique(db$par))) stop("sorting is broken, try again")
 
-    # Set rownames to null.
+    # Set row names to null
     rownames(tmp) <- NULL
 
 
-    # Extract avg and se into separate datasets.
+    # Extract avg and se into separate datasets
     avg <- cbind(par = tmp$par, tmp[, grepl(names(tmp), pattern = "^avg")])
     names(avg) <- sub(names(avg), pattern = "avg\\.", replacement = "")
-    # Reorder columns (group) to be as input.
+    # Reorder columns (group) to be as input
     avg <- avg[, u_group]
 
     se <- cbind(par = tmp$par, tmp[, grepl(names(tmp), pattern = "^se")])
     names(se) <- sub(names(se), pattern = "se\\.", replacement = "")
-    # Reorder columns (group) to be as input.
+    # Reorder columns (group) to be as input
     se <- se[, u_group]
   }
 

R/data.R

@@ -4,5 +4,7 @@
 #'
 #' @format A data frame with 591 rows and 41 variables.
 #'
+#' @return An analysis data frame.
+#'
 #' @source \url{https://github.com/phuse-org/phuse-scripts/tree/master/data/sdtm/cdiscpilot01}
 "metalite_ae_adex"

R/extend_ae_specific.R

@@ -95,8 +95,8 @@ extend_ae_specific_inference <- function(outdata, ci = 0.95) {
 #' Add average duration information for AE specific analysis
 #'
 #' @param outdata An `outdata` object created by [prepare_ae_specific()].
-#' @param duration_var A character value of variable name for AE duration.
-#' @param duration_unit A character value of AE duration unit.
+#' @param duration_var A character value of variable name for adverse event duration.
+#' @param duration_unit A character value of adverse event duration unit.
 #'
 #' @return A list of analysis raw datasets.
 #'
@@ -140,7 +140,7 @@ extend_ae_specific_duration <- function(outdata,
   par_var <- collect_adam_mapping(meta, parameter)$var
   par_soc <- collect_adam_mapping(meta, parameter)$soc
 
-  # Obtain Data
+  # Obtain data
   pop <- collect_population_record(meta, population, var = pop_var)
   obs <- collect_observation_record(meta, population, observation, parameter,
     var = unique(c(obs_var, par_var, par_soc, obs_dur))
@@ -181,7 +181,7 @@ extend_ae_specific_duration <- function(outdata,
   u_group <- levels(pop[[pop_group]])
   n_group <- length(u_group)
 
-  # Overall Duration
+  # Overall duration
   obs_duration <- avg_duration(obs[[obs_id]], obs[[obs_group]], obs[[obs_dur]])
   obs_order <- 1e2
 
@@ -204,7 +204,7 @@ extend_ae_specific_duration <- function(outdata,
     se <- rbind(se, par_duration$se)
   }
 
-  # Define Order and add blank row
+  # Define order and add a blank row
   index <- c(obs_order, soc_order, par_order)
   blank_order <- setdiff(outdata$order, index)
   blank_row <- data.frame(matrix(NA, nrow = length(blank_order), ncol = n_group))
@@ -255,7 +255,7 @@ extend_ae_specific_events <- function(outdata) {
   par_var <- collect_adam_mapping(meta, parameter)$var
   par_soc <- collect_adam_mapping(meta, parameter)$soc
 
-  # Obtain Data
+  # Obtain data
   pop <- collect_population_record(meta, population, var = pop_var)
   obs <- collect_observation_record(meta, population, observation, parameter,
     var = unique(c(obs_var, par_var, par_soc))
@@ -296,7 +296,7 @@ extend_ae_specific_events <- function(outdata) {
   u_group <- levels(pop[[pop_group]])
   n_group <- length(u_group)
 
-  # Overall Duration
+  # Overall duration
   obs_events <- avg_event(obs[[obs_id]], obs[[obs_group]])
   obs_order <- 1e2
 
@@ -319,7 +319,7 @@ extend_ae_specific_events <- function(outdata) {
     se <- rbind(se, par_events$se)
   }
 
-  # Define Order and add blank row
+  # Define order and add a blank row
   index <- c(obs_order, soc_order, par_order)
   blank_order <- setdiff(outdata$order, index)
   blank_row <- data.frame(matrix(NA, nrow = length(blank_order), ncol = n_group))
@@ -339,10 +339,10 @@ extend_ae_specific_events <- function(outdata) {
   outdata
 }
 
-#' Add Subgroup analysis in AE specific analysis
+#' Add subgroup analysis in AE specific analysis
 #'
 #' @param outdata  An `outdata` object created by [prepare_ae_specific()].
-#' @param subgroup a character string for subgroup variable name
+#' @param subgroup A character string for subgroup variable name.
 #'
 #' @export
 extend_ae_specific_subgroup <- function(outdata, subgroup) {

R/fmt.R

@@ -48,7 +48,7 @@ fmt_pct <- function(x, digits = 1, pre = "(", post = ")") {
 #' Decimals will understand the number will be formatted as x.x (x.xx).
 #'
 #' @param mean A numeric vector of mean value.
-#' @param sd A numeric vector of sd value.
+#' @param sd A numeric vector of standard deviation value.
 #' @param digits Digits of each column, i.e., format as x.x (x.xx).
 #' @param width Width of each column.
 #'

R/format_ae_specific.R

@@ -23,18 +23,18 @@
 #' @param digits_ci A numeric value of number of digits for confidence interval.
 #' @param digits_p A numeric value of number of digits for p-value.
 #' @param digits_dur A numeric value of number of digits for average
-#'   duration of AE.
+#'   duration of adverse event.
 #' @param digits_events A numeric value of number of digits for average of
-#'   number of AE per subjects.
+#'   number of adverse events per subject.
 #' @param display A character vector of measurement to be displayed:
-#'   - `n`: Number of subjects with AE.
-#'   - `prop`: Proportion of subjects with AE.
+#'   - `n`: Number of subjects with adverse event.
+#'   - `prop`: Proportion of subjects with adverse event.
 #'   - `total`: Total columns.
 #'   - `diff`: Risk difference.
 #'   - `diff_ci`: 95% confidence interval of risk difference using M&N method.
 #'   - `diff_p`: p-value of risk difference using M&N method.
-#'   - `dur`: Average of AE duration.
-#'   - `events`: Average number of AE per subject.
+#'   - `dur`: Average of adverse event duration.
+#'   - `events`: Average number of adverse event per subject.
 #' @param mock A boolean value to display mock table.
 #'
 #' @return A list of analysis raw datasets.

R/format_ae_specific_subgroup.R

@@ -16,25 +16,25 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Format AE specific analysis
+#' Format AE specific subgroup analysis
 #'
 #' @inheritParams format_ae_specific
 #' @param digits_prop A numeric value of number of digits for proportion value.
-#' @param digits_ci A numeric value of number of digits for confidence interval
-#' @param digits_p A numeric value of number of digits for p-value .
+#' @param digits_ci A numeric value of number of digits for confidence interval.
+#' @param digits_p A numeric value of number of digits for p-value.
 #' @param digits_dur A numeric value of number of digits for
-#'   average duration of AE.
+#'   average duration of adverse event.
 #' @param digits_events A numeric value of number of digits for
-#'   average of number of AE per subjects.
+#'   average of number of adverse event per subjects.
 #' @param display A character vector of measurement to be displayed.
-#'   - `n`: Number of subjects with AE.
-#'   - `prop`: Proportion of subjects with AE.
+#'   - `n`: Number of subjects with adverse event.
+#'   - `prop`: Proportion of subjects with adverse event.
 #'   - `total`: Total columns.
-#'   - `dur`: Average of AE duration.
-#'   - `events`: Average number of AE per subject.
+#'   - `dur`: Average of adverse event duration.
+#'   - `events`: Average number of adverse event per subject.
 #' @param mock Logical. Display mock table or not.
 #'
-#' @return A list of analysis raw datasets.
+#' @return A list of analysis raw datasets for subgroup analysis.
 #'
 #' @export
 #'
@@ -100,7 +100,7 @@ format_ae_specific_subgroup <- function(
     }
   }
 
-  # Need order column from Total Column for Ordering properly across tables
+  # Need order column from total column for ordering properly across tables
   tbl <- tbl[order(tbl$order), ]
 
   # If outdata$display_subgroup_total = FALSE, remove that part

R/outdata.R

@@ -1,7 +1,9 @@
 #' Evaluate a call using outdata
 #'
-#' @param outdata a outdata object.
-#' @param call a function call that require `outdata` object as an input.
+#' @param outdata An outdata object.
+#' @param call A function call that require `outdata` object as an input.
+#'
+#' @return outdata object
 #'
 #' @noRd
 outdata_eval_extend_call <- function(outdata, call) {
@@ -11,8 +13,8 @@ outdata_eval_extend_call <- function(outdata, call) {
 
 #' Evaluate a call using outdata
 #'
-#' @param outdata a outdata object.
-#' @param call a function call that require `outdata` object as an input.
+#' @param outdata An outdata object.
+#' @param call A function call that require `outdata` object as an input.
 #'
 #' @noRd
 outdata_eval_prepare_call <- function(outdata) {

R/prepare_ae_listing.R

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Prepare datasets for AE specific analysis
+#' Prepare datasets for AE listing
 #'
 #' @param meta A metadata object created by metalite.
 #' @param analysis Analysis name from `meta`.
@@ -27,7 +27,7 @@
 #' @param parameter A character value of parameter term name.
 #'   The term name is used as key to link information.
 #'
-#' @return A list of analysis raw datasets.
+#' @return A list of analysis datasets needed for AE listing.
 #'
 #' @import metalite
 #'

R/prepare_ae_specific.R

@@ -29,7 +29,7 @@
 #' @param reference_group An integer to indicate reference group.
 #'   Default is 2 if there are 2 groups, otherwise, the default is 1.
 #'
-#' @return A list of analysis raw datasets.
+#' @return A list of analysis datasets needed for AE specific analysis.
 #'
 #' @import metalite
 #'

R/prepare_ae_specific_subgroup.R

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Prepare datasets for AE specific analysis
+#' Prepare datasets for AE specific subgroup analysis
 #'
 #' @inheritParams prepare_ae_specific
 #' @param subgroup_var A character value of subgroup variable name in
@@ -27,7 +27,7 @@
 #' @param display_subgroup_total Logical. Display total column for
 #'   subgroup analysis or not.
 #'
-#' @return A list of analysis raw datasets.
+#' @return A list of analysis datasets needed for AE specific subgroup analysis.
 #'
 #' @export
 #'

R/prepare_ae_summary.R

@@ -16,12 +16,12 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Prepare datasets for AE specific analysis
+#' Prepare datasets for AE summary
 #'
 #' @inheritParams prepare_ae_specific
 #' @param ... Additional arguments passed to [prepare_ae_specific()].
 #'
-#' @return A list of analysis raw datasets.
+#' @return A list of analysis datasets needed for AE summary.
 #'
 #' @export
 #'

R/rate_compare.R

@@ -16,10 +16,10 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Unstratified and stratified  Miettinen and Nurminen test
+#' Unstratified and stratified Miettinen and Nurminen test
 #'
-#' Unstratified and stratified  Miettinen and Nurminen test.
-#' Details can be found in `vignette("rate-compare")`.
+#' Unstratified and stratified Miettinen and Nurminen test details can be found
+#' in `vignette("rate-compare")`.
 #'
 #' @param formula A symbolic description of the model to be fitted,
 #'   which has the form `y ~ x`. Here, `y` is the numeric vector

R/tlf_ae_listing.R

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#' Specific adverse events table
+#' Generate AE listing
 #'
 #' @param outdata An `outdata` object created by [prepare_ae_listing()].
 #' @param footnotes A character vector of table footnotes.
@@ -26,7 +26,7 @@
 #' @param path_outdata A character string of the outdata path.
 #' @param path_outtable A character string of the outtable path.
 #'
-#' @return RTF file and source dataset for AE listing.
+#' @return RTF file and the source dataset for AE listing.
 #'
 #' @export
 #'