coding-icd10

# Coding OpenMed diagnoses to ICD-10-CM / PCS Suggest **ICD-10-CM** diagnosis codes (and **ICD-10-PCS** for inpatient procedures) for the diagnosis and procedure spans OpenMed extracts. This is **decision support for a certified coder**, not autonomous billing: OpenMed + this skill narrow the candidate set and explain *why*; a human validates the final, billable code. ICD-10-CM and ICD-10-PCS are **public domain**. CMS publishes the complete annual code files, addenda, and indexes for free. (CPT/HCPCS procedure codes are **AMA-licensed and restricted** — out of scope here; obtain those separately under the user's own AMA license.) ## When to use - A note yields diagnoses ("type 2 diabetes with diabetic CKD", "community- acquired pneumonia") and you want candidate ICD-10-CM codes plus rationale. - You need to **route** a span to the right chapter quickly (see `references/icd10-chapters.md` for code ranges). - You hold legacy ICD-9 codes and need an approximate **GEM** cross-walk. - You are pre-filling encounter diagnoses for a coder's review queue. For clinical-meaning codes use `mapping-to-snomed`; for HCC/risk capture use `coding-hcc-risk-adjustment`; this skill is for the ICD-10 classification. ## Quick start (public data + public FHIR lookup) Two complementary paths, both license-clean: **A) CMS files, loaded locally** (public domain; you download once): ```python # CMS publishes the order/addenda file; load the code->description table. # Columns: code (no dot), description; you insert the dot for display. icd10cm = {} # "E1122" -> "Type 2 diabetes mellitus with diabetic chronic kidney disease" with open("icd10cm_order_2025.txt", encoding="latin-1") as fh: for line in fh: code = line[6:13].strip() billable = line[14] == "1" # '1' = valid billable code long_desc = line[77:].strip() if billable: icd10cm[code] = long_desc def search_local(term: str, limit: int = 5): t = term.lower() hits = [(c, d) for c, d in icd10cm.items() if t in d.lower()] return sorted(hits, key=lambda cd: len(cd[1]))[:limit] ``` **B) A FHIR terminology server that hosts ICD-10-CM** (public servers exist; e.g. an NLM Clinical Tables endpoint or your own HAPI/Ontoserver): ```python import requests # NLM Clinical Tables (public, no key) — ICD-10-CM autocomplete/search: def search_icd10cm(term: str, count: int = 7): r = requests.get( "https://clinicaltables.nlm.nih.gov/api/icd10cm/v3/search", params={"sf": "code,name", "terms": term, "maxList": count}, timeout=10, ) r.raise_for_status() _total, codes, _extra, display = r.json() return list(zip(codes, [d[1] for d in display])) # [(code, name), ...] print(search_icd10cm("type 2 diabetes nephropathy")) ``` ## Workflow 1. **Extract** diagnosis/procedure spans with OpenMed (Disease/Pathology models). 2. **Route to a chapter** using the span's clinical theme and `references/icd10-chapters.md` (e.g. endocrine → E00–E89, circulatory → I00–I99). This shrinks the search space and catches obvious mis-hits. 3. **Search** the code text (local CMS table or the NLM API) for candidates. 4. **Apply ICD-10-CM specificity rules** in your rationale: laterality, acute/chronic, episode of care, "with"/"due to" combination codes, and "code first / use additional code" notes. Flag where the note lacks the detail a billable code requires. 5. **Rank** candidates; present the top few **with rationale and the missing- detail caveat**, not a single auto-selected code. 6. **Emit** `{system: "http://hl7.org/fhir/sid/icd-10-cm", code, display}` marked `status: needs-coder-review`, with OpenMed source offsets. ## Hand-off from OpenMed `openmed.analyze_text(..., output_format="dict")` returns `entities`, each a dict with `text`, `label`, `confidence`, `start`, `end`. Consume Disease/Pathology spans: ```python import openmed note = "Assessment: type 2 diabetes with diabetic nephropathy; CAP." result = openmed.analyze_text( note, model_name="disease_detection_superclinical", # Disease category output_format="dict", ) DX_LABELS = {"DISEASE", "CONDITION", "PATHOLOGY"} for ent in result["entities"]: if ent["label"] in DX_LABELS: candidates = search_icd10cm(ent["text"], count=5) print(ent["text"], ent["start"], ent["end"], f"(conf {ent['confidence']:.2f}) ->", candidates) # surface as SUGGESTIONS for a coder — never auto-bill ``` Keep OpenMed's `start`/`end` offsets next to each suggested code so the coder can jump to the exact supporting text. Store offsets and codes only — never the raw note in your suggestion log. ## Edge cases & gotchas - **Human-in-the-loop is mandatory.** ICD-10-CM coding has legal/financial weight. Output candidates with rationale; a certified coder assigns the final billable code. Never present a suggestion as an authorized claim. - **Specificity & unspecified codes.** Many billable codes demand laterality, episode, or "with" detail the note may not state. Prefer flagging "documentation insufficient for a specific code" over forcing an `.9`/unspecified code. - **Combination codes.** ICD-10-CM bundles related conditions (e.g. E11.22 = diabetes *with* diabetic CKD). Don't emit two separate codes where one combination code is required; let the search surface combinations. - **"Code first" / "use additional code" / Excludes1/Excludes2** sequencing notes change which codes coexist. Carry these as rationale for the coder. - **GEMs are approximate.** ICD-9↔ICD-10 General Equivalence Mappings are many-to-many and lossy; treat a GEM result as a starting hint, not a billable mapping. - **Annual updates.** Codes change every fiscal year (Oct 1). Pin the file year you loaded and refresh annually; record which version produced a suggestion. - **Licensing.** ICD-10-CM/PCS are public domain (CMS). Do **not** pull in CPT or proprietary code maps that require an AMA/other license — those stay user-supplied and out-of-process. - **Local-first.** OpenMed NER runs on-device; if you query the NLM API, send only the de-identified diagnosis string. No PHI over the wire. ## Standards & references - ICD-10-CM files (CMS, public domain): https://www.cms.gov/medicare/coding-billing/icd-10-codes/icd-10-cm-cms-hcc and https://www.cms.gov/medicare/coding-billing/icd-10-codes - ICD-10-PCS files (CMS): https://www.cms.gov/medicare/coding-billing/icd-10-codes/icd-10-pcs - NLM Clinical Tables ICD-10-CM API (public, no key): https://clinicaltables.nlm.nih.gov/apidoc/icd10cm/v3/doc.html - GEMs (General Equivalence Mappings): https://www.cms.gov/medicare/coding-billing/icd-10-codes/icd-10-cm-pcs-gems-archive - Chapter/section ranges: `references/icd10-chapters.md`