Summarise observation period

In OmopSketch: Characterise Tables of an OMOP Common Data Model Instance

Introduction

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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

• summariseObservationPeriod(): get some overall statistics describing the observation_period table
• plotObservationPeriod(): create plots showing the results
• tableObservationPeriod(): display the results in a formatted table

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 R package omock.

library(dplyr)
library(OmopSketch)
library(omock)

# Connect to mock database
cdm <- mockCdmFromDataset(datasetName = "GiBleed", source = "duckdb")

Summarise observation periods

Let's now use the summariseObservationPeriod() function from the OmopSketch package to generate an overview of the observation_period table.
This function provides both a general summary of the table and some detailed statistics, such as the Number of subjects and the Duration in days for each observation period (e.g., first, second, etc.).

summarisedResult <- summariseObservationPeriod(cdm = cdm)

summarisedResult

Notice that the output is in the summarised result format.

We can use the function arguments to specify which summary statistics to compute. For instance, the estimates argument allows us to define which estimates we want to calculate for variables such as the Duration in days of the observation period or the Number of records per person.

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

summarisedResult |>
  filter(variable_name == "Duration in days") |>
  select(group_level, variable_name, estimate_name, estimate_value)

By default, the function returns statistics for the Number of subjects, Duration in days, and Days to next observation both overall and by each ordinal observation period (for example, first, second, etc.).

If we are only interested in overall statistics rather than those broken down by ordinal period, we can set the argument byOrdinal = FALSE:

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

summarisedResult |>
  filter(variable_name == "Duration in days") |>
  distinct(group_name, group_level)

Missingness

When the argument missingData = TRUE is set, the results will include an overall summary of missing data in the table, including the number of 0s in the concept columns. This output is analogous to the results produced by the OmopSketch function summariseMissingData().

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

summarisedResult |>
  filter(variable_name == "Column name") |>
  select(group_level, variable_name, estimate_name, estimate_value)

Quality

When the argument quality = TRUE is set, the results will include a quality assessment of the observation period table.
This assessment provides information such as:

• Issues with date columns (e.g., start dates occurring after end dates, or dates preceding a subject’s birth date).
• The presence of person_id values that do not exist in the person table.
• A summary of the types of concept_id available in the table.

summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = "mean", 
  missingData = FALSE, 
  quality = TRUE
)

summarisedResult |>
  select(group_level, variable_name, variable_level, estimate_name, estimate_value)

Strata

It is also possible to stratify the results by sex and age groups:

summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)),
)

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

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 = cdm,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE
)

summarisedResult |>
  tableObservationPeriod(type = "gt")

Visualise the results

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

summarisedResult <- summariseObservationPeriod(cdm = cdm)

plotObservationPeriod(
  result = 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 = cdm, sex = TRUE)

plotObservationPeriod(
  result = summarisedResult,
  variableName = "Duration in days",
  plotType = "boxplot",
  facet = "sex"
)

summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf))
)

plotObservationPeriod(
  result = summarisedResult,
  colour = "sex",
  facet = "age_group"
)

Disconnect from CDM

Finally, disconnect from the mock CDM.

cdmDisconnect(cdm = cdm)

OmopSketch documentation built on Aug. 27, 2026, 5:07 p.m.