Results table

This table has 13 columns:

• result_id (1), used to identify a group of results with common settings (see settings below).
• cdm_name (2), used to identify the name of the cdm object used to obtain those results.
• group_name (3) - group_level (4), these columns work together as a name-level pair. A name-level pair is two columns that work together to summarise information from multiple other columns. The name column contains the column names separated by &&& and the level column contains the column values separated by &&&. Elements in the name column must be snake_case. Usually, group aggregation is used to show high-level aggregations: e.g. cohort name or codelist name.
• strata_name (5) - strata_level (6), these columns work together as a name-level pair. Usually strata aggregation is used to show stratifications of the results: e.g. age groups or sex.
• variable_name (7), name of the variable of interest.
• variable_level (8), level of the variable of interest, it is usually a subclass of the variable_name.
• estimate_name (9), name of the estimate.
• estimate_type (10), type of the value displayed, the supported types are: numeric, integer, date, character, proportion, percentage, logical.
• estimate_value (11), value of interest.
• additional_name (12) - additional_level (13), these columns work together as a name-level pair. Usually additional aggregation is used to include the aggregations that did not fit in the group/strata definition.

The following table summarises the requirements of each column in the summarised_result format:

Settings

The settings table provides one row per result_id with the settings used to generate those results. There is no limit on the number of columns or parameters that can be provided per result_id, but at least three values should be provided:

• result_type (1): identifies the type of result provided. We would usually use the name of the function that generated that set of results in snake_case. For example, if the function that generates the summarised result is named summariseMyCustomData, then the result_type would be: summarise_my_custom_data.
• package_name (2): name of the package that generated the result type.
• package_version (3): version of the package that generated the result type.

These columns must be character vectors, but this restriction does not apply to other extra columns.

newSummarisedResult

The newSummarisedResult() function can be used to create objects. The inputs to this function are the summarised_result table, which must satisfy the conditions specified above, and the settings argument. The settings argument can be NULL or omit some required columns; missing columns will be populated by default and a warning will appear. Let’s see a very simple example:

library(omopgenerics)
library(dplyr)

x <- tibble(
  result_id = 1L,
  cdm_name = "my_cdm",
  group_name = "cohort_name",
  group_level = "cohort1",
  strata_name = "sex",
  strata_level = "male",
  variable_name = "Age group",
  variable_level = "10 to 50",
  estimate_name = "count",
  estimate_type = "numeric",
  estimate_value = "5",
  additional_name = "overall",
  additional_level = "overall"
)

result <- newSummarisedResult(x)
result |>
  glimpse()
#> Rows: 1
#> Columns: 13
#> $ result_id        <int> 1
#> $ cdm_name         <chr> "my_cdm"
#> $ group_name       <chr> "cohort_name"
#> $ group_level      <chr> "cohort1"
#> $ strata_name      <chr> "sex"
#> $ strata_level     <chr> "male"
#> $ variable_name    <chr> "Age group"
#> $ variable_level   <chr> "10 to 50"
#> $ estimate_name    <chr> "count"
#> $ estimate_type    <chr> "numeric"
#> $ estimate_value   <chr> "5"
#> $ additional_name  <chr> "overall"
#> $ additional_level <chr> "overall"
settings(result)
#> # A tibble: 1 × 8
#>   result_id result_type package_name package_version group     strata additional
#>       <int> <chr>       <chr>        <chr>           <chr>     <chr>  <chr>     
#> 1         1 ""          ""           ""              cohort_n… sex    ""        
#> # ℹ 1 more variable: min_cell_count <chr>

We can also associate settings with our results. These will typically be used to explain how the result was created.

result <- newSummarisedResult(
  x = x,
  settings = tibble(
    result_id = 1L,
    package_name = "PatientProfiles",
    study = "my_characterisation_study"
  )
)

result |> glimpse()
#> Rows: 1
#> Columns: 13
#> $ result_id        <int> 1
#> $ cdm_name         <chr> "my_cdm"
#> $ group_name       <chr> "cohort_name"
#> $ group_level      <chr> "cohort1"
#> $ strata_name      <chr> "sex"
#> $ strata_level     <chr> "male"
#> $ variable_name    <chr> "Age group"
#> $ variable_level   <chr> "10 to 50"
#> $ estimate_name    <chr> "count"
#> $ estimate_type    <chr> "numeric"
#> $ estimate_value   <chr> "5"
#> $ additional_name  <chr> "overall"
#> $ additional_level <chr> "overall"
settings(result)
#> # A tibble: 1 × 9
#>   result_id result_type package_name    package_version group  strata additional
#>       <int> <chr>       <chr>           <chr>           <chr>  <chr>  <chr>     
#> 1         1 ""          PatientProfiles ""              cohor… sex    ""        
#> # ℹ 2 more variables: min_cell_count <chr>, study <chr>

Tidy method

omopgenerics defines a tidy() method for <summarised_result> objects. This function:

result |>
  tidy()
#> # A tibble: 2 × 7
#>   cdm_name cohort_name sex     variable_name variable_level count study         
#>   <chr>    <chr>       <chr>   <chr>         <chr>          <dbl> <chr>         
#> 1 my_cdm   cohort1     male    Age group     10 to 50           5 my_characteri…
#> 2 my_cdm   overall     overall overall       overall           55 my_characteri…

Split

The split functions are provided independently:

• splitGroup() only splits the pair group_name-group_level columns.
• splitStrata() only splits the pair strata_name-strata_level columns.
• splitAdditional() only splits the pair additional_name-additional_level columns.

There is also the function: - splitAll() that splits any x_name-x_level pair found in the data.

splitAll(result)
#> # A tibble: 2 × 9
#>   result_id cdm_name cohort_name sex     variable_name variable_level
#>       <int> <chr>    <chr>       <chr>   <chr>         <chr>         
#> 1         1 my_cdm   cohort1     male    Age group     10 to 50      
#> 2         2 my_cdm   overall     overall overall       overall       
#> # ℹ 3 more variables: estimate_name <chr>, estimate_type <chr>,
#> #   estimate_value <chr>

Pivot estimates

pivotEstimates() can be used to pivot the variables that we are interested in.

The argument pivotEstimatesBy specifies which variables we want to use to pivot by. There are four options:

• NULL/character() to not pivot anything.
• c("estimate_name") to pivot only estimate_name.
• c("variable_level", "estimate_name") to pivot estimate_name and variable_level.
• c("variable_name", "variable_level", "estimate_name") to pivot estimate_name, variable_level and variable_name.

Note that variable_level can contain NA values, these will be ignored on the naming part.

pivotEstimates(
  result,
  pivotEstimatesBy = c("variable_name", "variable_level", "estimate_name")
)
#> # A tibble: 2 × 10
#>   result_id cdm_name group_name  group_level strata_name strata_level
#>       <int> <chr>    <chr>       <chr>       <chr>       <chr>       
#> 1         1 my_cdm   cohort_name cohort1     sex         male        
#> 2         2 my_cdm   overall     overall     overall     overall     
#> # ℹ 4 more variables: additional_name <chr>, additional_level <chr>,
#> #   `Age group_10 to 50_count` <dbl>, overall_overall_count <dbl>

Add settings

addSettings() is used to add the settings that we want as new columns to our <summarised_result> object.

The settingsColumn argument is used to choose which settings we want to add.

addSettings(
  result,
  settingsColumn = "result_type"
)
#> # A tibble: 2 × 14
#>   result_id cdm_name group_name  group_level strata_name strata_level
#>       <int> <chr>    <chr>       <chr>       <chr>       <chr>       
#> 1         1 my_cdm   cohort_name cohort1     sex         male        
#> 2         2 my_cdm   overall     overall     overall     overall     
#> # ℹ 8 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>, result_type <chr>

Filter

Dealing with an <summarised_result> object can be difficult, especially when we are trying to filter. For example, it can be difficult to filter to a certain result_type or, when many strata are joined together, to filter only one of the variables. The tidy format makes filtering easier, but using it means losing the <summarised_result> object.

The omopgenerics package contains functions that help with this process:

• filterSettings to filter the <summarised_result> object using the settings() attribute.
• filterGroup to filter the <summarised_result> object using the group_name-group_level tidy columns.
• filterStrata to filter the <summarised_result> object using the strata_name-strata_level tidy columns.
• filterAdditional to filter the <summarised_result> object using the additional_name-additional_level tidy columns.

For instance, let’s filter result so it only has results for males:

result |>
  filterStrata(sex == "male")
#> # A tibble: 1 × 13
#>   result_id cdm_name group_name  group_level strata_name strata_level
#>       <int> <chr>    <chr>       <chr>       <chr>       <chr>       
#> 1         1 my_cdm   cohort_name cohort1     sex         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>

Now let’s see an example using the information in settings to filter the result. In this case, we only want results from the “overall_analysis”. Since this information is in the result_type column in settings, we proceed as follows:

result |>
  filterSettings(result_type == "overall_analysis")
#> # A tibble: 1 × 13
#>   result_id cdm_name group_name group_level strata_name strata_level
#>       <int> <chr>    <chr>      <chr>       <chr>       <chr>       
#> 1         2 my_cdm   overall    overall     overall     overall     
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>

Column retrieval functions

Working with <summarised_result> objects often involves managing columns for settings, grouping, strata, and additional levels. These retrieval functions help you identify and manage columns:

• settingsColumns() gives you the setting names that are available in a <summarised_result> object.
• groupColumns() gives you the new columns that will be generated when splitting group_name-group_level pair into different columns.
• strataColumns() gives you the new columns that will be generated when splitting strata_name-strata_level pair into different columns.
• additionalColumns() gives you the new columns that will be generated when splitting additional_name-additional_level pair into different columns.
• tidyColumns() gives you the columns that the object will have if you tidy it (tidy(result)). This function is very useful for knowing which columns can be included in plot and table functions.

Let’s see the different values with our example result data:

settingsColumns(result)
#> [1] "study"
groupColumns(result)
#> [1] "cohort_name"
strataColumns(result)
#> [1] "sex"
additionalColumns(result)
#> character(0)
tidyColumns(result)
#> [1] "cdm_name"       "cohort_name"    "sex"            "variable_name" 
#> [5] "variable_level" "count"          "study"

Unite functions

The unite functions serve as the complementary tools to the split functions, allowing you to generate name-level pair columns from targeted columns within a <dataframe>.

There are three unite functions that allow you to create group, strata, and additional name-level columns from specified sets of columns:

• uniteAdditional()

• uniteGroup()

• uniteStrata()

# Create and show mock data
data <- tibble(
  denominator_cohort_name = c("general_population", "older_than_60", "younger_than_60"),
  outcome_cohort_name = c("stroke", "stroke", "stroke")
)
head(data)
#> # A tibble: 3 × 2
#>   denominator_cohort_name outcome_cohort_name
#>   <chr>                   <chr>              
#> 1 general_population      stroke             
#> 2 older_than_60           stroke             
#> 3 younger_than_60         stroke

# Unite into group name-level columns
data |>
  uniteGroup(cols = c("denominator_cohort_name", "outcome_cohort_name"))
#> # A tibble: 3 × 2
#>   group_name                                      group_level                  
#>   <chr>                                           <chr>                        
#> 1 denominator_cohort_name &&& outcome_cohort_name general_population &&& stroke
#> 2 denominator_cohort_name &&& outcome_cohort_name older_than_60 &&& stroke     
#> 3 denominator_cohort_name &&& outcome_cohort_name younger_than_60 &&& stroke