From d277c9c5da155ee3204ca65a29d4a6fb4c2ec447 Mon Sep 17 00:00:00 2001 From: "mike.stackhouse" Date: Fri, 26 Jan 2024 21:10:30 +0000 Subject: [PATCH] Update documentation to add note relavent to #160 --- R/count_bindings.R | 4 ++++ R/pop_data.R | 36 +++++++++++++++++++++--------------- man/add_total_row.Rd | 4 ++++ man/treat_grps.Rd | 36 +++++++++++++++++++++--------------- 4 files changed, 50 insertions(+), 30 deletions(-) diff --git a/R/count_bindings.R b/R/count_bindings.R index 291779e3..197c6757 100644 --- a/R/count_bindings.R +++ b/R/count_bindings.R @@ -12,6 +12,10 @@ #' use \code{set_denoms_by()}, and the grouping of \code{add_total_row()} will #' be updated accordingly. #' +#' Note that when using \code{add_total_row()} with \code{set_pop_data()}, you +#' should call \code{add_total_row()} AFTER calling \code{set_pop_data()}, +#' otherwise there is potential for unexpected behaivior with treatment groups. +#' #' @param e A \code{count_layer} object #' @param fmt An f_str object used to format the total row. If none is provided, #' display is based on the layer formatting. diff --git a/R/pop_data.R b/R/pop_data.R index ee98174e..9e79f1d0 100644 --- a/R/pop_data.R +++ b/R/pop_data.R @@ -36,27 +36,33 @@ build_header_n <- function(table) { #' Combine existing treatment groups for summary #' -#' Summary tables often present individual treatment groups, -#' but may additionally have a "Treatment vs. Placebo" or "Total" group added -#' to show grouped summary statistics or counts. This set of functions offers -#' an interface to add these groups at a table level and be consumed by -#' subsequent layers. +#' Summary tables often present individual treatment groups, but may +#' additionally have a "Treatment vs. Placebo" or "Total" group added to show +#' grouped summary statistics or counts. This set of functions offers an +#' interface to add these groups at a table level and be consumed by subsequent +#' layers. #' #' \code{add_treat_grps} allows you to specify specific groupings. This is done -#' by supplying named arguments, where the name becomes the new treatment group's -#' name, and those treatment groups are made up of the argument's values. +#' by supplying named arguments, where the name becomes the new treatment +#' group's name, and those treatment groups are made up of the argument's +#' values. #' -#' \code{add_total_group} is a simple wrapper around \code{add_treat_grps}. Instead of -#' producing custom groupings, it produces a "Total" group by the supplied name, which -#' defaults to "Total". This "Total" group is made up of all existing treatment -#' groups within the population dataset. +#' \code{add_total_group} is a simple wrapper around \code{add_treat_grps}. +#' Instead of producing custom groupings, it produces a "Total" group by the +#' supplied name, which defaults to "Total". This "Total" group is made up of +#' all existing treatment groups within the population dataset. #' -#' The function \code{treat_grps} allows you to see the custom treatment groups available -#' in your \code{tplyr_table} object +#' Note that when using \code{add_treat_grps} or \code{add_total_row()} with +#' \code{set_pop_data()}, you should call \code{add_total_row()} AFTER calling +#' \code{set_pop_data()}, otherwise there is potential for unexpected behaivior +#' with treatment groups. +#' +#' The function \code{treat_grps} allows you to see the custom treatment groups +#' available in your \code{tplyr_table} object #' #' @param table A \code{tplyr_table} object -#' @param ... A named vector where names will become the new treatment group names, -#' and values will be used to construct those treatment groups +#' @param ... A named vector where names will become the new treatment group +#' names, and values will be used to construct those treatment groups #' #' @return The modified table object #' @export diff --git a/man/add_total_row.Rd b/man/add_total_row.Rd index c9ca5f97..102423db 100644 --- a/man/add_total_row.Rd +++ b/man/add_total_row.Rd @@ -33,6 +33,10 @@ total and the application of denominators becomes ambiguous. You will be warned specifically if a percent is included in the format. To rectify this, use \code{set_denoms_by()}, and the grouping of \code{add_total_row()} will be updated accordingly. + +Note that when using \code{add_total_row()} with \code{set_pop_data()}, you +should call \code{add_total_row()} AFTER calling \code{set_pop_data()}, +otherwise there is potential for unexpected behaivior with treatment groups. } \examples{ # Load in Pipe diff --git a/man/treat_grps.Rd b/man/treat_grps.Rd index 1ed42a3e..d133bb87 100644 --- a/man/treat_grps.Rd +++ b/man/treat_grps.Rd @@ -15,8 +15,8 @@ treat_grps(table) \arguments{ \item{table}{A \code{tplyr_table} object} -\item{...}{A named vector where names will become the new treatment group names, -and values will be used to construct those treatment groups} +\item{...}{A named vector where names will become the new treatment group +names, and values will be used to construct those treatment groups} \item{group_name}{The treatment group name used for the constructed 'Total' group} } @@ -24,24 +24,30 @@ and values will be used to construct those treatment groups} The modified table object } \description{ -Summary tables often present individual treatment groups, -but may additionally have a "Treatment vs. Placebo" or "Total" group added -to show grouped summary statistics or counts. This set of functions offers -an interface to add these groups at a table level and be consumed by -subsequent layers. +Summary tables often present individual treatment groups, but may +additionally have a "Treatment vs. Placebo" or "Total" group added to show +grouped summary statistics or counts. This set of functions offers an +interface to add these groups at a table level and be consumed by subsequent +layers. } \details{ \code{add_treat_grps} allows you to specify specific groupings. This is done -by supplying named arguments, where the name becomes the new treatment group's -name, and those treatment groups are made up of the argument's values. +by supplying named arguments, where the name becomes the new treatment +group's name, and those treatment groups are made up of the argument's +values. -\code{add_total_group} is a simple wrapper around \code{add_treat_grps}. Instead of -producing custom groupings, it produces a "Total" group by the supplied name, which -defaults to "Total". This "Total" group is made up of all existing treatment -groups within the population dataset. +\code{add_total_group} is a simple wrapper around \code{add_treat_grps}. +Instead of producing custom groupings, it produces a "Total" group by the +supplied name, which defaults to "Total". This "Total" group is made up of +all existing treatment groups within the population dataset. -The function \code{treat_grps} allows you to see the custom treatment groups available -in your \code{tplyr_table} object +Note that when using \code{add_treat_grps} or \code{add_total_row()} with +\code{set_pop_data()}, you should call \code{add_total_row()} AFTER calling +\code{set_pop_data()}, otherwise there is potential for unexpected behaivior +with treatment groups. + +The function \code{treat_grps} allows you to see the custom treatment groups +available in your \code{tplyr_table} object } \examples{ tab <- tplyr_table(iris, Species)