# Extracting Sdoh

Extracts social determinants of health (SDOH), housing instability, food insecurity...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill extracting-sdoh -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill extracting-sdoh -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill extracting-sdoh -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill extracting-sdoh -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Extracts social determinants of health (SDOH), housing instability, food insecurity, unemployment, transportation barriers, social isolation, financial strain, from clinical narrative and maps the spans to ICD-10-CM Z-codes (Z55, Z65). Use after running OpenMed NER when the user wants SDOH surfacing, Z-code suggestion, health-equity analytics, or to recover SDOH that is documented in free text but not coded. Pairs with OpenMed analyze_text output. Standards: ICD-10-CM Z55, Z65, Gravity Project value sets, n2c2 2022 SDOH track. Trigger keywords: SDOH, social determinants, Z-codes, housing, food insecurity, health equity, Gravity Project.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```python
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")

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/extracting-sdoh/SKILL.md