Parsing trial eligibility & matching patients

A ClinicalTrials.gov study exposes its eligibility as a single free-text block (protocolSection.eligibilityModule.eligibilityCriteria) plus a few typed fields (sex, minimumAge, maximumAge, healthyVolunteers). This skill turns that prose into structured inclusion / exclusion criteria and matches each rule against patient facts that OpenMed extracted — producing an explainable eligible | ineligible | unknown verdict per criterion.

This is decision support, not enrollment. The output is a candidate list and a rationale for a clinician to review, never an automated eligibility decision.

When to use

• You pulled a study with searching-clinicaltrials and need its eligibility as machine-readable rules.
• You have a (synthetic) patient profile and want to screen it against one or many trials, with a per-criterion reason.
• You want to highlight which patient facts are missing to decide a criterion.

Quick start

The typed gates are deterministic — apply them first. The free-text criteria need parsing into bullet-level inclusion/exclusion items.

# Study from ClinicalTrials.gov v2 (see searching-clinicaltrials)
elig = study["protocolSection"]["eligibilityModule"]

raw = elig["eligibilityCriteria"]            # free text, often markdown bullets
sex = elig.get("sex", "ALL")                 # ALL | FEMALE | MALE
min_age = elig.get("minimumAge")             # e.g. "18 Years"
max_age = elig.get("maximumAge")             # e.g. "75 Years"
healthy_ok = elig.get("healthyVolunteers")   # bool

def split_criteria(text: str) -> dict[str, list[str]]:
    """Split the prose into inclusion / exclusion bullet lists."""
    sections, current = {"inclusion": [], "exclusion": []}, None
    for line in text.splitlines():
        low = line.strip().lower()
        if "inclusion criteria" in low:
            current = "inclusion"; continue
        if "exclusion criteria" in low:
            current = "exclusion"; continue
        bullet = line.strip(" -*•\t")
        if bullet and current:
            sections[current].append(bullet)
    return sections

criteria = split_criteria(raw)

Each bullet is a candidate rule. Structure it into a comparable predicate: condition present/absent, lab threshold, age/sex, prior-therapy, performance status (e.g. ECOG ≤ 2), pregnancy status, etc.

from dataclasses import dataclass

@dataclass
class Criterion:
    kind: str            # "condition" | "lab" | "age" | "sex" | "medication" | "other"
    polarity: str        # "include" | "exclude"
    text: str            # original bullet
    target: str | None   # e.g. "ECOG", "diabetes", "metformin"
    op: str | None = None  # "<=", ">=", "==", "present", "absent"
    value: float | str | None = None

Matching against OpenMed-extracted patient facts

Build the patient profile from openmed.analyze_text outputs plus structured demographics, then evaluate each criterion to a three-valued result.

patient = {
    "age": 61, "sex": "FEMALE",
    "conditions": {"type 2 diabetes", "hypertension"},   # OpenMed Disease spans
    "medications": {"metformin", "lisinopril"},          # OpenMed Pharmaceutical
    "labs": {"hba1c": 8.1, "ecog": 1},                   # from a labs extractor
}

def evaluate(c: Criterion, p: dict) -> str:
    if c.kind == "sex" and c.target:
        return "pass" if p["sex"] == c.target or c.target == "ALL" else "fail"
    if c.kind == "condition" and c.target:
        has = c.target.lower() in {x.lower() for x in p["conditions"]}
        ok = has if c.polarity == "include" else not has
        return "pass" if ok else "fail"
    if c.kind == "lab" and c.target and c.target.lower() in p["labs"]:
        v = p["labs"][c.target.lower()]
        cmp = {"<=": v <= c.value, ">=": v >= c.value, "==": v == c.value}
        return "pass" if cmp.get(c.op, False) else "fail"
    return "unknown"   # fact not present → needs human review, never assume pass

Aggregate: a patient is a candidate only if every inclusion criterion is pass (or unknown, flagged) and every exclusion criterion is not fail. Surface the unknown items prominently — missing data is the most common reason a real screen needs a human.

Workflow

1. Apply the typed gates (sex, minimumAge, maximumAge) — cheap, exact.
2. Split the free text into inclusion / exclusion bullets.
3. Structure each bullet into a Criterion (kind, polarity, target, op, value). NER on the bullet via openmed.analyze_text finds the condition / drug / lab targets; numeric thresholds come from a regex/units pass.
4. Evaluate each criterion against the OpenMed-derived patient profile to pass | fail | unknown.
5. Report a verdict with a per-criterion rationale and an explicit list of unknown facts that block a confident decision.

Hand-off to / from OpenMed

• From OpenMed (patient side). Run openmed.analyze_text over the patient note to populate conditions (Disease), medications (Pharmaceutical), and oncology context; normalize via coding-icd10 / normalizing-rxnorm so comparisons are code-based, not string-based.
• From OpenMed (trial side). Run openmed.analyze_text over each eligibility bullet to identify the condition / drug / lab the rule references, improving target extraction beyond keyword spotting.
• From searching-clinicaltrials. Studies arrive with their eligibilityModule already populated — this skill is the next stage.
• Keep everything local: matching runs on-device against the patient profile; no PHI leaves the process. Examples here use a synthetic patient.

Edge cases & gotchas

• Three-valued logic is mandatory. Treating unknown as pass enrolls ineligible patients; treating it as fail drops eligible ones. Surface it.
• Negation & temporality. "No prior chemotherapy" vs "prior chemotherapy" flips polarity; "active infection" vs "history of infection" differs in time. Use openmed.clinical (see resolving-clinical-context) so negated/historical mentions are not counted as present.
• Units & ranges. "Creatinine clearance ≥ 60 mL/min", "platelets > 100,000/µL" — normalize units before comparing; LOINC grounding (mapping-loinc) helps.
• Compound bullets. One sentence may carry several predicates ("age 18-75 and ECOG 0-1"). Split into atomic criteria.
• Inconsistent headings. Some studies omit explicit "Inclusion/Exclusion" labels or use "Key Inclusion Criteria". Default unlabeled bullets to inclusion and flag for review.
• Not a medical device. Output is a ranked candidate list with rationale for a clinician — never an autonomous enrollment or exclusion decision.

Standards & references

• ClinicalTrials.gov study structure (eligibilityModule) — https://clinicaltrials.gov/data-api/about-api/study-data-structure
• Protocol Registration eligibility data definitions — https://clinicaltrials.gov/policy/protocol-definitions
• Common Data Element: eligibility criteria — https://clinicaltrials.gov/data-api/about-api/study-data-structure#eligibilityModule
• OpenMed clinical context (negation/temporality) — resolving-clinical-context