Saltar al contenido principal

Study Designer

The Study Designer is Parthenon's end-to-end, OHDSI-aligned workspace for authoring, verifying, and packaging observational research studies. It guides you from an initial research intent through concept set drafting, cohort authoring, feasibility assessment, and analysis planning, and ultimately produces a locked, reproducible study package artifact.

OHDSI Workflow Alignment

Study Designer follows the canonical OHDSI study development lifecycle: Intent → Concept Sets → Cohorts → Feasibility → Analysis Plan → Package Lock. Each gate must pass verification before you can proceed to the next phase.

Overview​

A Study Design Session is a versioned workspace. Every material change — AI-assisted intent generation, cohort imports, concept set drafts, and analysis plan edits — is recorded as a versioned asset so you have a full audit trail from idea to locked package.

ConceptDescription
SessionTop-level container for one research question
VersionSnapshot of a session at a point in time; versions are immutable once locked
AssetAny durable artifact attached to a session (intent, concept set draft, cohort draft, analysis plan, feasibility report)
AI EventRecorded invocation of an AI assistant action within the session
Locked PackageA signed, immutable bundle of all verified assets ready for execution or external distribution

Creating a Study Design Session​

  1. Navigate to Analyses → Study Designer.
  2. Click New Study.
  3. Enter a Study Title and optional description.
  4. Choose a starting workflow:
    • Intent-First — Describe your research question in natural language and let Abby AI generate a structured intent.
    • Bottom-Up Import — Import an existing cohort, concept set, or analysis specification as the starting point.
  5. Click Create Session.

The session opens at the Intent phase.

Phase 1 — Research Intent​

The intent phase captures the structured research question that governs all downstream assets.

AI-Assisted Intent Generation​

  1. In the Intent panel, type your research question in plain language.

    Example: "Compare the risk of major adverse cardiovascular events in new users of GLP-1 receptor agonists versus DPP-4 inhibitors in type 2 diabetes patients aged 40–75."

  2. Click Generate Intent. Abby AI produces a structured intent document covering:
    • Population description
    • Exposure(s) of interest
    • Comparator(s)
    • Outcomes
    • Time-at-risk windows
    • Covariates and confounders
  3. Review and edit each field directly in the intent editor.
  4. Click Accept Intent to lock the intent and advance to concept set drafting.
Critique Assets

At any phase you can click Critique to invoke Abby AI's critique pipeline. The critique reviews your current assets for methodological gaps, OMOP alignment issues, and OHDSI best-practice deviations, and writes a structured critique asset to the session timeline.

Bottom-Up Study Import​

If you are starting from existing work:

  1. Click Import Study in the Intent panel.
  2. Select one or more source objects:
    • Cohort definitions from Parthenon's Cohort Library
    • Concept sets from your library or the Phenotype Library
    • An existing analysis specification (PLE, PLP, IR, Characterization)
  3. Study Designer maps imported objects to the appropriate intent fields and creates draft assets.
  4. Review the generated intent, then click Accept Intent.

Phase 2 — Concept Set Drafts​

The concept set drafting phase lets you build or refine the OMOP concept sets that will define your exposures, outcomes, and covariates.

Verifier Rules​

Study Designer enforces strict concept set verification before any cohort or package operations:

RuleEffect
All concept IDs must be positive integers present in vocab.conceptConcepts not found in the vocabulary block materialization
Deprecated concepts (invalid_reason IS NOT NULL) are flaggedDeprecated concepts block materialization with a hard error
Concepts with standard_concept != 'S' generate warningsNon-standard concepts are highlighted but do not block unless promoted to errors in your system configuration

Diagnostics Panel​

The Verifier Diagnostics panel (right sidebar) shows real-time validation state:

  • 🟢 Valid — concept is current, standard, and present in vocab.concept
  • 🟡 Warning — concept is non-standard or has a newer mapping
  • 🔴 Error — concept is missing from the vocabulary or deprecated; materialization is blocked

Click any flagged concept to open the Vocabulary Browser and find a replacement.

Drafting Workflow​

  1. Click Add Concept Set to create a new draft.
  2. Search the vocabulary or paste a list of concept IDs.
  3. The verifier runs automatically after each change.
  4. Resolve all errors shown in the Diagnostics panel.
  5. Click Finalize Concept Sets to seal the concept set assets and proceed.

Phase 3 — Cohort Drafts​

Cohort drafts are authored using the same Cohort Expression builder available elsewhere in Parthenon, but are managed within the session versioning system.

Authoring a Cohort Draft​

  1. Click New Cohort Draft.
  2. Build inclusion criteria using your finalized concept sets.
  3. Configure entry events, additional criteria, and exit criteria as you would in the standard Cohort Builder.
  4. Save the draft. The session records the draft as a versioned cohort asset.

Importing Cohorts​

  1. Click Import Cohort.
  2. Select from your Cohort Library or the Phenotype Library.
  3. Study Designer performs phenotype validation on import:
    • Deprecated concepts within an imported cohort definition block feasibility and package lock.
    • A deprecation report is shown inline; you must resolve or acknowledge each deprecated concept before proceeding.

Cohort Verifier​

Cohorts must be materialized against at least one connected data source before they are considered verified.

  1. Select a data source from the Materialize Against dropdown.
  2. Click Generate. Parthenon runs the cohort generation job.
  3. Once complete, the cohort status changes to Verified — Materialized.
Deprecated Cohorts Block Downstream Phases

If a cohort draft or imported cohort contains deprecated OMOP concept IDs that have not been resolved, the session will display a hard block on the Feasibility and Package Lock phases. Resolve all deprecations in the Diagnostics panel before continuing.

Phase 4 — Feasibility Evidence​

Feasibility evidence gives you an early signal on cohort sizes and outcome rates before committing to full execution.

  1. With cohorts verified and materialized, click Run Feasibility.
  2. Study Designer submits feasibility queries against your selected data sources.
  3. Results populate the Feasibility Evidence panel:
    • Target cohort size (N)
    • Comparator cohort size (N)
    • Outcome rate estimate
    • Data source coverage summary
  4. Review results. If sizes are insufficient, return to Phase 2 or 3 and revise.
  5. Click Accept Feasibility Evidence to record the feasibility asset and unlock the Analysis Plan phase.

Phase 5 — Analysis Plan​

The analysis plan specifies the statistical methods that will be applied to your verified cohorts.

Supported Analysis Types​

Analysis TypeModule
Cohort CharacterizationPart IV — Characterization
Incidence Rate AnalysisPart IV — Incidence Rates
Population-Level Estimation (PLE)Part IV — PLE
Patient-Level Prediction (PLP)Part IV — PLP
Self-Controlled Case Series (SCCS)Part IV — SCCS

Authoring the Plan​

  1. Click Add Analysis and select an analysis type.
  2. Configure the analysis parameters. The UI surfaces the same configuration panels as the standalone analysis modules.
  3. Repeat for each analysis in your study.
  4. Click Verify Analysis Plan. The verifier checks:
    • All referenced cohorts are verified and materialized.
    • All referenced concept sets are finalized and error-free.
    • Required parameters are complete for each analysis type.
  5. When verification passes, the plan status changes to Verified.

Phase 6 — Readiness Check & Package Lock​

The Readiness Check panel aggregates the status of all session gates:

GateRequired State
Research IntentAccepted
Concept SetsAll errors resolved; no deprecated concepts
CohortsAll verified and materialized; no deprecated imports
Feasibility EvidenceAccepted
Analysis PlanVerified

All five gates must show green before the Lock Package button becomes active.

Locking the Package​

  1. Click Lock Package.
  2. Parthenon assembles a locked package artifact containing:
    • Accepted intent document
    • Finalized concept set definitions (JSON)
    • Cohort expression definitions (Circe JSON)
    • Feasibility evidence report
    • Analysis plan specification
    • Session version history and AI event log
    • Package provenance manifest (hash, timestamp, locking user)
  3. The session moves to Locked state. No further edits are permitted on this version.
  4. A new version can be branched from a locked session if revisions are needed.

Downloading the Package​

  1. Open the locked session.
  2. Click Download Package.
  3. Parthenon performs a study ownership check — only the session owner or users with the study:package:download permission can download the artifact.
  4. The package downloads as a .zip archive suitable for submission to OHDSI network sites or archival.
Package Provenance

Each locked package includes a provenance.json manifest recording the session ID, version hash, lock timestamp, and the identity of the locking user. This manifest is verified on import into any Parthenon instance.

Session Timeline & Version History​

The Session Timeline (accessible from the left rail) provides a chronological view of all versioned changes:

  • Asset creation and edits
  • AI events (intent generation, critique invocations)
  • Verification runs and outcomes
  • Phase transitions
  • Package lock events

Click any timeline entry to inspect the full asset state at that point.

Permissions​

ActionRequired Role
Create a sessionstudy:create
Edit draftsstudy:edit (own sessions) or study:edit:any
Run feasibilitystudy:feasibility
Lock packagestudy:lock
Download packagestudy:package:download
View any sessionstudy:view:any

See Roles & Permissions for full role configuration.

Troubleshooting​

Package Lock Button Is Disabled​

Open the Readiness Check panel and inspect each gate. Common causes:

  • One or more concept sets still have deprecated concept errors → Diagnostics panel will highlight the offending concepts.
  • An imported cohort contains deprecated concepts → Resolve in the cohort draft editor.
  • Feasibility evidence has not been accepted → Run and accept feasibility.
  • Analysis plan verification has not been run or failed → Click Verify Analysis Plan.

Deprecated Concept Errors After Vocabulary Update​

If a vocabulary refresh deprecates concepts that were previously valid in your session:

  1. The session automatically re-runs the verifier after a vocabulary update is detected.
  2. Affected assets are flagged in the Diagnostics panel.
  3. Open each flagged concept set or cohort draft, replace deprecated concepts with current standard concepts, and re-verify.

Feasibility Queries Return Zero Counts​

  • Confirm the selected data source has completed CDM ETL and Achilles characterization.
  • Check that cohort generation completed successfully (see Jobs Monitoring).
  • Review cohort inclusion criteria — overly restrictive criteria can produce empty cohorts even on large data sources.