# Count number of patients and sum exposure across all patients in columns The analyze function `analyze_patients_exposure_in_cols()` creates a layout element to count total numbers of patients and sum an analysis value (i.e. exposure) across all patients in columns. The primary analysis variable `ex_var` is the exposure variable used to calculate the `sum_exposure` statistic. The `id` variable is used to uniquely identify patients in the data such that only unique patients are counted in the `n_patients` statistic, and the `var` variable is used to create a row split if needed. The percentage returned as part of the `n_patients` statistic is the proportion of all records that correspond to a unique patient. The summarize function `summarize_patients_exposure_in_cols()` performs the same function as `analyze_patients_exposure_in_cols()` except it creates content rows, not data rows, to summarize the current table row/column context and operates on the level of the latest row split or the root of the table if no row splits have occurred. If a column split has not yet been performed in the table, `col_split` must be set to `TRUE` for the first call of `analyze_patients_exposure_in_cols()` or `summarize_patients_exposure_in_cols()`. ```r analyze_patients_exposure_in_cols( lyt, var = NULL, ex_var = "AVAL", id = "USUBJID", add_total_level = FALSE, custom_label = NULL, col_split = TRUE, na_str = default_na_str(), .stats = c("n_patients", "sum_exposure"), .stat_names = NULL, .formats = NULL, .labels = c(n_patients = "Patients", sum_exposure = "Person time"), .indent_mods = NULL, ... ) summarize_patients_exposure_in_cols( lyt, var, ex_var = "AVAL", id = "USUBJID", add_total_level = FALSE, custom_label = NULL, col_split = TRUE, na_str = default_na_str(), ..., .stats = c("n_patients", "sum_exposure"), .stat_names = NULL, .formats = NULL, .labels = c(n_patients = "Patients", sum_exposure = "Person time"), .indent_mods = NULL ) s_count_patients_sum_exposure( df, labelstr = "", .stats = c("n_patients", "sum_exposure"), .N_col, ..., ex_var = "AVAL", id = "USUBJID", custom_label = NULL, var_level = NULL ) a_count_patients_sum_exposure( df, labelstr = "", ..., .stats = NULL, .stat_names = NULL, .formats = NULL, .labels = NULL, .indent_mods = NULL ) ``` ## Arguments - `lyt`: (`PreDataTableLayouts`) layout that analyses will be added to. - `var`: (`string`) single variable name that is passed by `rtables` when requested by a statistics function. - `ex_var`: (`string`) name of the variable in `df` containing exposure values. - `id`: (`string`) subject variable name. - `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. - `custom_label`: (`string` or `NULL`) if provided and `labelstr` is empty, this will be used as label. - `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. - `na_str`: (`string`) string used to replace all `NA` or empty values in the output. - `.stats`: (`character`) statistics to select for the table. Options are: `'n_patients', 'sum_exposure'` - `.stat_names`: (`character`) names of the statistics that are passed directly to name single statistics (`.stats`). This option is visible when producing `rtables::as_result_df()` with `make_ard = TRUE`. - `.formats`: (named `character` or `list`) formats for the statistics. See Details in `analyze_vars` for more information on the `"auto"` setting. - `.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. - `...`: additional arguments for the lower level functions. - `df`: (`data.frame`) data set containing all analysis variables. - `labelstr`: (`string`) 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. - `.N_col`: (`integer(1)`) column-wise N (column count) for the full column being analyzed that is typically passed by `rtables`. ## Returns * `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. * `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. * `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()`. ## Functions * `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()`. * `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()`. * `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()`. ## 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 ```r 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 ) lyt <- 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) result <- build_table(lyt, df = df, alt_counts_df = adsl) result lyt2 <- 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") result2 <- build_table(lyt2, df = df, alt_counts_df = adsl) result2 lyt3 <- basic_table() %>% analyze_patients_exposure_in_cols(var = "SEX", col_split = TRUE, ex_var = "AVAL") result3 <- build_table(lyt3, df = df, alt_counts_df = adsl) result3 # Adding total levels and custom label lyt4 <- 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")) result4 <- build_table(lyt4, df = df, alt_counts_df = adsl) result4 lyt5 <- basic_table() %>% summarize_patients_exposure_in_cols(var = "AVAL", col_split = TRUE) result5 <- build_table(lyt5, df = df, alt_counts_df = adsl) result5 lyt6 <- basic_table() %>% summarize_patients_exposure_in_cols(var = "AVAL", col_split = TRUE, .stats = "sum_exposure") result6 <- build_table(lyt6, df = df, alt_counts_df = adsl) result6 ```

summarize_patients_exposure_in_cols function