Counting Patients Summing Exposure Across All Patients in Columns — summarize_patients_exposure_in

Counting the number of patients and summing analysis value (i.e exposure values) across all patients when a column table layout is required.

Usage

s_count_patients_sum_exposure(
  df,
  ex_var = "AVAL",
  id = "USUBJID",
  labelstr = "",
  .stats = c("n_patients", "sum_exposure"),
  .N_col,
  custom_label = NULL
)

a_count_patients_sum_exposure(
  df,
  var = NULL,
  ex_var = "AVAL",
  id = "USUBJID",
  labelstr = "",
  add_total_level = FALSE,
  .N_col,
  .stats,
  .formats = list(n_patients = "xx (xx.x%)", sum_exposure = "xx"),
  custom_label = NULL
)

summarize_patients_exposure_in_cols(
  lyt,
  var,
  na_str = NA_character_,
  ...,
  .stats = c("n_patients", "sum_exposure"),
  .labels = c(n_patients = "Patients", sum_exposure = "Person time"),
  .indent_mods = NULL,
  col_split = TRUE
)

analyze_patients_exposure_in_cols(
  lyt,
  var = NULL,
  ex_var = "AVAL",
  col_split = TRUE,
  add_total_level = FALSE,
  .stats = c("n_patients", "sum_exposure"),
  .labels = c(n_patients = "Patients", sum_exposure = "Person time"),
  .indent_mods = 0L,
  ...
)

Arguments

df: (data.frame)
data set containing all analysis variables.
ex_var: (character)
name of the variable within df containing exposure values.
id: (string)
subject variable name.
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.
.stats: (character)
statistics to select for the table.
.N_col: (integer)
column-wise N (column count) for the full column being analyzed that is typically passed by rtables.
custom_label: (string or NULL)
if provided and labelstr is empty then this will be used as label.
var: (string)
single variable name that is passed by rtables when requested by a statistics function.
add_total_level: (flag)
adds a "total" level after the others which includes all the levels that constitute the split. A custom label can be set for this level via the custom_label argument.
.formats: (named character or list)
formats for the statistics. See Details in analyze_vars for more information on the "auto" setting.
lyt: (layout)
input layout where analyses will be added to.
na_str: (string)
string used to replace all NA or empty values in the output.
...: additional arguments for the lower level functions.
.labels: (named character)
labels for the statistics (without indent).
.indent_mods: (named integer)
indent modifiers for the labels. Defaults to 0, which corresponds to the unmodified default behavior. Can be negative.
col_split: (flag)
whether the columns should be split. Set to FALSE when the required column split has been done already earlier in the layout pipe.

Value

s_count_patients_sum_exposure() returns a named list with the statistics:
- n_patients: Number of unique patients in df.
- sum_exposure: Sum of ex_var across all patients in df.

a_count_patients_sum_exposure() returns formatted rtables::CellValue().

summarize_patients_exposure_in_cols() 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, with the statistics from s_count_patients_sum_exposure() arranged in columns, to the table layout.

analyze_patients_exposure_in_cols() 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 data rows, with the statistics from s_count_patients_sum_exposure() arranged in columns, to the table layout.

Functions

s_count_patients_sum_exposure(): Statistics function which counts numbers of patients and the sum of exposure across all patients.
a_count_patients_sum_exposure(): Analysis function which is used as afun in rtables::analyze_colvars() within analyze_patients_exposure_in_cols() and as cfun in rtables::summarize_row_groups() within summarize_patients_exposure_in_cols().
summarize_patients_exposure_in_cols(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::split_cols_by_multivar() and rtables::summarize_row_groups().
analyze_patients_exposure_in_cols(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::split_cols_by_multivar() and rtables::analyze_colvars().

Note

As opposed to summarize_patients_exposure_in_cols() which generates content rows, analyze_patients_exposure_in_cols() generates data rows which will not be repeated on multiple pages when pagination is used.

Examples

set.seed(1)
df <- data.frame(
  USUBJID = c(paste("id", seq(1, 12), sep = "")),
  ARMCD = c(rep("ARM A", 6), rep("ARM B", 6)),
  SEX = c(rep("Female", 6), rep("Male", 6)),
  AVAL = as.numeric(sample(seq(1, 20), 12)),
  stringsAsFactors = TRUE
)
adsl <- data.frame(
  USUBJID = c(paste("id", seq(1, 12), sep = "")),
  ARMCD = c(rep("ARM A", 2), rep("ARM B", 2)),
  SEX = c(rep("Female", 2), rep("Male", 2)),
  stringsAsFactors = TRUE
)

a_count_patients_sum_exposure(
  df = df,
  var = "SEX",
  .N_col = nrow(df),
  .stats = "n_patients"
)
#> RowsVerticalSection (in_rows) object print method:
#> ----------------------------
#>   row_name formatted_cell indent_mod row_label
#> 1   Female      6 (50.0%)          0    Female
#> 2     Male      6 (50.0%)          0      Male

lyt <- basic_table() %>%
  summarize_patients_exposure_in_cols(var = "AVAL", col_split = TRUE)
result <- build_table(lyt, df = df, alt_counts_df = adsl)
result
#>                                       Patients     Person time
#> ——————————————————————————————————————————————————————————————
#> Total patients numbers/person time   12 (100.0%)       114    

lyt2 <- basic_table() %>%
  summarize_patients_exposure_in_cols(var = "AVAL", col_split = TRUE, .stats = "sum_exposure")
result2 <- build_table(lyt2, df = df, alt_counts_df = adsl)
result2
#>                                      Person time
#> ————————————————————————————————————————————————
#> Total patients numbers/person time       114    

lyt3 <- basic_table() %>%
  split_cols_by("ARMCD", split_fun = add_overall_level("Total", first = FALSE)) %>%
  summarize_patients_exposure_in_cols(var = "AVAL", col_split = TRUE) %>%
  analyze_patients_exposure_in_cols(var = "SEX", col_split = FALSE)
result3 <- build_table(lyt3, df = df, alt_counts_df = adsl)
result3
#>                                               ARM A                      ARM B                       Total          
#>                                       Patients    Person time    Patients    Person time    Patients     Person time
#> ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
#> Total patients numbers/person time   6 (100.0%)       46        6 (100.0%)       68        12 (100.0%)       114    
#>   Female                             6 (100.0%)       46         0 (0.0%)         0         6 (50.0%)        46     
#>   Male                                0 (0.0%)         0        6 (100.0%)       68         6 (50.0%)        68     

lyt4 <- basic_table() %>%
  split_cols_by("ARMCD", split_fun = add_overall_level("Total", first = FALSE)) %>%
  summarize_patients_exposure_in_cols(
    var = "AVAL", col_split = TRUE,
    .stats = "n_patients", custom_label = "some custom label"
  ) %>%
  analyze_patients_exposure_in_cols(var = "SEX", col_split = FALSE, ex_var = "AVAL")
result4 <- build_table(lyt4, df = df, alt_counts_df = adsl)
result4
#>                       ARM A        ARM B         Total   
#>                      Patients     Patients     Patients  
#> —————————————————————————————————————————————————————————
#> some custom label   6 (100.0%)   6 (100.0%)   12 (100.0%)
#>   Female            6 (100.0%)    0 (0.0%)     6 (50.0%) 
#>   Male               0 (0.0%)    6 (100.0%)    6 (50.0%) 

lyt5 <- basic_table() %>%
  analyze_patients_exposure_in_cols(var = "SEX", col_split = TRUE, ex_var = "AVAL")
result5 <- build_table(lyt5, df = df, alt_counts_df = adsl)
result5
#>          Patients    Person time
#> ————————————————————————————————
#> Female   6 (50.0%)       46     
#> Male     6 (50.0%)       68     

# Adding total levels and custom label
lyt <- basic_table(
  show_colcounts = TRUE
) %>%
  analyze_patients_exposure_in_cols(
    var = "ARMCD",
    col_split = TRUE,
    add_total_level = TRUE,
    custom_label = "TOTAL"
  ) %>%
  append_topleft(c("", "Sex"))

tbl <- build_table(lyt, df = df, alt_counts_df = adsl)
tbl
#>          Patients     Person time
#> Sex       (N=12)        (N=12)   
#> —————————————————————————————————
#> ARM A    6 (50.0%)        46     
#> ARM B    6 (50.0%)        68     
#> TOTAL   12 (100.0%)       114