More information needed about the `drop_split_levels()` function in the {rtables} R package

More details are needed to explain what the drop_split_levels() function is doing in the rtables documentation/"Split functions" reference site (https://insightsengineering.github.io/rtables/latest-tag/reference/split_funcs.html#ref-examples).

It is unclear what this function does based on the example and associated output.

library(rtables)
#> Loading required package: formatters
#> 
#> Attaching package: 'formatters'
#> The following object is masked from 'package:base':
#> 
#>     %||%
#> Loading required package: magrittr
#> 
#> Attaching package: 'rtables'
#> The following object is masked from 'package:utils':
#> 
#>     str
lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_rows_by("SEX", split_fun = drop_split_levels) %>%
  analyze("AGE")

tbl <- build_table(lyt, DM)
tbl
#>          A: Drug X   B: Placebo   C: Combination
#> ————————————————————————————————————————————————
#> F                                               
#>   Mean     33.71       33.84          34.89     
#> M                                               
#>   Mean     36.55       32.10          34.28

^{Created on 2024-07-25 with reprex v2.1.1}

It would additionally be helpful to include more examples with various function arguments specified.

Thank you!

Solution

drop_split_levels removes levels that do not appear in the data in a specific split (partitioning column). If you print the number of elements per each factor level, you see that c("U", "UNDIFFERENTIATED") are absent. In the following, you can also see the different outputs for having or not having drop_split_levels as a split function:

library(rtables)
#> Loading required package: formatters
#> 
#> Attaching package: 'formatters'
#> The following object is masked from 'package:base':
#> 
#>     %||%
#> Loading required package: magrittr
#> 
#> Attaching package: 'rtables'
#> The following object is masked from 'package:utils':
#> 
#>     str

print(table(DM$SEX))
#> 
#>                F                M                U UNDIFFERENTIATED 
#>              187              169                0                0

basic_table(title = "Without drop_split_levels") |> 
  split_rows_by("SEX") |> 
  analyze("AGE") |> 
  build_table(DM)
#> Without drop_split_levels
#> 
#> ——————————————————————————
#>                    all obs
#> ——————————————————————————
#> F                         
#>   Mean              34.13 
#> M                         
#>   Mean              34.32 
#> U                         
#>   Mean               NA   
#> UNDIFFERENTIATED          
#>   Mean               NA
basic_table(title = "With drop_split_levels") |> 
  split_rows_by("SEX", split_fun = drop_split_levels) |> 
  analyze("AGE") |> 
  build_table(DM)
#> With drop_split_levels
#> 
#> ————————————————
#>          all obs
#> ————————————————
#> F               
#>   Mean    34.13 
#> M               
#>   Mean    34.32

^{Created on 2024-07-29 with reprex v2.1.1}