extracting-sdoh

Extracting SDOH and Mapping to ICD-10-CM Z-Codes

Social determinants of health (SDOH) — the conditions in which people live, work, and age — drive an estimated 80% of health outcomes, yet they live almost entirely in free-text narrative. Multiple chart-review studies find SDOH documented in notes but coded with a Z-code under ~2% of the time. The information is there; the structured signal is not. This skill recovers it: run OpenMed NER over de-identified notes, then map the resulting spans to the ICD-10-CM Z55–Z65 family.

When to use

• A note clearly describes a social risk ("lives in her car", "skips meals to afford insulin", "no ride to dialysis") and you want a coded, queryable signal.
• You are building health-equity dashboards, risk stratification, or closed-loop referral feeds and need SDOH as discrete data.
• You want to reconcile what the chart says against what was coded, and flag Z-code gaps for a coder or care team to confirm.

This is a decision-support step. It proposes Z-codes; a human assigns them. SDOH coding is sensitive — never expose individual SDOH inferences outside the care/coding workflow, and never feed them to coverage or pricing decisions.

Quick start

De-identify first, run NER, then map spans to Z-codes:

import openmed
from sdoh_zcode_map import SDOH_ZCODES  # see references/sdoh_zcode_map.md

note = (
    "62F with CHF. Reports she lost her apartment last month and is "
    "staying in a shelter. Often runs out of food before month-end. "
    "No car; misses appointments because the bus does not run to clinic."
)

# 1) Strip PHI before any downstream processing or storage.
deid = openmed.deidentify(note, method="replace", policy="hipaa_safe_harbor")

# 2) Run clinical NER. Use an SDOH/clinical model from the registry; discover
#    available keys with openmed.get_models_by_category(...).
result = openmed.analyze_text(deid.text, output_format="dict")

# 3) Map each entity span to a candidate Z-code.
for ent in result["entities"]:
    code = SDOH_ZCODES.get(ent["label"].lower())
    if code:
        print(f"{ent['text']!r:40}  {ent['label']:18}  -> {code}")