Mastering ATLAS Cohort Definitions: A Clinical Researcher's Complete Guide

The Journey So Far

Building on our exploration of the OMOP Common Data Model, standardized vocabularies like SNOMED CT, RxNorm, and LOINC, ETL fundamentals, and data quality assessment with Achilles, we've reached a pivotal milestone: defining patient cohorts in OHDSI ATLAS.

Why ATLAS and OHDSI Matter

OHDSI has grown into one of the largest international collaboratives in healthcare data science:

What is ATLAS?

ATLAS is the flagship web application of the OHDSI ecosystem. It provides a graphical interface for vocabulary exploration, cohort definition, characterization, estimation, prediction, and pathway analysis.

The ATLAS home screen provides navigation to all OHDSI analytical tools

Why Cohorts Are the Foundation

In clinical research, a cohort is a defined group of patients who share specific characteristics. Unlike ad-hoc database queries, cohorts are reproducible, shareable, standardized, versioned, and portable across 450+ OMOP databases.

Mapping Clinical Criteria to OMOP Concepts

Our Database Setup

After extensive preparation, our PostgreSQL database contained 2,411 synthetic patients with complete OMOP CDM 5.4 structure.

flowchart TB
    subgraph DB["Database: ohdsi_learning"]
        subgraph CDM["cdm (OMOP CDM 5.4)"]
            P["person (2,411 patients)"]
            CO[condition_occurrence]
            DE[drug_exposure]
        end
        
        subgraph VOC["vocabulary"]
            C["concept (~6M)"]
        end
        
        subgraph RES["results"]
            CH[cohort]
        end
    end
    
    P --> CO
    P --> DE
    C --> CO
                

First Success: Data Sources Dashboard

The Data Sources dashboard confirmed our setup was working. ATLAS correctly displayed our 2,411 synthetic patients with demographic breakdowns:

The CDM Summary shows 2,411 patients with gender distribution from our Synthea data

Building the Type 2 Diabetes Cohort

Step 1: Vocabulary Search

Every cohort starts with finding the right clinical concepts. In ATLAS, navigate to Search and enter "type 2 diabetes":

Searching for "type 2 diabetes" returns 299 concepts across multiple vocabularies

Step 2: Building the Cohort Definition

The definition has four key sections:

flowchart LR
    subgraph Entry["1. Entry Events"]
        E1["Condition: T2DM"]
        E2["First occurrence"]
    end
    
    subgraph Include["2. Inclusion"]
        I1["Age ≥ 18"]
        I2["No prior T1DM"]
    end
    
    subgraph Exit["3. Exit"]
        X1["End of obs"]
    end
    
    subgraph Out["4. Output"]
        O1["220 patients"]
    end
    
    Entry --> Include --> Exit --> Out
                

The cohort builder showing entry events, inclusion criteria, and exit settings

Step 3: Generating the Cohort

After saving the definition, navigate to the Generation tab and click "Generate":

Generation completed successfully—220 patients in the final cohort

The Schema Compatibility Problem

After successfully generating cohorts, we attempted to run Cohort Characterization. That's when the errors started:

ERROR: schema "temp" does not exist
ERROR: column "design_hash" does not exist
ERROR: relation "results.cohort_cache" does not exist

WebAPI 2.x has evolved significantly beyond the base OMOP CDM specification. When you connect an external database, Flyway migrations don't run automatically.

Key Takeaways