Summarise the person table
In OmopSketch: Characterise Tables of an OMOP Common Data Model Instance

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

Introduction

This vignette walks through the OmopSketch functions designed to provide a concise overview of the OMOP person table. Two functions cover this workflow:

summarisePerson(): computes summary statistics and data-quality checks for the person table, including total subject counts, observation-period coverage, sex/race/ethnicity distributions, birth-date components, and summaries of id-columns (location_id, provider_id, care_site_id).
tablePerson(): renders the results as a formatted table (gt, reactable, or datatable).

Setup

Load the required packages and create a mock CDM using omock.

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

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

Summarise the person table

Call summarisePerson() to compute all summaries. It returns a summarised_result object — a standardised tidy format used across the OMOP analytics ecosystem.

result <- summarisePerson(cdm = cdm)
result |> glimpse()

What the function reports

summarisePerson() covers the following summaries, each stored as a separate variable_name in the result:

| Variable | Description | |---|---| | Number subjects | Total row count in person. | | Number subjects not in observation | Count and percentage of persons absent from observation_period. A warning is emitted when this is non-zero. | | Sex | Count and percentage for Female, Male, and None (derived via PatientProfiles::addSexQuery()). | | Sex source | Distribution of raw gender_source_value. | | Race | Distribution of race_concept_id, resolved to concept names. | | Race source | Distribution of raw race_source_value. | | Ethnicity | Distribution of ethnicity_concept_id, resolved to concept names. | | Ethnicity source | Distribution of raw ethnicity_source_value. | | Year of birth | Numeric summary: missingness, quantiles (Q05, Q25, median, Q75, Q95), min/max. | | Month of birth | Same numeric summary as year of birth. | | Day of birth | Same numeric summary as year of birth. | | Location | Missing count, zero count, and distinct values for location_id. When location_id is empty, the function attempts to derive it from care_site_id and notes this in a message.| | Provider | Missing count, zero count, distinct values, and (below threshold) individual provider_name labels. | | Care site | Missing count, zero count, distinct values, and (below threshold) individual care_site_name labels. |

Threshold

For location_id, provider_id, and care_site_id, summarisePerson() always reports three aggregate statistics: number missing, number of zeros, and number of distinct values. Whether it goes further and lists each value individually depends on a threshold.

If the number of distinct values is below 15 (the default), the function joins to the corresponding lookup table and appends one row per unique label — location_source_value, provider_name, or care_site_name — each with its own count and percentage. This gives you a readable breakdown rather than just a count of how many distinct ids exist.

If the number of distinct values is at or above 15, only the aggregate stats are returned. Listing dozens or hundreds of individual sites would produce noise rather than insight.

You can tune this cutoff for your database before calling summarisePerson():

# Raise the threshold to show individual labels for up to 50 distinct values
options(OmopSketch.personLabels = 50)
result <- summarisePerson(cdm = cdm)

Estimate types

Depending on the variable, estimates include:

count / percentage — for categorical variables (sex, race, ethnicity).
count_missing / percentage_missing — missingness for id-columns and birth-date fields.
count_0 / percentage_0 — zero values for id-columns.
distinct_values — number of unique non-null values for id-columns.
min, q05, q25, median, q75, q95, max — quantile summaries for birth-date fields.

Visualise the results

tablePerson() formats the summarised_result into a publication-ready table. The type argument accepts "gt" (default), "reactable", or "datatable".

tablePerson(result = result, type = "gt")

The column headers are driven by the CDM name and the estimate combinations are rendered as human-readable labels (e.g. N (%), Median [Q25 - Q75], Missing N (%)).