/reconciling-problem-lists

name: reconciling-problem-lists
description: "Deduplicate and reconcile OpenMed-extracted conditions into one clean active problem list with clinical status (active / resolved / historical). Use after NER and context resolution when the user wants a problem list, condition reconciliation, dedup of synonymous diagnosis mentions, or active-vs-resolved status from a note. Covers clustering synonymous mentions into one concept, excluding negated mentions, applying clinical context (historical / hypothetical / recent) to set status, and emitting a USCDI-Problem-shaped list. SNOMED CT concept grounding is user-supplied and out-of-process. Hand-off: consume openmed.analyze_text Disease entities plus resolving-clinical-context axes. Pairs after extracting-clinical-entities."
license: Apache-2.0
metadata:
  project: OpenMed
  category: clinical-nlp
  pairs: after
  version: "1.0"

Reconciling problem lists

A single note mentions the same condition many ways — "DM2," "type 2 diabetes," "diabetes mellitus" — across PMH, HPI, and A&P, some negated, some historical. A usable **problem list** collapses those mentions into one concept per problem, drops what the patient does not have, and assigns a clinical status (active / resolved / historical). This skill turns OpenMed's per-mention entity stream plus ConText axes into that reconciled, de-duplicated list, shaped for USCDI "Problem" exchange.

When to use

• After `extracting-clinical-entities` and `resolving-clinical-context`, when the

user wants a clean problem list, condition reconciliation, or dedup of repeated diagnosis mentions.

• You need active-vs-resolved-vs-historical status per problem, not just raw

mentions.

• You are assembling a FHIR Condition list or a USCDI Problem element and need

one entry per concept.

Quick start

import openmed
from openmed.clinical import resolve_span_context, NEGATED, HISTORICAL, HYPOTHETICAL

note = ("PMH: type 2 diabetes, prior MI 2019 (resolved). "
        "A&P: poorly controlled DM2; denies chest pain.")

ents = openmed.analyze_text(note, model_name="disease_detection_superclinical",
                            output_format="dict")

def normalize(surface: str) -> str:
    # Cheap synonym folding; replace with SNOMED grounding (out-of-process).
    s = surface.lower().strip()
    return {"dm2": "type 2 diabetes", "diabetes mellitus": "type 2 diabetes"}.get(s, s)

problems = {}  # concept -> reconciled record
for e in ents:
    surface = e["word"]
    ctx = resolve_span_context(surface, note)
    if ctx.negation == NEGATED:
        continue                                   # patient does NOT have it -> exclude
    concept = normalize(surface)
    status = ("resolved" if ctx.temporality == HISTORICAL else
              "active")
    if ctx.temporality == HYPOTHETICAL:
        continue                                   # not asserted as present
    rec = problems.setdefault(concept, {"concept": concept, "status": status,
                                        "mentions": 0})
    rec["mentions"] += 1
    # Active anywhere wins over a historical mention of the same concept.
    if status == "active":
        rec["status"] = "active"

problem_list = list(problems.values())
# -> [{"concept": "type 2 diabetes", "status": "active", "mentions": 2}, ...]
# "chest pain" excluded (negated); "MI" -> historical/resolved.

Workflow

1. **Collect Disease/Condition entities** from `analyze_text` across the whole note (or per section if you ran `segmenting-clinical-sections`). 2. **Attach clinical context** per mention with `resolve_span_context` (or the axes from `resolving-clinical-context`): negation, temporality, uncertainty. 3. **Exclude what isn't a problem.** Drop `NEGATED` mentions (patient denies / no evidence of) and `HYPOTHETICAL` mentions (conditional, not asserted). These must never land on the active list. 4. **Cluster synonymous mentions into one concept.** Fold surface variants (abbreviations, word order, lexical synonyms) to a single canonical key. Cheap normalization gets you started; **SNOMED CT concept grounding** is the robust path — run it out-of-process with the user's own license and key on the concept code, not the surface string. 5. **Assign status by aggregating context.** A concept that is `RECENT`/active anywhere (typically A&P) is **active**; one seen only as `HISTORICAL` ("history of," "resolved," PMH-only) is **resolved/historical**. Active wins over historical when the same concept appears both ways. 6. **Emit the reconciled list** — one record per concept with status, mention count, and provenance offsets — shaped for USCDI Problem / FHIR Condition.

Hand-off to / from OpenMed

• **From** `extracting-clinical-entities`: consumes `analyze_text` Disease

entities. Run on a sectioned note (`segmenting-clinical-sections`) for best active-vs-historical signal.

• **From** `resolving-clinical-context`: this skill *depends* on the negation /

temporality / uncertainty axes — reconciliation without them would put "denies chest pain" on the active list.

• **OpenMed calls:** `from openmed import analyze_text` and

`from openmed.clinical import resolve_span_context, NEGATED, HISTORICAL, HYPOTHETICAL`.

• **To FHIR / USCDI:** each reconciled problem becomes a Condition with

`clinicalStatus` active/resolved (from temporality) and `verificationStatus` refuted/provisional (from negation/uncertainty). SNOMED CT codes are user-supplied and grounded out-of-process — OpenMed produces the dedup'd concept and status, not the terminology binding.

Edge cases & gotchas

• **Surface dedup is lossy.** "MI" and "myocardial infarction" only fold if your

normalizer knows the synonym. Lexical folding handles the easy cases; lean on SNOMED CT grounding for real reconciliation, and never bundle SNOMED — call it out-of-process with the user's credentials.

• **Active beats historical for the same concept.** "History of