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

{
  "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" } } }
    }] }
  }]
}