StitchEDC: Clinical Study Setup Metadata Compiler & Validator

CDISC ODM 1.3.2 & 21-Entity Semantic Schema Specification for Clinical Programmers

StitchEDC is an advanced, automated clinical metadata compiler designed to ingest unstructured trial protocols or clinical state structures and output fully compliant CDISC ODM v1.3.2 XML study setups.

By mapping raw protocol constraints into a formal 21-Definition Canonical Schema, StitchEDC bridges the gap between study protocols and production-ready electronic Data Capture (EDC) environments, providing real-time verification of study logic before database locking.

---

🏗️ Technical Architecture & The 21-Entity Semantic Schema

At the heart of StitchEDC lies a strict JSON-Schema abstraction (canonical_study.schema.json) that model compilers and translation scripts must resolve to. This schema covers 21 distinct structural definitions grouped across three critical layers:

                  ┌──────────────────────────────────────────────┐
                  │          PROTOCOL & METRICS LAYER            │
                  │  1. Protocol Identity    2. Descriptors (MAMS)│
                  │  3. Estimands            4. Eligibility (I/E)│
                  │  5. Clinical Endpoints   6. DOOR Scales       │
                  └──────────────────────┬───────────────────────┘
                                         ▼
                  ┌──────────────────────────────────────────────┐
                  │              TRIAL DESIGN LAYER              │
                  │  7. Stages               8. Treatment Arms   │
                  │  9. Analysis Gates      10. Stratum Factors  │
                  └──────────────────────┬───────────────────────┘
                                         ▼
                  ┌──────────────────────────────────────────────┐
                  │           DATA COLLECTION LAYER              │
                  │ 11. Calendar Epochs     12. Timeline Visits  │
                  │ 13. CRF Templates       14. Item Layout Groups│
                  │ 15. Form Items/Fields   16. Codelists / Decodes│
                  │ 17. Visit×Form Matrix                        │
                  └──────────────────────┬───────────────────────┘
                                         ▼
                  ┌──────────────────────────────────────────────┐
                  │            LOGICAL RULES ENGINE              │
                  │ 18. Edit Checks (Cross) 19. Derivations      │
                  │ 20. Access Control Roles21. Change Audit/Prov│
                  └──────────────────────────────────────────────┘

1. The Protocol & Metrics Layer

1. protocol_identity: Captures primary keys including protocol_id, standard phase designations (I/Ib/II/IIa/IIb/III/IV), therapeutic area, study sponsor, and target_enrollment.
2. design_descriptors: Binds architectural flags such as Multi-Arm Multi-Stage (MAMS), blinding style (open-label, double-blind, triple-blind), non-inferiority margins, and adaptive seamless transitions.
3. estimands: Formalizes the precise scientific question on the trial by pairing target subject population, intervention strategy, clinical endpoints, and rules for intercurrent event resolution.
4. structured_eligibility: Deconstructs inclusion and exclusion criteria into database-executable flags map-wired directly back to screening item variables.
5. endpoint: Maps primary, secondary, and exploratory protocol endpoints.
6. door_ranking: Specifically isolates multi-state complex matrices, formulating Desirability of Outcome Ranking (DOOR) hierarchies.

2. The Trial Design Layer

7. stage: Defines sequential adaptive trials segments governed by specific gates.
8. arm: Represents study treatment pathways linked directly to corresponding study stages.
9. analysis_gate: Declares trial interim analysis criteria (e.g., sample-size triggers, DSMB futility limits, or O'Brien-Fleming efficacy alpha-boundaries).
10. stratification: Maps key randomization balancing indicators (e.g., diagnostic sub-strata, clinical site IDs) mapped to active target variables.

3. The Data Collection Layer

11. epoch: Demarcates the clinical trial schedule (e.g., screening cycle, active intervention period, recovery, long-term safety follow-up).
12. event: Outlines physical clinic visits or remote monitoring checkpoints.
13. form: Represents individual Case Report Forms (CRF) or clinical domains.
14. item_group: Structural layout partitions (tabular matrices, continuous forms) inside individual CRFs.
15. field: Fully resolved database metadata items containing strict CDISC data types (Date, Integer, Float, Text, Boolean, Coded) and target units.
16. code_list: Translation dictionaries carrying internal software transaction values (code) paired with human-readable language strings (decode).
17. visit_form_link: Connects visits (event_id) to CRFs (form_id), generating the logical study collection calendar grid.

4. Logic & Operations

18. edit_check: Declares diagnostic and semantic validation formulas (including cross-form or time-offset dependencies) to prevent input errors on paperless sites.
19. derivation: Governs calculated database endpoints (e.g., BMI, Mean Arterial Pressure, Creatinine Clearance) so secondary fields are auto-populated.
20. role: Implements Role-Based Access Control permissions mapping investigator, monitor, CRA, and auditor workflows.
21. provenance: An integrated review audit block attached to every schema definition block tracking generation model confidence metrics, reviewer overrides, timestamps, and validation stamps.

---

🔒 The 5 Crucial Clinical Failure Modes

Standard XML schemas only check basic syntax (like tag structures). To prevent database errors in production, StitchEDC integrates a robust semantic rules validator (validate_schema.py & schemaChecker.ts) that screens for five critical clinical failure modes:

🚨 Failure Mode 1: Empty Code Lists & Options

• The Gaps: Programmers declare a coded field (e.g., Sex, Race, Toxicity Grade) but fail to configure option values, leaving the CRF dropdown empty.
• The Check: Parses database schemas, flag and blocks any code_list that has zero list members ("items" is empty), or contains any option with a null code or empty description decode.

🚨 Failure Mode 2: Orphaned Code Lists

• The Gaps: Code lists are defined in the database but are completely disconnected from any item field or domain space. This causes code drift, bloating the study metadata.
• The Check: Aggregates all references in the database. Generates code-list usage warnings for clinical programmers to prune unreferenced dictionaries.

🚨 Failure Mode 3: Broken Design & Stage Wiring

• The Gaps: Arm pathways are defined but have no stage associations, or calendar visit events have invalid references to timeline segments (Epochs). This leads to unassigned subjects or untracked clinical data.
• The Check: Ensures every designated arm maps to at least one active study stage, verifies all interim analysis_gates reference active definitions, and guarantees scheduled events are bounded by real epochs.

🚨 Failure Mode 4: Dangling Reference Links

• The Gaps: Fields reference undefined CRFs, visit matrices link to deleted visit dates, or inclusion/exclusion rules link to deleted questions.
• The Check: Performs full relational integrity diagnostics on the schema graph. It flags any reference where: $$\text{Target OID} \notin {\text{Declared Primary Identifiers}}$$ This includes checking fields mapping to missing layout groups, cross-form derivations referencing missing fields, and eligibility rules referencing non-existent data points.

🚨 Failure Mode 5: Malformed DOOR Rankings

• The Gaps: Desirability of Outcome Ranking (DOOR) scales are configured incorrectly (e.g., skipping ranks, duplicate numbers, or non-sequential ranges).
• The Check: Programmatically validates that DOOR scale rankings are unique, sequential, and start exactly at $1$ ($1, 2, 3, \ldots, N$). Any non-contiguous or missing numbers are flagged as severe database configuration errors.

---

💻 Running the Command-Line Validator

StitchEDC contains a standalone, server-compatible Python script (validate_schema.py) to validate your study setup. You can run it on your CI/CD pipelines, build scripts, or terminals:

CLI Execution Pattern:

python3 validate_schema.py path_to_your_study_design.json

Sample stdout Diagnostics Report:

=======================================================
StitchEDC Clinical Trial Ingest Validator Diagnostics Report
=======================================================
Clinical Fields Audited: 18
CRF Forms Scanned:        8
Outcome Endpoints Map:     2
Total Errors Found:       0
Total Warnings Flagged:   1
=======================================================

🟢 NO CRITICAL COMPILATION SCHEMA ERRORS DISCOVERED. VALID STITCHEDC INGEST STUDY.

⚠️ ARCHITECTURAL DESIGN WARNINGS FLAGGED:
  - [Orphaned Code List] Code list 'CL_LB_CSF_LACTATE' exists but is never referenced.

---

🕸️ Neo4j Topological Graph Exporter (export_clinical_graph.py)

For advanced clinical research data groups, comparing protocol setups across multiple trials is a major bottleneck. StitchEDC resolves this by treating the entire 21-definition clinical domain space as a topological property graph.

The standalone Python tool export_clinical_graph.py parses a study setup and outputs a comprehensive Neo4j Cypher script ready to build transaction-safe indexes and multi-edge connected clinical nodes.

Topological Structural Relationships Built:

• Protocol Backbone: (:Protocol) -[:HAS_ARM]-> (:Arm) and (:Protocol) -[:CONDUCTED_AT]-> (:Site)
• Clinical Timeline: (:Protocol) -[:HAS_VISIT]-> (:Visit)
• Data-Dictionary Layout: (:Visit)-[:COLLECTS {mandatory: boolean}]-> (:Form) -[:CONTAINS_FIELD]-> (:Field) -[:USES_CODELIST]-> (:CodeList)
• Rigor and Quality Control: (:Field) -[:VALIDATED_BY]-> (:EditCheck)

CLI Graph Exporter Execution Pattern:

python3 export_clinical_graph.py path_to_your_study_design.json study_graph.cypher

Advanced Clinical Graph Traversal Queries (Cypher Examples):

Data scientists and trial designers can run highly specialized Cypher questions instantly in the Neo4j browser:

1. Investigator Cognitive Burden: Look for overloaded clinic visits by counting total field entries expected at each physical visit checkpoint.

   MATCH (v:Visit)-[:COLLECTS]->(f:Form)-[:CONTAINS_FIELD]->(fi:Field)
   RETURN v.name AS Visit, count(fi) AS TotalFields, count(DISTINCT f) AS FormsCount
   ORDER BY TotalFields DESC;

2. Clinical Logic dependencies audit: Trace multi-form validation formulas and dependencies to map validation rules to specific clinical domains.

   MATCH (f:Form)-[:CONTAINS_FIELD]->(fi:Field)-[:VALIDATED_BY]->(ec:EditCheck)
   RETURN f.cdisc_domain AS Domain, fi.name AS TargetField, ec.rule AS RuleExpression
   ORDER BY Domain;

---

🧬 CDISC ODM XML Compilation Details

The exported StitchEDC_ODM_Setup.xml is fully compliant with the CDISC ODM XML Version 1.3.2 schema, allowing clinical database designers to import the generated files directly into standard EDCs (like Viedoc, Rave, or OpenClinica).

Key Compilation Rules Applied:

• CreationDateTime: Auto-generated timestamping conform to ISO 8601 formatting.
• FileOID / StudyOID: Formats structured strings incorporating protocol identifiers and cryptographic epoch values.
• XmlEscape: Safe encoding rules applied across all protocol titles, labels, edit check error messages, and descriptions to ensure stable file handling.
• Custom Metadata Block: Appends stratification elements, treatment arms, and edit-check equations as structured auxiliary comments, streamlining database setups.

---

Developed for Global Clinical Data Managers and Research Coordinators by StitchEDC Studio.