# Count the number of patients with particular flags

Source:`R/count_patients_with_flags.R`

`count_patients_with_flags.Rd`

## Usage

```
count_patients_with_flags(
lyt,
var,
flag_variables,
flag_labels = NULL,
var_labels = var,
show_labels = "hidden",
riskdiff = FALSE,
na_str = default_na_str(),
nested = TRUE,
...,
table_names = paste0("tbl_flags_", var),
.stats = "count_fraction",
.formats = NULL,
.indent_mods = NULL
)
s_count_patients_with_flags(
df,
.var,
flag_variables,
flag_labels = NULL,
.N_col,
.N_row,
denom = c("n", "N_row", "N_col")
)
a_count_patients_with_flags(
df,
.var,
flag_variables,
flag_labels = NULL,
.N_col,
.N_row,
denom = c("n", "N_row", "N_col")
)
```

## 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.- flag_variables
(

`character`

)

a vector specifying the names of`logical`

variables from analysis dataset used for counting the number of unique identifiers.- flag_labels
(

`character`

)

vector of labels to use for flag variables.- var_labels
(

`character`

)

variable labels.- 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 the case that the same`vars`

are analyzed multiple times, to avoid warnings from`rtables`

.- .stats
(

`character`

)

statistics to select for the table. Run`get_stats("count_patients_with_flags")`

to see available statistics for this function.- .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.- df
(

`data.frame`

)

data set containing all analysis variables.- .var
(

`string`

)

name of the column that contains the unique identifier.- .N_col
(

`integer(1)`

)

column-wise N (column count) for the full column being analyzed that is typically passed by`rtables`

.- .N_row
(

`integer(1)`

)

row-wise N (row group count) for the group of observations being analyzed (i.e. with no column-based subsetting) that is typically passed by`rtables`

.- denom
(

`string`

)

choice of denominator for proportion. Options are:`n`

: number of values in this row and column intersection.`N_row`

: total number of values in this row across columns.`N_col`

: total number of values in this column across rows.

## Value

`count_patients_with_flags()`

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_patients_with_flags()`

to the table layout.

`s_count_patients_with_flags()`

returns the count and the fraction of unique identifiers with each particular flag as a list of statistics`n`

,`count`

,`count_fraction`

, and`n_blq`

, with one element per flag.

`a_count_patients_with_flags()`

returns the corresponding list with formatted`rtables::CellValue()`

.

## Functions

`count_patients_with_flags()`

: Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for`rtables::analyze()`

.`s_count_patients_with_flags()`

: Statistics function which counts the number of patients for which a particular flag variable is`TRUE`

.`a_count_patients_with_flags()`

: Formatted analysis function which is used as`afun`

in`count_patients_with_flags()`

.

## Note

If `flag_labels`

is not specified, variables labels will be extracted from `df`

. If variables are not
labeled, variable names will be used instead. Alternatively, a named `vector`

can be supplied to
`flag_variables`

such that within each name-value pair the name corresponds to the variable name and the value is
the label to use for this variable.

## Examples

```
library(dplyr)
# Add labelled flag variables to analysis dataset.
adae <- tern_ex_adae %>%
mutate(
fl1 = TRUE %>% with_label("Total AEs"),
fl2 = (TRTEMFL == "Y") %>%
with_label("Total number of patients with at least one adverse event"),
fl3 = (TRTEMFL == "Y" & AEOUT == "FATAL") %>%
with_label("Total number of patients with fatal AEs"),
fl4 = (TRTEMFL == "Y" & AEOUT == "FATAL" & AEREL == "Y") %>%
with_label("Total number of patients with related fatal AEs")
)
# `count_patients_with_flags()`
lyt2 <- basic_table() %>%
split_cols_by("ARM") %>%
add_colcounts() %>%
count_patients_with_flags(
"SUBJID",
flag_variables = c("fl1", "fl2", "fl3", "fl4"),
denom = "N_col"
)
build_table(lyt2, adae, alt_counts_df = tern_ex_adsl)
#> A: Drug X B: Placebo C: Combination
#> (N=69) (N=73) (N=58)
#> ———————————————————————————————————————————————————————————————————————————————————————————————————
#> Total AEs 59 (85.5%) 57 (78.1%) 48 (82.8%)
#> Total number of patients with at least one adverse event 59 (85.5%) 57 (78.1%) 48 (82.8%)
#> Total number of patients with fatal AEs 28 (40.6%) 31 (42.5%) 20 (34.5%)
#> Total number of patients with related fatal AEs 28 (40.6%) 31 (42.5%) 20 (34.5%)
# `s_count_patients_with_flags()`
s_count_patients_with_flags(
adae,
"SUBJID",
flag_variables = c("fl1", "fl2", "fl3", "fl4"),
denom = "N_col",
.N_col = 1000
)
#> $n
#> $n$`Total AEs`
#> [1] 164
#>
#> $n$`Total number of patients with at least one adverse event`
#> [1] 164
#>
#> $n$`Total number of patients with fatal AEs`
#> [1] 164
#>
#> $n$`Total number of patients with related fatal AEs`
#> [1] 164
#>
#>
#> $count
#> $count$`Total AEs`
#> [1] 164
#>
#> $count$`Total number of patients with at least one adverse event`
#> [1] 164
#>
#> $count$`Total number of patients with fatal AEs`
#> [1] 79
#>
#> $count$`Total number of patients with related fatal AEs`
#> [1] 79
#>
#>
#> $count_fraction
#> $count_fraction$`Total AEs`
#> [1] 164.000 0.164
#>
#> $count_fraction$`Total number of patients with at least one adverse event`
#> [1] 164.000 0.164
#>
#> $count_fraction$`Total number of patients with fatal AEs`
#> [1] 79.000 0.079
#>
#> $count_fraction$`Total number of patients with related fatal AEs`
#> [1] 79.000 0.079
#>
#>
#> $n_blq
#> $n_blq$`Total AEs`
#> [1] 0
#>
#> $n_blq$`Total number of patients with at least one adverse event`
#> [1] 0
#>
#> $n_blq$`Total number of patients with fatal AEs`
#> [1] 0
#>
#> $n_blq$`Total number of patients with related fatal AEs`
#> [1] 0
#>
#>
# We need to ungroup `count_fraction` first so that the `rtables` formatting
# function `format_count_fraction()` can be applied correctly.
# `a_count_patients_with_flags()`
afun <- make_afun(a_count_patients_with_flags,
.stats = "count_fraction",
.ungroup_stats = "count_fraction"
)
afun(
adae,
.N_col = 10L,
.N_row = 10L,
.var = "USUBJID",
flag_variables = c("fl1", "fl2", "fl3", "fl4")
)
#> RowsVerticalSection (in_rows) object print method:
#> ----------------------------
#> row_name formatted_cell
#> 1 Total AEs 164 (100%)
#> 2 Total number of patients with at least one adverse event 164 (100%)
#> 3 Total number of patients with fatal AEs 79 (48.2%)
#> 4 Total number of patients with related fatal AEs 79 (48.2%)
#> indent_mod row_label
#> 1 0 Total AEs
#> 2 0 Total number of patients with at least one adverse event
#> 3 0 Total number of patients with fatal AEs
#> 4 0 Total number of patients with related fatal AEs
```