2 Introduction

In this vignette, we will explore the OmopSketch functions designed to provide an overview of the observation_period table. Specifically, there are six key functions that facilitate this:

2.1 Create a mock cdm

Let’s see an example of its functionalities. To start with, we will load essential packages and create a mock cdm using the mockOmopSketch() database.

library(dplyr)
library(OmopSketch)

# Connect to mock database
cdm <- mockOmopSketch()

3 Summarise observation periods

Let’s now use the summariseObservationPeriod() function from the OmopSketch package to help us have an overview of one of the observation_period table, including some statistics such as the Number of subjects and Duration in days for each observation period (e.g., 1st, 2nd)

summarisedResult <- summariseObservationPeriod(cdm$observation_period)

summarisedResult
#> # A tibble: 3,102 × 13
#>    result_id cdm_name       group_name      group_level strata_name strata_level
#>        <int> <chr>          <chr>           <chr>       <chr>       <chr>       
#>  1         1 mockOmopSketch observation_pe… all         overall     overall     
#>  2         1 mockOmopSketch observation_pe… all         overall     overall     
#>  3         1 mockOmopSketch observation_pe… all         overall     overall     
#>  4         1 mockOmopSketch observation_pe… all         overall     overall     
#>  5         1 mockOmopSketch observation_pe… all         overall     overall     
#>  6         1 mockOmopSketch observation_pe… all         overall     overall     
#>  7         1 mockOmopSketch observation_pe… all         overall     overall     
#>  8         1 mockOmopSketch observation_pe… all         overall     overall     
#>  9         1 mockOmopSketch observation_pe… all         overall     overall     
#> 10         1 mockOmopSketch observation_pe… all         overall     overall     
#> # ℹ 3,092 more rows
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>

Notice that the output is in the summarised result format.

We can use the arguments to specify which statistics we want to perform. For example, use the argument estimates to indicate which estimates you are interested regarding the Duration in days of the observation period.

summarisedResult <- summariseObservationPeriod(cdm$observation_period,
  estimates = c("mean", "sd", "q05", "q95")
)

summarisedResult |>
  filter(variable_name == "Duration in days") |>
  select(group_level, variable_name, estimate_name, estimate_value)
#> # A tibble: 8 × 4
#>   group_level variable_name    estimate_name estimate_value 
#>   <chr>       <chr>            <chr>         <chr>          
#> 1 all         Duration in days mean          3908.36        
#> 2 all         Duration in days sd            3667.2069037827
#> 3 all         Duration in days q05           249            
#> 4 all         Duration in days q95           10817          
#> 5 1st         Duration in days mean          3908.36        
#> 6 1st         Duration in days sd            3667.2069037827
#> 7 1st         Duration in days q05           249            
#> 8 1st         Duration in days q95           10817

Additionally, you can stratify the results by sex and age groups, and specify a date range of interest:

summarisedResult <- summariseObservationPeriod(cdm$observation_period,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)),
  dateRange = as.Date(c("1970-01-01", "2010-01-01"))
)

summarisedResult |>
  select(group_level, variable_name, strata_level, estimate_name, estimate_value) |>
  glimpse()
#> Rows: 135
#> Columns: 5
#> $ group_level    <chr> "all", "all", "all", "all", "all", "all", "all", "all",…
#> $ variable_name  <chr> "Number records", "Number subjects", "Records per perso…
#> $ strata_level   <chr> "overall", "overall", "overall", "overall", "overall", …
#> $ estimate_name  <chr> "count", "count", "mean", "sd", "q05", "q95", "mean", "…
#> $ estimate_value <chr> "75", "75", "1", "0", "1", "1", "3922.24", "3453.495169…

Notice that, by default, the “overall” group will be also included, as well as crossed strata (that means, sex == “Female” and ageGroup == “>35”).

3.1 Tidy the summarised object

tableObservationPeriod() will help you to create a table (see supported types with: visOmopResults::tableType()). By default it creates a gt table.

summarisedResult <- summariseObservationPeriod(cdm$observation_period,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE
)

summarisedResult |>
  tableObservationPeriod()
#> ℹ <median> [<q25> - <q75>] has not been formatted.
Observation period ordinal Variable name Estimate name
CDM name
mockOmopSketch
overall
all Number records N 100
Number subjects N 100
Records per person mean (sd) 1.00 (0.00)
Duration in days mean (sd) 3,908.36 (3,667.21)
1st Number subjects N 100
Duration in days mean (sd) 3,908.36 (3,667.21)
Female
all Number records N 47
Number subjects N 47
Records per person mean (sd) 1.00 (0.00)
Duration in days mean (sd) 3,860.36 (3,709.03)
1st Number subjects N 47
Duration in days mean (sd) 3,860.36 (3,709.03)
Male
all Number records N 53
Number subjects N 53
Records per person mean (sd) 1.00 (0.00)
Duration in days mean (sd) 3,950.92 (3,664.73)
1st Number subjects N 53
Duration in days mean (sd) 3,950.92 (3,664.73)

3.2 Visualise the results

Finally, we can visualise the result using plotObservationPeriod().

summarisedResult <- summariseObservationPeriod(cdm$observation_period)

plotObservationPeriod(summarisedResult,
  variableName = "Number subjects",
  plotType = "barplot"
)

Note that either Number subjects or Duration in days can be plotted. For Number of subjects, the plot type can be barplot, whereas for Duration in days, the plot type can be barplot, boxplot, or densityplot.”

Additionally, if results were stratified by sex or age group, we can further use facet or colour arguments to highlight the different results in the plot. To help us identify by which variables we can colour or facet by, we can use visOmopResult package.

summarisedResult <- summariseObservationPeriod(cdm$observation_period,
  sex = TRUE
)
plotObservationPeriod(summarisedResult,
  variableName = "Duration in days",
  plotType = "boxplot",
  facet = "sex"
)


summarisedResult <- summariseObservationPeriod(cdm$observation_period,
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf))
)
plotObservationPeriod(summarisedResult,
  colour = "sex",
  facet = "age_group"
)

4 Summarise in observation

OmopSketch can also help you to summarise the number of records in observation during specific intervals of time.

summarisedResult <- summariseInObservation(cdm$observation_period,
  interval = "years"
)

summarisedResult |>
  select(variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 126 × 5
#>    variable_name   estimate_name estimate_value additional_name additional_level
#>    <chr>           <chr>         <chr>          <chr>           <chr>           
#>  1 Number records… count         100            overall         overall         
#>  2 Number records… percentage    100.00         overall         overall         
#>  3 Number records… count         1              time_interval   1958-01-01 to 1…
#>  4 Number records… percentage    1.00           time_interval   1958-01-01 to 1…
#>  5 Number records… count         1              time_interval   1959-01-01 to 1…
#>  6 Number records… percentage    1.00           time_interval   1959-01-01 to 1…
#>  7 Number records… count         1              time_interval   1960-01-01 to 1…
#>  8 Number records… percentage    1.00           time_interval   1960-01-01 to 1…
#>  9 Number records… count         1              time_interval   1961-01-01 to 1…
#> 10 Number records… percentage    1.00           time_interval   1961-01-01 to 1…
#> # ℹ 116 more rows

Note that you can adjust the time interval period using the interval argument, which can be set to either “years”, “quarters”, “months” or “overall” (default value).

summarisedResult <- summariseInObservation(cdm$observation_period,
  interval = "months"
)

summarisedResult |>
  select(variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 1,468 × 5
#>    variable_name   estimate_name estimate_value additional_name additional_level
#>    <chr>           <chr>         <chr>          <chr>           <chr>           
#>  1 Number records… count         100            overall         overall         
#>  2 Number records… percentage    100.00         overall         overall         
#>  3 Number records… count         1              time_interval   1958-10-01 to 1…
#>  4 Number records… percentage    1.00           time_interval   1958-10-01 to 1…
#>  5 Number records… count         1              time_interval   1958-11-01 to 1…
#>  6 Number records… percentage    1.00           time_interval   1958-11-01 to 1…
#>  7 Number records… count         1              time_interval   1958-12-01 to 1…
#>  8 Number records… percentage    1.00           time_interval   1958-12-01 to 1…
#>  9 Number records… count         1              time_interval   1959-01-01 to 1…
#> 10 Number records… percentage    1.00           time_interval   1959-01-01 to 1…
#> # ℹ 1,458 more rows

Along with the number of records in observation, you can also calculate the number of person-days by setting the output argument to c(“record”, “person-days”).


summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("record", "person-days"))                                        


summarisedResult |>
  select(variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 4 × 5
#>   variable_name    estimate_name estimate_value additional_name additional_level
#>   <chr>            <chr>         <chr>          <chr>           <chr>           
#> 1 Number person-d… count         390836         overall         overall         
#> 2 Number records … count         100            overall         overall         
#> 3 Number person-d… percentage    100.00         overall         overall         
#> 4 Number records … percentage    100.00         overall         overall

We can further stratify our counts by sex (setting argument sex = TRUE) or by age (providing an age group). Notice that in both cases, the function will automatically create a group called overall with all the sex groups and all the age groups. We can also define a date range of interest to filter the observation_period table accordingly.


summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("record", "person-days"),
                                           interval = "quarters",
                                           sex = TRUE, 
                                           ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)), 
                                           dateRange = as.Date(c("1970-01-01", "2010-01-01")))                                        


summarisedResult |>
  select(strata_level, variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 1,704 × 6
#>    strata_level    variable_name    estimate_name estimate_value additional_name
#>    <chr>           <chr>            <chr>         <chr>          <chr>          
#>  1 overall         Number person-d… count         294168         overall        
#>  2 Male            Number person-d… count         155915         overall        
#>  3 Female          Number person-d… count         138253         overall        
#>  4 <35             Number person-d… count         267676         overall        
#>  5 >=35            Number person-d… count         26492          overall        
#>  6 Male &&& >=35   Number person-d… count         15563          overall        
#>  7 Female &&& <35  Number person-d… count         127324         overall        
#>  8 Male &&& <35    Number person-d… count         140352         overall        
#>  9 Female &&& >=35 Number person-d… count         10929          overall        
#> 10 overall         Number records … count         75             overall        
#> # ℹ 1,694 more rows
#> # ℹ 1 more variable: additional_level <chr>

You can include additional output metrics by them to the output argument:

If output = "person", the trend in the number of individuals in observation is returned.

summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("person"),
                                           interval = "years",
                                           sex = TRUE, 
                                           ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)), 
                                           )                                        


summarisedResult |>
  select(strata_level, variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 938 × 6
#>    strata_level    variable_name    estimate_name estimate_value additional_name
#>    <chr>           <chr>            <chr>         <chr>          <chr>          
#>  1 overall         Number subjects… count         100            overall        
#>  2 Female          Number subjects… count         47             overall        
#>  3 Male            Number subjects… count         53             overall        
#>  4 <35             Number subjects… count         83             overall        
#>  5 >=35            Number subjects… count         17             overall        
#>  6 Female &&& <35  Number subjects… count         39             overall        
#>  7 Male &&& >=35   Number subjects… count         9              overall        
#>  8 Female &&& >=35 Number subjects… count         8              overall        
#>  9 Male &&& <35    Number subjects… count         44             overall        
#> 10 overall         Number subjects… percentage    100.00         overall        
#> # ℹ 928 more rows
#> # ℹ 1 more variable: additional_level <chr>

If output = "sex", the trend in the number of females in observation is returned. If sex = TRUE is specified, this stratification is ignored.

summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("sex"),
                                           interval = "years",
                                           sex = TRUE, 
                                           ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)), 
                                           )                                        


summarisedResult |>
  select(strata_level, variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 294 × 6
#>    strata_level variable_name       estimate_name estimate_value additional_name
#>    <chr>        <chr>               <chr>         <chr>          <chr>          
#>  1 overall      Number females in … count         47             overall        
#>  2 <35          Number females in … count         39             overall        
#>  3 >=35         Number females in … count         8              overall        
#>  4 overall      Number females in … percentage    47.00          overall        
#>  5 <35          Number females in … percentage    39.00          overall        
#>  6 >=35         Number females in … percentage    8.00           overall        
#>  7 overall      Number females in … count         1              time_interval  
#>  8 <35          Number females in … count         1              time_interval  
#>  9 overall      Number females in … percentage    1.00           time_interval  
#> 10 <35          Number females in … percentage    1.00           time_interval  
#> # ℹ 284 more rows
#> # ℹ 1 more variable: additional_level <chr>

If output = "age, the trend in the median age of the population in observation is calculated. If ageGroup and interval are both specified, the age is computed at the beginning of the interval or of the observation period, whichever is more recent.

summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("age"),
                                           interval = "years",
                                           ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)), 
                                           )                                        
#> ℹ The following estimates will be computed:
#> • age: median
#> → Start summary of data, at 2025-06-18 20:20:06.870177
#> 
#> ✔ Summary finished, at 2025-06-18 20:20:06.965523
#> ℹ The following estimates will be computed:
#> • age: median
#> → Start summary of data, at 2025-06-18 20:20:07.485326
#> 
#> ✔ Summary finished, at 2025-06-18 20:20:07.593965


summarisedResult |>
  select(strata_level, variable_name, estimate_name, estimate_value, additional_name, additional_level)
#> # A tibble: 161 × 6
#>    strata_level variable_name       estimate_name estimate_value additional_name
#>    <chr>        <chr>               <chr>         <chr>          <chr>          
#>  1 overall      Median age in obse… median        20             overall        
#>  2 <35          Median age in obse… median        17             overall        
#>  3 >=35         Median age in obse… median        43             overall        
#>  4 overall      Median age in obse… median        3              time_interval  
#>  5 <35          Median age in obse… median        3              time_interval  
#>  6 overall      Median age in obse… median        3              time_interval  
#>  7 <35          Median age in obse… median        3              time_interval  
#>  8 overall      Median age in obse… median        4              time_interval  
#>  9 <35          Median age in obse… median        4              time_interval  
#> 10 overall      Median age in obse… median        5              time_interval  
#> # ℹ 151 more rows
#> # ℹ 1 more variable: additional_level <chr>

4.1 Tidy the summarised object

tableInObservartion() will help you to create a table of type gt, reactable or datatable. By default it creates a gt table.

summarisedResult <- summariseInObservation(cdm$observation_period, 
                                           output = c("person", "person-days", "sex"),
                                           sex = TRUE)

summarisedResult |>
  tableInObservation(type = "gt")
Variable name Estimate name Sex
Database name
mockOmopSketch
Number person-days N (%) Female 181437 (46.42%)
Number subjects in observation N (%) Female 47 (47.00%)
Number person-days N (%) Male 209399 (53.58%)
Number subjects in observation N (%) Male 53 (53.00%)
Number females in observation N (%) overall 47 (47.00%)
Number person-days N (%) overall 390836 (100.00%)
Number subjects in observation N (%) overall 100 (100.00%)

4.2 Visualise the results

Finally, we can visualise the trend using plotInObservation().

summarisedResult <- summariseInObservation(cdm$observation_period,
  interval = "years"
)
plotInObservation(summarisedResult)
#> `result_id` is not present in result.
#> `result_id` is not present in result.

Notice that one output at a time can be plotted. If more outputs have been included in the summarised result, you will have to filter to only include one variable at time.

Additionally, if results were stratified by sex or age group, we can further use facet or colour arguments to highlight the different results in the plot. To help us identify by which variables we can colour or facet by, we can use visOmopResult package.


summarisedResult <- summariseInObservation(cdm$observation_period, 
                       interval = "years",
                       output = c("record", "age"),
                       sex = TRUE,
                       ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf))) 
#> ℹ The following estimates will be computed:
#> • age: median
#> → Start summary of data, at 2025-06-18 20:20:09.561128
#> 
#> ✔ Summary finished, at 2025-06-18 20:20:09.758062
#> ℹ The following estimates will be computed:
#> • age: median
#> → Start summary of data, at 2025-06-18 20:20:10.434073
#> 
#> ✔ Summary finished, at 2025-06-18 20:20:10.617626
plotInObservation(summarisedResult |> 
  filter(variable_name == "Median age in observation"),
  colour = "sex", 
  facet = "age_group")
#> `result_id` is not present in result.
#> `result_id` is not present in result.

Finally, disconnect from the cdm

PatientProfiles::mockDisconnect(cdm = cdm)