Main Functions
These functions are built on top of the format
functions, providing a quick and straightforward way to format
tables.
visTable()
visTable() is a flexible function designed to format any
<data.frame>.
Let’s demonstrate its usage with a dataset from the
palmerpenguins package.
library(visOmopResults)
library(palmerpenguins)
library(dplyr)
library(tidyr)
x <- penguins |> 
  filter(!is.na(sex) & year == 2008) |> 
  select(!"body_mass_g") |>
  summarise(across(ends_with("mm"), ~mean(.x)), .by = c("species", "island", "sex"))
head(x)
#> # A tibble: 6 × 6
#>   species island    sex    bill_length_mm bill_depth_mm flipper_length_mm
#>   <fct>   <fct>     <fct>           <dbl>         <dbl>             <dbl>
#> 1 Adelie  Biscoe    female           36.6          17.2              187.
#> 2 Adelie  Biscoe    male             40.8          19.0              193.
#> 3 Adelie  Torgersen female           36.6          17.4              190 
#> 4 Adelie  Torgersen male             40.9          18.8              194.
#> 5 Adelie  Dream     female           36.3          17.8              189 
#> 6 Adelie  Dream     male             40.1          18.9              195We can format this data into a <gt> table using
visTable() as follows:
visTable(
  result = x,
  groupColumn = c("sex"),
  rename = c("Bill length (mm)" = "bill_length_mm",
             "Bill depth (mm)" = "bill_depth_mm",
             "Flipper length (mm)" = "flipper_length_mm"),
  type = "gt",
  hide = "year"
)| Species | Island | Bill length (mm) | Bill depth (mm) | Flipper length (mm) | 
|---|---|---|---|---|
| female | ||||
| Adelie | Biscoe | 36.6444444444444 | 17.2222222222222 | 186.555555555556 | 
| Torgersen | 36.6125 | 17.4 | 190 | |
| Dream | 36.275 | 17.7875 | 189 | |
| Gentoo | Biscoe | 45.2954545454545 | 14.1318181818182 | 213 | 
| Chinstrap | Dream | 46 | 17.3 | 192.666666666667 | 
| male | ||||
| Adelie | Biscoe | 40.7555555555556 | 19.0333333333333 | 192.555555555556 | 
| Torgersen | 40.925 | 18.8375 | 193.5 | |
| Dream | 40.1125 | 18.8875 | 195 | |
| Gentoo | Biscoe | 48.5391304347826 | 15.704347826087 | 222.086956521739 | 
| Chinstrap | Dream | 51.4 | 19.6 | 202.777777777778 | 
To use the arguments estimateName and
header, the <data.frame> must have the
estimates arranged into three columns: estimate_name,
estimate_type, and estimate_value. Let’s
reshape the example dataset accordingly and demonstrate creating a
<flextable> object:
# Transforming the dataset to include estimate columns
x <- x |>
  pivot_longer(
    cols = ends_with("_mm"), 
    names_to = "estimate_name", 
    values_to = "estimate_value"
  ) |>
  mutate(estimate_type = "numeric")
# Creating a formatted flextable
visTable(
  result = x,
  estimateName = c(
    "Bill length - Bill depth (mm)" = "<bill_length_mm> - <bill_depth_mm>",
    "Flipper length (mm)" = "<flipper_length_mm>"
  ),
  header = c("species", "island"),
  groupColumn = "sex",
  type = "flextable",
  hide = c("year", "estimate_type")
)| Estimate name | Species | ||||
|---|---|---|---|---|---|
| Adelie | Gentoo | Chinstrap | |||
| Island | |||||
| Biscoe | Torgersen | Dream | Biscoe | Dream | |
| female | |||||
| Bill length - Bill depth (mm) | 36.64 - 17.22 | 36.61 - 17.40 | 36.27 - 17.79 | 45.30 - 14.13 | 46.00 - 17.30 | 
| Flipper length (mm) | 186.56 | 190.00 | 189.00 | 213.00 | 192.67 | 
| male | |||||
| Bill length - Bill depth (mm) | 40.76 - 19.03 | 40.92 - 18.84 | 40.11 - 18.89 | 48.54 - 15.70 | 51.40 - 19.60 | 
| Flipper length (mm) | 192.56 | 193.50 | 195.00 | 222.09 | 202.78 | 
visOmopTable()
visOmopTable() extends the functionality of
visTable() with additional features tailored specifically
for handling <summarised_result> objects, making it
easier to work with standardized result formats.
Let’s demonstrate visOmopTable() with a mock
<summarised_result>:
# Creating a mock summarised result
result <- mockSummarisedResult() |>
  filter(strata_name == "age_group &&& sex")
# Displaying the first few rows
head(result)
#> # A tibble: 6 × 13
#>   result_id cdm_name group_name  group_level strata_name       strata_level   
#>       <int> <chr>    <chr>       <chr>       <chr>             <chr>          
#> 1         1 mock     cohort_name cohort1     age_group &&& sex <40 &&& Male   
#> 2         1 mock     cohort_name cohort1     age_group &&& sex >=40 &&& Male  
#> 3         1 mock     cohort_name cohort1     age_group &&& sex <40 &&& Female 
#> 4         1 mock     cohort_name cohort1     age_group &&& sex >=40 &&& Female
#> 5         1 mock     cohort_name cohort2     age_group &&& sex <40 &&& Male   
#> 6         1 mock     cohort_name cohort2     age_group &&& sex >=40 &&& Male  
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>
# Creating a formatted gt table
visOmopTable(
  result = result,
  estimateName = c(
    "N%" = "<count> (<percentage>)",
    "N" = "<count>",
    "Mean (SD)" = "<mean> (<sd>)"
  ),
  header = c("package_name", "age_group"),
  groupColumn = c("cohort_name", "sex"),
  settingsColumn = "package_name",
  type = "gt"
)| Package name | |||||
|---|---|---|---|---|---|
| visOmopResults | |||||
| CDM name | Variable name | Variable level | Estimate name | Age group | |
| <40 | >=40 | ||||
| cohort1; Male | |||||
| mock | number subjects | - | N | 3,721,239 | 5,728,534 | 
| age | - | Mean (SD) | 77.74 (1.08) | 93.47 (7.24) | |
| Medications | Amoxiciline | N% | 9,947 (33.38) | 31,627 (47.64) | |
| Ibuprofen | N% | 5,893 (59.88) | 64,229 (97.62) | ||
| cohort1; Female | |||||
| mock | number subjects | - | N | 9,082,078 | 2,016,819 | 
| age | - | Mean (SD) | 21.21 (4.11) | 65.17 (8.21) | |
| Medications | Amoxiciline | N% | 51,863 (89.22) | 66,201 (86.43) | |
| Ibuprofen | N% | 87,627 (73.18) | 77,891 (35.67) | ||
| cohort2; Male | |||||
| mock | number subjects | - | N | 2,059,746 | 1,765,568 | 
| age | - | Mean (SD) | 86.97 (0.23) | 34.03 (4.77) | |
| Medications | Amoxiciline | N% | 65,087 (40.00) | 25,802 (32.54) | |
| Ibuprofen | N% | 65,472 (44.63) | 35,320 (64.01) | ||
| cohort2; Female | |||||
| mock | number subjects | - | N | 6,870,228 | 3,841,037 | 
| age | - | Mean (SD) | 48.21 (7.32) | 59.96 (6.93) | |
| Medications | Amoxiciline | N% | 47,855 (75.71) | 76,631 (20.27) | |
| Ibuprofen | N% | 27,026 (99.18) | 99,268 (49.56) | ||
The workflow is quite similar to visTable(), but it
includes specific enhancements for
<summarised_result> objects:
- Automatic splitting: The result object is always processed using the - splitAll()function. Thereby, column names to use in other arguments must be based on the split result.
- settingsColumnargument: Use this argument to specify which settings should be displayed in the main table. The columns specified here can also be referenced in other arguments such as- header,- rename, and- groupColumn.
- headerargument: accepts specific- <summarised_result>inputs, in addition to its typical usage as in- visTable(). For example, use “strata” in the header to display all variables in- strata_name, or use “settings” to show all settings specified in- settingsColumns.
- Hidden columns: result_id and estimate_type columns are always hidden as they serve as helper columns for internal processes. 
- Suppressed estimates: if the result object has been processed with suppress(), obscured estimates can be displayed as the default - navalue or as “<{minCellCount}” with the corresponding minimum count value used. This can be controlled using the- showMinCellCountargument.
In the next example, visOmopTable() generates a
<gt> table while displaying suppressed estimates
(those with counts below 1,000,000) with the specified minimum cell
count.
Customise tables
Tables displayed in visOmopResults() follow a default
style, but customisation is possible through the style and
.options arguments. These allow users to modify various
formatting aspects using options from the format functions
(see the format Functions section to learn
more).
Style
By default, the visOmopResults default style is applied for all tables. At the moment, besides from the default style, the package also supports the “darwin” style.
To inspect the code for the default styles of the different table
types supported, you can use the tableStyleCode() function
as showed next.
tableStyleCode(type = "gt", style = "default")
#> list(header = list(gt::cell_fill(color = "#c8c8c8"), gt::cell_text(weight = "bold", 
#>     align = "center")), header_name = list(gt::cell_fill(color = "#d9d9d9"), 
#>     gt::cell_text(weight = "bold", align = "center")), header_level = list(gt::cell_fill(color = "#e1e1e1"), 
#>     gt::cell_text(weight = "bold", align = "center")), column_name = list(gt::cell_text(weight = "bold", 
#>     align = "center")), group_label = list(gt::cell_fill(color = "#e9e9e9"), 
#>     gt::cell_text(weight = "bold")), title = list(gt::cell_text(weight = "bold", 
#>     size = 15, align = "center")), subtitle = list(gt::cell_text(weight = "bold", 
#>     size = 12, align = "center")), body = list())If you want all your tables to use the same type and style, use
setGlobalTableOptions(). This will apply the desired
settings to all subsequent tables, unless you specify a different style
in a specific function call.
Further Options
The main vis table functions are built on top of
specific formatting functions described in the next section. These core
table functions do not directly expose all customization arguments in
their signature. Instead, additional tweaks can be made via the
.options argument.
To view the full list of customization options and their default values, use:
tableOptions()
#> $decimals
#>    integer percentage    numeric proportion 
#>          0          2          2          2 
#> 
#> $decimalMark
#> [1] "."
#> 
#> $bigMark
#> [1] ","
#> 
#> $keepNotFormatted
#> [1] TRUE
#> 
#> $useFormatOrder
#> [1] TRUE
#> 
#> $delim
#> [1] "\n"
#> 
#> $includeHeaderName
#> [1] TRUE
#> 
#> $includeHeaderKey
#> [1] TRUE
#> 
#> $na
#> [1] "-"
#> 
#> $title
#> NULL
#> 
#> $subtitle
#> NULL
#> 
#> $caption
#> NULL
#> 
#> $groupAsColumn
#> [1] FALSE
#> 
#> $groupOrder
#> NULL
#> 
#> $merge
#> [1] "all_columns"As mentioned, all these arguments originate from specific formatting functions. The table below shows, for each argument, the function it belongs to and its purpose:
| Argument | Description | 
|---|---|
| formatEstimateValue() | |
| decimals | Number of decimals to display, which can be specified per estimate type (integer, numeric, percentage, proportion), per estimate name, or applied to all estimates. | 
| decimalMark | Symbol to use as the decimal separator. | 
| bigMark | Symbol to use as the thousands and millions separator. | 
| formatEstimateName() | |
| keepNotFormatted | Whether to retain rows with estimate names that are not explicitly formatted. | 
| useFormatOrder | Whether to display estimate names in the order provided in `estimateName` (TRUE) or in the order of the input data frame (FALSE). | 
| formatHeader() | |
| delim | Delimiter to use when separating header components. | 
| includeHeaderName | Whether to include the column name as part of the header. | 
| includeHeaderKey | Whether to prefix header elements with their type (e.g., header, header_name, header_level). | 
| formatTable() | |
| style | Named list specifying styles for table components (e.g., title, subtitle, header, body). Use `'default'` for the default `visOmopResults` style or `NULL` for the package default (either `gt` or `flextable`). Use `tableStyleCode()` to preview the pre-defined styles. | 
| na | Value to display for missing data. | 
| title | Title of the table. Use `NULL` for no title. | 
| subtitle | Subtitle of the table. Use `NULL` for no subtitle. | 
| caption | Caption in markdown format. Use `NULL` for no caption. For example, *Your caption here* renders in italics. | 
| groupAsColumn | Whether to display group labels as a separate column (`TRUE`) or as row headers (`FALSE`). | 
| groupOrder | Order in which to display group labels. | 
| merge | Columns to merge vertically when consecutive cells have the same value. Use `'all_columns'` to merge all, or `NULL` for no merging. |