Occurrence Counts by Grade

Functions for analyzing frequencies and fractions of occurrences by grade for patients with occurrence data. Multiple occurrences within one individual are counted once at the greatest intensity/highest grade level.

Usage

s_count_occurrences_by_grade(
  df,
  .var,
  .N_col,
  id = "USUBJID",
  grade_groups = list(),
  remove_single = TRUE,
  labelstr = ""
)

a_count_occurrences_by_grade(
  df,
  .var,
  .N_col,
  id = "USUBJID",
  grade_groups = list(),
  remove_single = TRUE,
  labelstr = ""
)

count_occurrences_by_grade(
  lyt,
  var,
  var_labels = var,
  show_labels = "default",
  riskdiff = FALSE,
  na_str = NA_character_,
  nested = TRUE,
  ...,
  table_names = var,
  .stats = NULL,
  .formats = NULL,
  .indent_mods = NULL,
  .labels = NULL
)

summarize_occurrences_by_grade(
  lyt,
  var,
  na_str = NA_character_,
  ...,
  .stats = NULL,
  .formats = NULL,
  .indent_mods = NULL,
  .labels = NULL
)

Arguments

df: (data.frame)
data set containing all analysis variables.
.var, var: (string)
single variable name that is passed by rtables when requested by a statistics function.
.N_col: (integer)
column-wise N (column count) for the full column being analyzed that is typically passed by rtables.
id: (string)
subject variable name.
grade_groups: (named list of character)
containing groupings of grades.
remove_single: (logical)
TRUE to not include the elements of one-element grade groups in the the output list; in this case only the grade groups names will be included in the output.
labelstr: (character)
label of the level of the parent split currently being summarized (must be present as second argument in Content Row Functions). See rtables::summarize_row_groups() for more information.
lyt: (layout)
input layout where analyses will be added to.
var_labels: (character)
labels to show in the result table.
show_labels: (string)
label visibility: one of "default", "visible" and "hidden".
riskdiff: (flag)
whether a risk difference column is present. When set to TRUE, add_riskdiff() must be used as split_fun in the prior column split of the table layout, specifying which columns should be compared. See stat_propdiff_ci() for details on risk difference calculation.
na_str: (string)
string used to replace all NA or empty values in the output.
nested: (flag)
whether this layout instruction should be applied within the existing layout structure if possible (TRUE, the default) or as a new top-level element (FALSE). Ignored if it would nest a split. underneath analyses, which is not allowed.
...: additional arguments for the lower level functions.
table_names: (character)
this can be customized in case that the same vars are analyzed multiple times, to avoid warnings from rtables.
.stats: (character)
statistics to select for the table.
.formats: (named character or list)
formats for the statistics. See Details in analyze_vars for more information on the "auto" setting.
.indent_mods: (named integer)
indent modifiers for the labels. Defaults to 0, which corresponds to the unmodified default behavior. Can be negative.
.labels: (named character)
labels for the statistics (without indent).

Value

s_count_occurrences_by_grade() returns a list of counts and fractions with one element per grade level or grade level grouping.

a_count_occurrences_by_grade() returns the corresponding list with formatted rtables::CellValue().

count_occurrences_by_grade() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_occurrences_by_grade() to the table layout.

summarize_occurrences_by_grade() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted content rows containing the statistics from s_count_occurrences_by_grade() to the table layout.

Functions

s_count_occurrences_by_grade(): Statistics function which counts the number of patients by highest grade.
a_count_occurrences_by_grade(): Formatted analysis function which is used as afun in count_occurrences_by_grade().
count_occurrences_by_grade(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().
summarize_occurrences_by_grade(): Layout-creating function which can take content function arguments and additional format arguments. This function is a wrapper for rtables::summarize_row_groups().

Examples

library(dplyr)
df <- data.frame(
  USUBJID = as.character(c(1:6, 1)),
  ARM = factor(c("A", "A", "A", "B", "B", "B", "A"), levels = c("A", "B")),
  AETOXGR = factor(c(1, 2, 3, 4, 1, 2, 3), levels = c(1:5)),
  AESEV = factor(
    x = c("MILD", "MODERATE", "SEVERE", "MILD", "MILD", "MODERATE", "SEVERE"),
    levels = c("MILD", "MODERATE", "SEVERE")
  ),
  stringsAsFactors = FALSE
)
df_adsl <- df %>%
  select(USUBJID, ARM) %>%
  unique()

s_count_occurrences_by_grade(
  df,
  .N_col = 10L,
  .var = "AETOXGR",
  id = "USUBJID",
  grade_groups = list("ANY" = levels(df$AETOXGR))
)
#> $count_fraction
#> $count_fraction$ANY
#> [1] 6.0 0.6
#> 
#> $count_fraction$`1`
#> [1] 1.0 0.1
#> 
#> $count_fraction$`2`
#> [1] 2.0 0.2
#> 
#> $count_fraction$`3`
#> [1] 2.0 0.2
#> 
#> $count_fraction$`4`
#> [1] 1.0 0.1
#> 
#> $count_fraction$`5`
#> [1] 0 0
#> 
#> 

#  We need to ungroup `count_fraction` first so that the `rtables` formatting
# function `format_count_fraction()` can be applied correctly.
afun <- make_afun(a_count_occurrences_by_grade, .ungroup_stats = "count_fraction")
afun(
  df,
  .N_col = 10L,
  .var = "AETOXGR",
  id = "USUBJID",
  grade_groups = list("ANY" = levels(df$AETOXGR))
)
#> RowsVerticalSection (in_rows) object print method:
#> ----------------------------
#>   row_name formatted_cell indent_mod row_label
#> 1      ANY      6 (60.0%)          0       ANY
#> 2        1      1 (10.0%)          0         1
#> 3        2      2 (20.0%)          0         2
#> 4        3      2 (20.0%)          0         3
#> 5        4      1 (10.0%)          0         4
#> 6        5              0          0         5

# Layout creating function with custom format.
basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_occurrences_by_grade(
    var = "AESEV",
    .formats = c("count_fraction" = "xx.xx (xx.xx%)")
  ) %>%
  build_table(df, alt_counts_df = df_adsl)
#>                  A               B      
#>                (N=3)           (N=3)    
#> ————————————————————————————————————————
#> MILD       0.00 (0.00%)    2.00 (66.67%)
#> MODERATE   1.00 (33.33%)   1.00 (33.33%)
#> SEVERE     2.00 (66.67%)   0.00 (0.00%) 

# Define additional grade groupings.
grade_groups <- list(
  "-Any-" = c("1", "2", "3", "4", "5"),
  "Grade 1-2" = c("1", "2"),
  "Grade 3-5" = c("3", "4", "5")
)

basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_occurrences_by_grade(
    var = "AETOXGR",
    grade_groups = grade_groups
  ) %>%
  build_table(df, alt_counts_df = df_adsl)
#>                 A           B    
#>               (N=3)       (N=3)  
#> —————————————————————————————————
#> -Any-       3 (100%)    3 (100%) 
#> Grade 1-2   1 (33.3%)   2 (66.7%)
#> 1               0       1 (33.3%)
#> 2           1 (33.3%)   1 (33.3%)
#> Grade 3-5   2 (66.7%)   1 (33.3%)
#> 3           2 (66.7%)       0    
#> 4               0       1 (33.3%)
#> 5               0           0    

# Layout creating function with custom format.
basic_table() %>%
  add_colcounts() %>%
  split_rows_by("ARM", child_labels = "visible", nested = TRUE) %>%
  summarize_occurrences_by_grade(
    var = "AESEV",
    .formats = c("count_fraction" = "xx.xx (xx.xx%)")
  ) %>%
  build_table(df, alt_counts_df = df_adsl)
#>                 all obs   
#>                  (N=6)    
#> ——————————————————————————
#> A                         
#>   MILD       0.00 (0.00%) 
#>   MODERATE   1.00 (16.67%)
#>   SEVERE     2.00 (33.33%)
#> B                         
#>   MILD       2.00 (33.33%)
#>   MODERATE   1.00 (16.67%)
#>   SEVERE     0.00 (0.00%) 

basic_table() %>%
  add_colcounts() %>%
  split_rows_by("ARM", child_labels = "visible", nested = TRUE) %>%
  summarize_occurrences_by_grade(
    var = "AETOXGR",
    grade_groups = grade_groups
  ) %>%
  build_table(df, alt_counts_df = df_adsl)
#>                all obs 
#>                 (N=6)  
#> ———————————————————————
#> A                      
#>   -Any-       3 (50.0%)
#>   Grade 1-2   1 (16.7%)
#>   1               0    
#>   2           1 (16.7%)
#>   Grade 3-5   2 (33.3%)
#>   3           2 (33.3%)
#>   4               0    
#>   5               0    
#> B                      
#>   -Any-       3 (50.0%)
#>   Grade 1-2   2 (33.3%)
#>   1           1 (16.7%)
#>   2           1 (16.7%)
#>   Grade 3-5   1 (16.7%)
#>   3               0    
#>   4           1 (16.7%)
#>   5               0

Usage

Arguments

Value

Functions

See also

Examples