Summarise concept id counts
In OmopSketch: Characterise Tables of an OMOP Common Data Model Instance

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

Introduction

In this vignette, we will explore the OmopSketch functions designed to summarise concept use in clinical OMOP tables. Specifically, there are two key functions:

summariseConceptIdCounts(): counts standard concept IDs and their associated source concept IDs in one or more clinical tables.
tableConceptIdCounts(): displays concept count results in a formatted table.

Create a mock cdm

Let's see an example of these functions. To start with, we will load essential packages and create a mock CDM using the R package omock.

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

cdm <- mockCdmFromDataset(datasetName = "GiBleed", source = "duckdb")

cdm

Summarise concept level counts

We now use the summariseConceptIdCounts() function from the OmopSketch package to retrieve counts for each standard concept ID and name, together with the associated source concept ID, source concept name, standard vocabulary, and source vocabulary.

summariseConceptIdCounts(cdm = cdm, omopTableName = "drug_exposure") |>
  select(group_level, variable_name, variable_level, estimate_name, estimate_value, additional_name, additional_level) |>
  glimpse()

By default, the function returns the number of records (estimate_name == "count_records") for each standard concept ID. To count distinct subjects instead, set countBy = "person". To return both record and subject counts, use countBy = c("record", "person").

summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "drug_exposure",
  countBy = c("record", "person")
) |>
  select(variable_name, estimate_name, estimate_value)

Further stratification can be applied using the interval, sex, and ageGroup arguments. The interval argument supports "overall" (no time stratification), "years", "quarters", or "months". Age groups and time intervals are assigned using the clinical record start date.

summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  countBy = "person",
  interval = "years",
  sex = TRUE,
  ageGroup = list("<=50" = c(0, 50), ">50" = c(51, Inf))
) |>
  select(group_level, strata_level, variable_name, estimate_name, additional_level) |>
  glimpse()

When inObservation = TRUE, results are stratified by whether each record occurred within the subject's observation period.

summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  countBy = "record",
  inObservation = TRUE
) |>
  select(variable_name, strata_name, strata_level, estimate_name, estimate_value) |>
  glimpse()

We can also filter the clinical table to a specific time window by setting the dateRange argument. Only records with a start date inside the date range are included.

summarisedResult <- summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  dateRange = as.Date(c("1990-01-01", "2010-01-01"))
)
summarisedResult |>
  settings() |>
  glimpse()

You can restrict concept counts to a subset of subjects with the sample argument. Provide an integer to randomly select that many person_ids from the person table, or provide the name of a cohort table in the CDM to restrict counts to its subject_ids.

summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "condition_occurrence",
  sample = 50
) |>
  select(group_level, variable_name, estimate_name) |>
  glimpse()

Display the results

Concept counts can be displayed using tableConceptIdCounts(). By default, it generates an interactive reactable table, but DT datatables are also supported.

result <- summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "measurement",
  countBy = "record"
)
tableConceptIdCounts(result = result, type = "reactable")

tableConceptIdCounts(result = result, type = "datatable")

The display argument in tableConceptIdCounts() controls which concept columns are shown. The default is display = "overall", which shows both standard and source concept information.

tableConceptIdCounts(result = result, display = "overall")

If display = "standard", the table shows only standard concept ID, standard concept name, and standard vocabulary.

tableConceptIdCounts(result = result, display = "standard")

If display = "source", the table shows only source concept ID, source concept name, and source vocabulary.

tableConceptIdCounts(result = result, display = "source")

If display = "missing source", the table shows standard concepts for records that are missing a corresponding source concept ID.

tableConceptIdCounts(result = result, display = "missing source")

If display = "missing standard", the table shows source concepts for records that are missing a mapped standard concept ID.

tableConceptIdCounts(result = result, display = "missing standard")

Display the most frequent concepts

You can use the tableTopConceptCounts() function to display the most frequent concepts in an OMOP CDM table. By default, the function returns a gt table, but other formats supported by visOmopResults::tableType() can also be used.

result <- summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "drug_exposure",
  countBy = "record"
)
tableTopConceptCounts(result = result, type = "gt")

Customising the number of top concepts

By default, the function shows the top 10 concepts within each table and stratum. You can change this using the top argument:

tableTopConceptCounts(result = result, top = 5)

Choosing the count type

If your summary includes both record and subject counts, you must specify which type to rank by using the countBy argument:

result <- summariseConceptIdCounts(
  cdm = cdm,
  omopTableName = "drug_exposure",
  countBy = c("record", "person")
)
tableTopConceptCounts(result = result, countBy = "person")