Defining Cohort Phenotypes

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):

jsoncCopy code
{
  "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.

pythonCopy code
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