Summarise clinical records

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 clinical tables within a CDM object (for example, visit_occurrence, condition_occurrence, drug_exposure, procedure_occurrence, device_exposure, measurement, observation, and death). Specifically, there are two key functions that facilitate this:

• summariseClinicalRecords(): creates summary statistics with key information about clinical tables, including the number of records, number of subjects, records per person, record duration, quality checks, concept summaries, and missing data.

• tableClinicalRecords(): displays the results in a formatted table.

Create a mock cdm

Let's see an example of these 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")

cdm

Summarise clinical tables

Let's now use summariseClinicalRecords() from the OmopSketch package to create an overview of one clinical table in the CDM, condition_occurrence.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm, 
  omopTableName = "condition_occurrence"
)

summarisedResult

Notice that the output is in the summarised result format.

Records per person

We can use the function arguments to specify which statistics to compute. For example, the recordsPerPerson argument controls the estimates returned for the number of records per person.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  recordsPerPerson = c("mean", "sd", "q05", "q95")
)

summarisedResult |>
  filter(variable_name == "Records per person") |>
  select(variable_name, estimate_name, estimate_value)

Quality

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

• The proportion of records that fall outside the subjects’ observation periods.
• Issues with date columns (e.g., start dates occurring after end dates, or dates preceding a subject’s birth date).
• The presence of subjects in the clinical table that do not exist in the person table.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  recordsPerPerson = NULL, 
  conceptSummary = FALSE,
  missingData = FALSE,
  quality = TRUE
)

summarisedResult |>
  select(variable_name, estimate_name, estimate_value) 

Concept Summary

When the argument conceptSummary = TRUE is set, the results will include information about the concepts contained in the table, such as:

• The domain to which each concept belongs.
• Whether records use standard or non-standard concepts.
• The concept class, concept type, standard vocabulary, and source vocabulary associated with the records.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = "drug_exposure",
  recordsPerPerson = NULL, 
  conceptSummary = TRUE,
  missingData = FALSE,
  quality = FALSE
)

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

Missingness

When the argument missingData = TRUE is set, the results will include a summary of missing data in the table. This output is analogous to the results produced by the OmopSketch function summariseMissingData().

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  recordsPerPerson = NULL, 
  conceptSummary = FALSE,
  missingData = TRUE,
  quality = FALSE
)

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

Strata

It is also possible to stratify the results by sex and age groups. When sex = TRUE, summaries are stratified by sex. When ageGroup is provided, records are assigned to the specified age groups using the clinical record start date.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  recordsPerPerson = c("mean", "sd", "q05", "q95"),
  quality = TRUE,
  conceptSummary = TRUE,
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf))
)

summarisedResult |>
  select(variable_name, strata_level, estimate_name, estimate_value) 

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

The analysis can also be conducted for multiple OMOP tables at the same time:

summarisedResult <- summariseClinicalRecords(
  cdm = cdm,
  omopTableName = c("visit_occurrence", "drug_exposure"),
  recordsPerPerson = c("mean", "sd"),
  quality = FALSE,
  conceptSummary = FALSE,
  missingData = FALSE
)

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

Date Range

We can also filter the clinical table to a specific time window by setting the dateRange argument.

summarisedResult <- summariseClinicalRecords(
  cdm = cdm, 
  omopTableName = "drug_exposure",
  dateRange = as.Date(c("1990-01-01", "2010-01-01"))
) 

summarisedResult |>
  settings() |>
  glimpse()

Tidy the summarised object

tableClinicalRecords() will help you to tidy the previous results and create a formatted table. The table type can be set with the type argument; supported formats are provided by visOmopResults::tableType(). If type = NULL, global table options are used when available; otherwise, a gt table is created by default.

summarisedResult <- summariseClinicalRecords(cdm,
  omopTableName = "condition_occurrence",
  recordsPerPerson = c("mean", "sd", "q05", "q95"),
  quality = TRUE, 
  conceptSummary = TRUE,
  sex = TRUE
)

tableClinicalRecords(result = summarisedResult, type = "gt")

Disconnect from CDM

Finally, disconnect from the mock CDM.

cdmDisconnect(cdm = cdm)

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