Skip to main content

Cohort Wizard Takes Shape & OMOP Extensions Land in Production

· 5 min read
Sanjay M. Udoshi MD
Creator, Parthenon
Claude (AI Pair Programmer)
AI Development Assistant

A massive day on the Parthenon platform: we shipped the full six-chapter Cohort Wizard UI from scratch in a single push, and completed a methodical, non-destructive migration of Imaging, Genomics, GIS, and Oncology extension structures into the localhost OMOP schema. These two workstreams — one facing researchers building cohorts, one facing the data layer powering them — represent a significant leap forward in Parthenon's end-to-end outcomes research story.

Cohort Wizard: Zero to Full Six-Chapter Flow​

The headline feature today is the Cohort Wizard — a guided, step-by-step UI for constructing OHDSI-compliant cohort definitions without requiring researchers to hand-author CIRCE JSON or wrangle the Atlas interface directly.

The implementation spans ten commits and was designed ground-up with a clear separation of concerns:

Foundation Layer​

Before any UI was built, we laid the plumbing:

  • Zustand wizard store (feat: add Zustand wizard store) manages navigation state, per-chapter form state, and — critically — assembles a valid OHDSI cohort expression object as the user progresses. This means the wizard is never just a pretty form; it's a live expression builder.
  • Utility functions for expression building, temporal presets (e.g., "within 30 days prior"), and concept set auto-naming were extracted into their own module so they remain testable and reusable outside the wizard context.
  • WizardConceptPicker and SelectedConceptsList components provide a consistent concept search and selection experience used across multiple chapters. These wrap the platform's existing concept search infrastructure with wizard-specific affordances like inline inclusion/exclusion toggling.

The Six Chapters​

The wizard shell provides a sidebar navigation with chapter routing. Each chapter is independently navigable once unlocked, and the sidebar reflects completion state. The chapters themselves:

  1. Chapter 1 — Basics: Cohort name, description, domain selection, and tag assignment. Simple, but sets metadata that flows into Atlas and downstream reporting.
  2. Chapter 2 — Define Population: Entry events, observation window configuration, and qualifying events. This is the heart of any OHDSI cohort definition, and the UI maps directly to the CIRCE primaryCriteria and qualifiedLimit structures.
  3. Chapter 3 — Refine & Filter: Inclusion rules, demographic filters (age, gender, race), and risk score thresholds. Supports both simple demographic predicates and structured inclusion rule groups.
  4. Chapter 4 — Follow-up & Exit: End strategy selection (continuous observation, fixed duration, event-based exit) and censoring event configuration. Researchers often get this chapter wrong in manual Atlas sessions — the wizard surfaces the tradeoffs clearly.
  5. Chapter 5 — Specialized Criteria: Extended criteria including correlated criteria, temporal windows, and domain-specific filters (e.g., measurement range constraints, condition era logic). This chapter handles the long tail of complex cohort requirements.
  6. Chapter 6 — Review, Generate & Handoff: A structured review of the assembled expression, a one-click generate action that POSTs to the Atlas-compatible cohort definition endpoint, and handoff affordances (copy JSON, open in Atlas, export to file).

The implementation plan (docs: add Cohort Wizard implementation plan) was committed alongside the code, serving as both a design record and onboarding document for future contributors.

Why This Matters​

Atlas is powerful but has a steep learning curve that creates a real barrier for clinician-researchers and study coordinators. The Cohort Wizard makes cohort authoring accessible without sacrificing the expressiveness of the underlying OHDSI model. Because the Zustand store emits valid CIRCE JSON at every step, nothing is lost in translation — the wizard is a first-class citizen of the OHDSI toolchain, not a simplified approximation of it.

OMOP Extension Handoff: Imaging, Genomics, GIS & Oncology​

In parallel, a major database-layer workstream completed today against the localhost parthenon PostgreSQL 17 instance. The full handoff document has been captured in 2026-04-10-omop-extension-handoff.md, but here are the key points for the development record.

What Was Done​

  • Additive extension tables for Imaging, Genomics, GIS, and Oncology were created in the omop schema, aligned with current public OHDSI extension proposals and CDM conventions.
  • Imaging backfill was completed for every OMOP-eligible Acumenus acquisition series present on localhost — bridging app.imaging_* source rows into the new OMOP extension structures via xref tables.
  • Genomics backfill was completed for the one clinically person-linked upload currently on localhost. The seven GIAB benchmark uploads were intentionally left out of scope — they are not linked to clinical persons and materializing them as OMOP records would be methodologically incorrect without an explicit decision to model benchmark data differently.

What Was Not Done (By Design)​

No destructive operations were used. No source rows in app.imaging_* or app.genomic_* were deleted or modified. No existing OMOP rows were overwritten. The migration is purely additive: new tables, new xref bridges, new nullable foreign key columns on existing structures, and INSERT-only backfill scripts.

This constraint was explicit in the user brief and was honored throughout. Future agents picking up this work should treat the current backfill boundaries as authoritative and focus any follow-on imaging work on upstream person-link remediation rather than re-running completed backfills.

What's Next​

  • Cohort Wizard testing: The wizard needs integration tests covering expression assembly edge cases — particularly Chapter 5 specialized criteria and the temporal window logic. Unit tests for the Zustand store utilities are the natural starting point.
  • Wizard ↔ Atlas round-trip validation: We need to confirm that expressions generated by the wizard import cleanly into a live Atlas instance and produce expected cohort counts on a reference dataset.
  • OMOP extension — image_feature backfill: The handoff doc identifies image_feature population as remaining work once upstream person-link remediation is addressed.
  • GIS and Oncology extension data: The schema structures are in place; actual data backfill for GIS (geospatial location enrichment) and Oncology (staging, pathology) awaits upstream data availability.
  • Chapter 6 handoff polish: The generate-and-handoff flow works end-to-end but the UX for the Atlas deep-link and JSON export could use a second pass before we ship this to external study teams.