Defining cohort phenotypes (OHDSI / OMOP CDM)

A computable phenotype is a portable, executable definition of "which patients have condition X" — concept sets plus inclusion logic that runs against any OMOP CDM-compliant database. In the OHDSI stack, ATLAS authors these visually, CIRCE serializes them to a standardized JSON representation, and that JSON compiles to database-specific SQL. This skill helps you author such definitions and augment them with NLP features that OpenMed extracts from clinical text — exactly the signals that structured codes miss.

OMOP CDM, ATLAS, CIRCE, and the OHDSI Phenotype Library are open source. The vocabulary content you reference (SNOMED CT, CPT4, ICD) is user-supplied — do not bundle restricted terminologies; load them into your own OMOP vocabulary tables with your own licenses.

When to use

• You need a reproducible cohort definition for analytics or research.
• You want to reuse an existing PheKB or OHDSI Phenotype Library definition and adapt it.
• A phenotype depends on facts that live only in free text (e.g. smoking status, symptom severity, social context) and code-based logic alone is weak.

For terminology grounding of individual entities, see coding-icd10, normalizing-rxnorm, mapping-loinc; this skill is about composing them into a cohort.

Anatomy of a CIRCE cohort definition

A CIRCE cohort definition JSON has two parts: ConceptSets (the code lists) and an expression (entry event + inclusion rules). Shape (abridged):

{
  "ConceptSets": [{
    "id": 0, "name": "Type 2 diabetes",
    "expression": { "items": [{
      "concept": { "CONCEPT_ID": 201826,           // OMOP standard concept
                   "CONCEPT_CODE": "44054006",      // SNOMED (user vocab)
                   "VOCABULARY_ID": "SNOMED" },
      "includeDescendants": true                    // pull the hierarchy
    }] }
  }],
  "PrimaryCriteria": {                              // entry event
    "CriteriaList": [{ "ConditionOccurrence": { "CodesetId": 0 } }],
    "ObservationWindow": { "PriorDays": 0, "PostDays": 0 },
    "PrimaryCriteriaLimit": { "Type": "First" }
  },
  "InclusionRules": [{
    "name": "Adult at index",
    "expression": { "Type": "ALL", "CriteriaList": [{
      "Criteria": { "ConditionEra": { "AgeAtStart": { "Value": 18, "Op": "gte" } } }
    }] }
  }]
}

You author this in ATLAS (recommended) or by hand. The OHDSI Phenotype Library ships hundreds of vetted definitions as exactly this JSON; reuse before you write.

Augmenting with OpenMed NLP features

Code-based phenotypes are blind to facts that only appear in notes. The pattern is materialize an NLP feature as OMOP rows, then reference it like any concept set.

import openmed

# 1) Extract the text feature OpenMed is good at (e.g. tobacco use, symptom)
note = "Patient is a current smoker, ~1 pack/day, with worsening dyspnea."
res = openmed.analyze_text(note, model_name="disease_detection_superclinical",
                           output_format="dict")

# 2) Write a derived OBSERVATION (or a custom cohort attribute) per patient,
#    mapping each extracted entity to a standard concept (grounded out-of-process).
#    e.g. Observation: "Current smoker" -> a SNOMED concept in your vocab.

# 3) Reference that concept in a CIRCE ConceptSet, so the phenotype combines
#    structured codes AND the NLP-derived flag in one inclusion rule.

This mirrors how eMERGE and PheKB phenotypes mix structured codes with NLP: the NLP step contributes high-recall flags for concepts that ICD/CPT capture poorly, and CIRCE composes them with the rest of the logic.

Workflow

1. Start from a library definition if one exists (OHDSI Phenotype Library / PheKB) and adapt; otherwise design entry event + inclusion rules.
2. Build concept sets from standard OMOP concepts; set includeDescendants to capture hierarchies. Vocabulary content comes from your own licensed tables.
3. Identify text-only criteria the codes miss; extract them with openmed.analyze_text and materialize as OMOP rows / cohort attributes.
4. Assemble the CIRCE JSON (concept sets + expression) — in ATLAS or directly.
5. Validate against OMOP CDM: generate SQL, run on a (synthetic/de-identified) database, review cohort counts; iterate with PheValuator-style checks.
6. Document human-readable logic alongside the JSON for portability.

Hand-off to / from OpenMed

• OpenMed → phenotype features. openmed.analyze_text over notes yields Disease, Pharmaceutical, Genomics, Oncology, and social/behavioral spans. Ground each to a standard concept (coding-icd10, normalizing-rxnorm, mapping-loinc, or your SNOMED map) and write it into OMOP so CIRCE can reference it.
• Phenotype → OpenMed scope. A cohort definition tells you which notes to process: run OpenMed only on the cohort's documents to extract the features the phenotype needs, keeping compute and PHI exposure minimal.
• Run locally on de-identified or synthetic OMOP data. De-identify notes with openmed.deidentify before they enter any shared analytics environment.

Edge cases & gotchas

• Standard vs source concepts. OMOP maps source codes (ICD-10-CM) to standard concepts (usually SNOMED). Build concept sets on standard concepts and let the source-to-standard map do the translation, or you will miss rows.
• Descendants matter. Forgetting includeDescendants silently drops the hierarchy (e.g. all diabetes subtypes). Forgetting nothing can over-capture — review the resolved concept list.
• NLP feature provenance. Tag NLP-derived OMOP rows distinctly (e.g. a type_concept indicating "derived from NLP") so analysts know the signal is probabilistic, not adjudicated.
• Vocabulary licensing. SNOMED CT, CPT4, and similar require their own licenses and are not redistributed here — load them into your OMOP vocab.
• Portability ≠ equivalence. The same JSON runs everywhere, but data capture differs by site; validate cohort counts per source before trusting them.
• Not clinical advice. Phenotype membership supports research/analytics; it is not a diagnosis.

Standards & references

• OMOP Common Data Model — https://ohdsi.github.io/CommonDataModel/
• The Book of OHDSI (cohorts & phenotypes) — https://ohdsi.github.io/TheBookOfOhdsi/
• ATLAS — https://github.com/OHDSI/Atlas
• CIRCE (cohort expression → SQL) — https://github.com/OHDSI/circe-be
• OHDSI Phenotype Library — https://github.com/OHDSI/PhenotypeLibrary
• PheKB phenotype knowledge base — https://phekb.org/
• WebAPI (programmatic cohort definitions) — https://github.com/OHDSI/WebAPI