# yubin-park/hccpy architecture

> Architecture diagram of the GitHub repository yubin-park/hccpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yubin-park/hccpy
- Repository: https://github.com/yubin-park/hccpy

## Overview

hccpy is a Python package for health-risk adjustment: callers provide member demographics and diagnosis codes (plus drug and procedure codes for HHS), and receive HCC profiles and risk scores. CMS-HCC and HHS-HCC engines map codes, apply edits and hierarchies, generate model interactions, and calculate scores; CMS scoring also supports normalization and coding-intensity adjustment. The package additionally describes HCCs, compares HCC lists, and checks claim-code eligibility. Unsampled modules and data are represented only at paths supported by the tree and documented interfaces.

Main entry points: [`hccpy/hcc.py`](https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py) (CMS-HCC engine), [`hccpy/hhshcc.py`](https://github.com/yubin-park/hccpy/blob/master/hccpy/hhshcc.py) (HHS-HCC engine), [`hccpy/utils.py`](https://github.com/yubin-park/hccpy/blob/master/hccpy/utils.py) (CMS data readers), [`hccpy/utils_hhs.py`](https://github.com/yubin-park/hccpy/blob/master/hccpy/utils_hhs.py) (HHS data readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engines["Risk engines"]
  node_hcc_engine["CMS-HCC engine<br/>[hcc.py]"]
  node_hhs_engine["HHS-HCC engine<br/>[hhshcc.py]"]
end

subgraph group_classification["Code classification"]
  node_cms_data["CMS model data"]
  node_hhs_data["HHS model data"]
  node_cms_utils["CMS data readers<br/>[utils.py]"]
  node_hhs_utils["HHS data readers<br/>[utils_hhs.py]"]
  node_cms_edits["CMS age-sex edits<br/>[_V22I0ED2.py]"]
  node_v28_edits["V28 age-sex edits<br/>[_V28I0ED1.py]"]
  node_hhs_edits["HHS age-sex edits<br/>[_I0V05ED2.py]"]
  node_hierarchy["HCC hierarchy<br/>[hcc.py]"]
  node_cms_demo["CMS demographics<br/>[_AGESEXV2.py]"]
  node_hhs_demo["HHS demographics<br/>[_AGESEXV6.py]"]
end

subgraph group_scoring["Risk scoring"]
  node_cms_interactions["CMS interactions<br/>[_V2419P1M.py]"]
  node_v22_interactions["V22 interactions<br/>[_V2218O1M.py]"]
  node_v23_interactions["V23 interactions<br/>[_V2318P1M.py]"]
  node_v28_interactions["V28 interactions<br/>[_V2823T2M.py]"]
  node_esrd_interactions["ESRD interactions<br/>[_E2118P1M.py]"]
  node_hhs_interactions["HHS interactions<br/>[_V0519F3M.py]"]
  node_cms_coefficients["CMS coefficients<br/>[_V2218O1P.py]"]
  node_esrd_coefficients["ESRD coefficients<br/>[_E2118P1P.py]"]
  node_hhs_coefficients["HHS coefficients<br/>[_V0519F3P.py]"]
end

subgraph group_support["Eligibility and support"]
  node_ra_eligible["Claim eligibility<br/>[raeligible.py]"]
  node_hcc_tools["Describe and diff<br/>[hcc.py]"]
  node_hhs_diff["HHS profile diff<br/>[hhshcc.py]"]
end

node_caller(("Package caller"))

node_caller -->|"profiles member"| node_hcc_engine
node_caller -->|"profiles member"| node_hhs_engine
node_caller -->|"checks claims"| node_ra_eligible
node_hcc_engine -->|"loads model data"| node_cms_utils
node_cms_utils -->|"reads mappings and factors"| node_cms_data
node_hcc_engine -->|"derives demographics"| node_cms_demo
node_hcc_engine -->|"edits diagnoses"| node_cms_edits
node_hcc_engine -->|"edits V28 diagnoses"| node_v28_edits
node_hcc_engine -->|"applies hierarchy"| node_hierarchy
node_hcc_engine -->|"dispatches V22"| node_v22_interactions
node_hcc_engine -->|"dispatches V23"| node_v23_interactions
node_hcc_engine -->|"dispatches V24"| node_cms_interactions
node_hcc_engine -->|"dispatches V28"| node_v28_interactions
node_hcc_engine -->|"dispatches ESRD"| node_esrd_interactions
node_hcc_engine -->|"scores CMS models"| node_cms_coefficients
node_hcc_engine -->|"scores ESRD"| node_esrd_coefficients
node_hhs_engine -->|"loads model data"| node_hhs_utils
node_hhs_utils -->|"reads mappings and factors"| node_hhs_data
node_hhs_engine -->|"derives demographics"| node_hhs_demo
node_hhs_engine -->|"edits diagnoses"| node_hhs_edits
node_hhs_engine -->|"creates interactions"| node_hhs_interactions
node_hhs_engine -->|"calculates risk score"| node_hhs_coefficients
node_caller -->|"describes or compares HCCs"| node_hcc_tools
node_caller -->|"compares HHS lists"| node_hhs_diff

click node_hcc_engine "https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py"
click node_hhs_engine "https://github.com/yubin-park/hccpy/blob/master/hccpy/hhshcc.py"
click node_cms_data "https://github.com/yubin-park/hccpy/tree/master/hccpy/data"
click node_hhs_data "https://github.com/yubin-park/hccpy/tree/master/hccpy/data"
click node_cms_utils "https://github.com/yubin-park/hccpy/blob/master/hccpy/utils.py"
click node_hhs_utils "https://github.com/yubin-park/hccpy/blob/master/hccpy/utils_hhs.py"
click node_cms_edits "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V22I0ED2.py"
click node_v28_edits "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V28I0ED1.py"
click node_hhs_edits "https://github.com/yubin-park/hccpy/blob/master/hccpy/_I0V05ED2.py"
click node_hierarchy "https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py"
click node_cms_demo "https://github.com/yubin-park/hccpy/blob/master/hccpy/_AGESEXV2.py"
click node_hhs_demo "https://github.com/yubin-park/hccpy/blob/master/hccpy/_AGESEXV6.py"
click node_cms_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2419P1M.py"
click node_v22_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2218O1M.py"
click node_v23_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2318P1M.py"
click node_v28_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2823T2M.py"
click node_esrd_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_E2118P1M.py"
click node_hhs_interactions "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V0519F3M.py"
click node_cms_coefficients "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2218O1P.py"
click node_esrd_coefficients "https://github.com/yubin-park/hccpy/blob/master/hccpy/_E2118P1P.py"
click node_hhs_coefficients "https://github.com/yubin-park/hccpy/blob/master/hccpy/_V0519F3P.py"
click node_ra_eligible "https://github.com/yubin-park/hccpy/blob/master/hccpy/raeligible.py"
click node_hcc_tools "https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py"
click node_hhs_diff "https://github.com/yubin-park/hccpy/blob/master/hccpy/hhshcc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hcc_engine,node_hhs_engine toneBlue
class node_cms_data,node_hhs_data,node_cms_utils,node_hhs_utils,node_cms_edits,node_v28_edits,node_hhs_edits,node_hierarchy,node_cms_demo,node_hhs_demo toneAmber
class node_cms_interactions,node_v22_interactions,node_v23_interactions,node_v28_interactions,node_esrd_interactions,node_hhs_interactions,node_cms_coefficients,node_esrd_coefficients,node_hhs_coefficients toneMint
class node_ra_eligible,node_hcc_tools,node_hhs_diff toneRose
class node_caller toneIndigo
```

## Components

### Risk engines

- [CMS-HCC engine](https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py): `hccpy/hcc.py`
- [HHS-HCC engine](https://github.com/yubin-park/hccpy/blob/master/hccpy/hhshcc.py): `hccpy/hhshcc.py`

### Code classification

- [CMS model data](https://github.com/yubin-park/hccpy/tree/master/hccpy/data): `hccpy/data`
- [HHS model data](https://github.com/yubin-park/hccpy/tree/master/hccpy/data): `hccpy/data`
- [CMS data readers](https://github.com/yubin-park/hccpy/blob/master/hccpy/utils.py): `hccpy/utils.py`
- [HHS data readers](https://github.com/yubin-park/hccpy/blob/master/hccpy/utils_hhs.py): `hccpy/utils_hhs.py`
- [CMS age-sex edits](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V22I0ED2.py): `hccpy/_V22I0ED2.py`
- [V28 age-sex edits](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V28I0ED1.py): `hccpy/_V28I0ED1.py`
- [HHS age-sex edits](https://github.com/yubin-park/hccpy/blob/master/hccpy/_I0V05ED2.py): `hccpy/_I0V05ED2.py`
- [HCC hierarchy](https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py): `hccpy/hcc.py`
- [CMS demographics](https://github.com/yubin-park/hccpy/blob/master/hccpy/_AGESEXV2.py): `hccpy/_AGESEXV2.py`
- [HHS demographics](https://github.com/yubin-park/hccpy/blob/master/hccpy/_AGESEXV6.py): `hccpy/_AGESEXV6.py`

### Risk scoring

- [CMS interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2419P1M.py): `hccpy/_V2419P1M.py`
- [V22 interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2218O1M.py): `hccpy/_V2218O1M.py`
- [V23 interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2318P1M.py): `hccpy/_V2318P1M.py`
- [V28 interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2823T2M.py): `hccpy/_V2823T2M.py`
- [ESRD interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_E2118P1M.py): `hccpy/_E2118P1M.py`
- [HHS interactions](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V0519F3M.py): `hccpy/_V0519F3M.py`
- [CMS coefficients](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V2218O1P.py): `hccpy/_V2218O1P.py`
- [ESRD coefficients](https://github.com/yubin-park/hccpy/blob/master/hccpy/_E2118P1P.py): `hccpy/_E2118P1P.py`
- [HHS coefficients](https://github.com/yubin-park/hccpy/blob/master/hccpy/_V0519F3P.py): `hccpy/_V0519F3P.py`

### Eligibility and support

- [Claim eligibility](https://github.com/yubin-park/hccpy/blob/master/hccpy/raeligible.py): `hccpy/raeligible.py`
- [Describe and diff](https://github.com/yubin-park/hccpy/blob/master/hccpy/hcc.py): `hccpy/hcc.py`
- [HHS profile diff](https://github.com/yubin-park/hccpy/blob/master/hccpy/hhshcc.py): `hccpy/hhshcc.py`

### Other components

- **Package caller**

## Connections

- Package caller → CMS-HCC engine: profiles member
- Package caller → HHS-HCC engine: profiles member
- Package caller → Claim eligibility: checks claims
- CMS-HCC engine → CMS data readers: loads model data
- CMS data readers → CMS model data: reads mappings and factors
- CMS-HCC engine → CMS demographics: derives demographics
- CMS-HCC engine → CMS age-sex edits: edits diagnoses
- CMS-HCC engine → V28 age-sex edits: edits V28 diagnoses
- CMS-HCC engine → HCC hierarchy: applies hierarchy
- CMS-HCC engine → V22 interactions: dispatches V22
- CMS-HCC engine → V23 interactions: dispatches V23
- CMS-HCC engine → CMS interactions: dispatches V24
- CMS-HCC engine → V28 interactions: dispatches V28
- CMS-HCC engine → ESRD interactions: dispatches ESRD
- CMS-HCC engine → CMS coefficients: scores CMS models
- CMS-HCC engine → ESRD coefficients: scores ESRD
- HHS-HCC engine → HHS data readers: loads model data
- HHS data readers → HHS model data: reads mappings and factors
- HHS-HCC engine → HHS demographics: derives demographics
- HHS-HCC engine → HHS age-sex edits: edits diagnoses
- HHS-HCC engine → HHS interactions: creates interactions
- HHS-HCC engine → HHS coefficients: calculates risk score
- Package caller → Describe and diff: describes or compares HCCs
- Package caller → HHS profile diff: compares HHS lists