Generator of Synthetic Patient Data for the OMOP Common Data Model.

PatientGenerator

PatientGenerator facilitates the creation of synthetic test datasets for the OMOP Common Data Model (CDM) using two complementary approaches:

• patientChat: Generates structured patient JSON files using Large Language Models (LLMs).
• patientDesigner: Provides a D3-based Shiny interface for reviewing and editing CDM test sets.

The package also includes support for Hecate-powered concept lookups to ensure valid OMOP concept codes.

Installation

# install.packages("remotes")
remotes::install_github("mi-erasmusmc/PatientGenerator")

Workflow Overview

1. Generate an initial synthetic cohort using patientChat.
2. Save JSON test sets to the local filesystem.
3. Refine patients using patientDesigner().
   • Utilize built-in concept search (powered by hecateSearch) during table editing.

Synthetic Patient Generation with patientChat

Set an OPENAI_API_KEY environment variable (e.g., via usethis::edit_r_environ()) to enable LLM access.

Available models can be listed using PatientGenerator::availableModels().

library(PatientGenerator)

patientGenerator <- patientChat$new(
  model = "gpt-5.4",
  echo = "none"
)

Generating Patients via Natural Language Prompts

Provide detailed prompts, including specific concept sets, for optimal results.

patientGenerator$prompt(
  "Population (person table):
     - 10 adult patients
     - 5 female
     - 5 male
  
   Observation Period:
     - Start date between date of birth and 2025-12-31
  
   Condition Occurrence:
     - All patients must have Diabetes (condition_concept_id: 201826)
     - Start date between 2015-01-01 and 2020-12-31
  
   Drug Exposure:
     - All patients must have Semaglutide (drug_concept_id: 19079450)
     - Exposure within 30 days post-index date
  
   Measurement:
     - All patients must have Fasting glucose (measurement_concept_id: 3018251)
  
   Procedure Occurrence:
     - 50% of patients must have Amputation of toe (procedure_concept_id: 4159766)
  
   Output Requirements:
     - Populate only the tables specified in this prompt"
)

Integration with testthat

Save the generated dataset as a JSON file and utilize TestGenerator::patientsCDM to instantiate a CDM reference.

patientGenerator$save(name = "diabetes-patients")

cdm <- TestGenerator::patientsCDM(
  testName = "diabetes-patients",
  cdmVersion = "5.4"
)

cdm$person |> 
  collect() |> 
  print()

#> cdm$person |> collect() |> head(5)
#>    person_id gender_concept_id year_of_birth person_source_value
#>        <int>             <int>         <int>              <char>
#> 1:         1              8532          1965              SYN001
#> 2:         2              8532          1972              SYN002
#> 3:         3              8532          1958              SYN003
#> 4:         4              8532          1981              SYN004
#> 5:         5              8532          1949              SYN005

Iterative Refinement

The LLM can be instructed to modify the current test set within the same patientChat instance.

patientGenerator$prompt("Remove all male patients")

#> cdm$person |> collect() |> head(5)
#>    person_id gender_concept_id year_of_birth person_source_value
#>        <int>             <int>         <int>              <char>
#> 1:         1              8532          1965              SYN001
#> 2:         2              8532          1972              SYN002
#> 3:         3              8532          1958              SYN003
#> 4:         4              8532          1981              SYN004
#> 5:         5              8532          1949              SYN005

Visual Review and Editing with patientDesigner()

Launch the interactive editor to review and refine datasets:

PatientGenerator::patientDesigner()

The interface supports:

• Loading existing JSON test sets.
• Interactive CRUD operations (Create, Read, Update, Delete) on CDM tables.
• Visual timeline inspection and table previews.
• Exporting updated test sets to JSON.

Concept Search with Hecate

patientDesigner integrates a concept search module powered by hecateSearch(). This allows users to search for and insert valid OMOP concept IDs directly into the CDM tables.

Configure Hecate globally via environment variables:

Sys.setenv(
  HECATE_BASE_URL = "https://your-hecate-server/api",
  HECATE_API_KEY = "your-api-key"
)

Or via package options:

options(PatientGenerator.hecate = list(
  base_url = "https://your-hecate-server/api",
  timeout_ms = 15000,
  api_key = "your-api-key"
))

Further Documentation

• Vignette: vignette("shiny-integration", package = "PatientGenerator")
• Reference: Detailed API documentation and benchmarks are available on the GitHub Pages site.