data: Medicare Physician & Other Practitioners PUF ingest — utilization and allowed amounts per HCPCS, 2013– #694

New Issue

kert · 2026-09-09T14:30:05Z

kert commented

2026-09-09 14:30:05 +00:00

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (§P50).

The direct outcome for a code becoming payable is whether anyone bills it. Ingest the CMS Medicare Physician & Other Practitioners by Provider and Service PUF (annual, 2013–) into pfs.utilization(year, hcpcs, place_of_service, n_providers, n_services, n_beneficiaries, avg_allowed, avg_paid), cite the dataset in bib (source:cms-website, table:pfs.utilization, year: tags), and join to the exposure calendar.

First questions it must answer: services billed for 99490 per year 2015–2024; G2058 → 99439 continuity in 2020–2021; APCM uptake 2025 vs CCM decline. Done when those three series plot from the table with provenance.

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (§P50). The direct outcome for a code becoming payable is whether anyone bills it. Ingest the CMS Medicare Physician & Other Practitioners by Provider and Service PUF (annual, 2013–) into `pfs.utilization(year, hcpcs, place_of_service, n_providers, n_services, n_beneficiaries, avg_allowed, avg_paid)`, cite the dataset in bib (`source:cms-website`, `table:pfs.utilization`, `year:` tags), and join to the exposure calendar. First questions it must answer: services billed for 99490 per year 2015–2024; G2058 → 99439 continuity in 2020–2021; APCM uptake 2025 vs CCM decline. Done when those three series plot from the table with provenance.

kert added this to the P50: Legal epidemiology — outcome series around code-family events (utilization, BLS wages, industry markets) milestone 2026-09-09 14:30:05 +00:00

kert added the bib data labels 2026-09-09 14:30:05 +00:00

kert referenced this issue from a commit

2026-09-22 20:05:34 +00:00

feat(pfs): Part B utilization per HCPCS — pfs.utilization from the CMS by-Geography-and-Service PUFs, stack pfs utilization, notebook 7d/7e (refs #694)

kert referenced this issue from a commit

2026-09-22 20:05:34 +00:00

merge: #694 — Part B utilization per HCPCS: pfs.utilization, stack pfs utilization, notebook 7d/7e (refs #694)

kert commented

2026-09-22 20:15:42 +00:00

Merged to main as 592ad3c (feature commit 4c69d5b) and ingested the same day.

What landed

pfs.utilization (pfs/table/utilization.py model; writer/reader in pfs/utilization.py): one row per (year, hcpcs, place_of_service) with providers, beneficiaries, services, beneficiary-day services, average submitted / allowed / paid / standardized amounts, plus dataset_id (the year's data.cms.gov UUID) and item_key (the bib Source citing it). Source is the CMS Medicare Physician & Other Practitioners — by Geography and Service PUF, national rows only — ~13k a year, so the whole 2013–2024 run is 156k rows and fetches in about 10 s through the Data API (filter[Rndrng_Prvdr_Geo_Lvl]=National, 5,000-row pages).
Provenance: raw pages cached at data/cms/utilization/mup-phy-geo-<year>.json; one bib Source per year tagged module:pfs, table:pfs.utilization, source:cms-website, year:<year> (keys 67XAAK6M … UJCVPVE2); a cms.ingest_log row per year with the cache file's sha256 and the bib key as pincite_key. Suppressed cells (<11 beneficiaries) load as NULL, never 0.
stack pfs utilization [--year N]... [--write [--offline]] [--code C]... — fetch/cite/log/republish, or print a code's per-year series (places of service summed, allowed/paid service-weighted).
Notebook code_families.py: 7d charts the selected family's services per year with the 7c exposure dates as rules; 7e answers this issue's three questions; provenance counts include the table.

The three series (from the live table):

99490 services per year: 2015 996k → 2016 2.44M → 2017 3.39M → 2018 4.15M → 2019 4.32M → 2020 4.76M → 2021 4.48M → 2022 4.74M → 2023 5.86M → 2024 6.92M (beneficiaries 292k → 1.38M; avg allowed steps from ~$40 to ~$60 with the CY2022 revaluation the exposure calendar dates 2022-01-01).
G2058 → 99439 continuity: G2058 567k services / 204k beneficiaries in 2020 (its only year); 99439 836k / 241k in 2021, then 1.28M, 2.20M, 3.11M through 2024 — the add-on carried over and kept growing.
APCM 2025 vs CCM: not answerable yet — the newest Geography-and-Service file covers calendar 2024, and G0556–G0558 became payable 2025-01-01, so the table has no APCM rows. Notebook 7e says so instead of plotting zeros; re-run stack pfs utilization --write --year 2025 when CMS publishes the 2025 file (add its UUID to DATASETS).

Tests: 12 unit (tests/pfs/test_utilization.py), 5 CLI, notebook structure + live run green; pre-commit suites (cli, pfs, notebooks) passed.

**Merged to main as 592ad3c** (feature commit 4c69d5b) and ingested the same day. **What landed** - `pfs.utilization` (`pfs/table/utilization.py` model; writer/reader in `pfs/utilization.py`): one row per (year, hcpcs, place_of_service) with providers, beneficiaries, services, beneficiary-day services, average submitted / allowed / paid / standardized amounts, plus `dataset_id` (the year's data.cms.gov UUID) and `item_key` (the bib Source citing it). Source is the CMS *Medicare Physician & Other Practitioners — by Geography and Service* PUF, national rows only — ~13k a year, so the whole 2013–2024 run is 156k rows and fetches in about 10 s through the Data API (`filter[Rndrng_Prvdr_Geo_Lvl]=National`, 5,000-row pages). - Provenance: raw pages cached at `data/cms/utilization/mup-phy-geo-<year>.json`; one bib Source per year tagged `module:pfs`, `table:pfs.utilization`, `source:cms-website`, `year:<year>` (keys 67XAAK6M … UJCVPVE2); a `cms.ingest_log` row per year with the cache file's sha256 and the bib key as `pincite_key`. Suppressed cells (<11 beneficiaries) load as NULL, never 0. - `stack pfs utilization [--year N]... [--write [--offline]] [--code C]...` — fetch/cite/log/republish, or print a code's per-year series (places of service summed, allowed/paid service-weighted). - Notebook `code_families.py`: 7d charts the selected family's services per year with the 7c exposure dates as rules; 7e answers this issue's three questions; provenance counts include the table. **The three series** (from the live table): 1. 99490 services per year: 2015 996k → 2016 2.44M → 2017 3.39M → 2018 4.15M → 2019 4.32M → 2020 4.76M → 2021 4.48M → 2022 4.74M → 2023 5.86M → 2024 6.92M (beneficiaries 292k → 1.38M; avg allowed steps from ~$40 to ~$60 with the CY2022 revaluation the exposure calendar dates 2022-01-01). 2. G2058 → 99439 continuity: G2058 567k services / 204k beneficiaries in 2020 (its only year); 99439 836k / 241k in 2021, then 1.28M, 2.20M, 3.11M through 2024 — the add-on carried over and kept growing. 3. APCM 2025 vs CCM: **not answerable yet** — the newest Geography-and-Service file covers calendar 2024, and G0556–G0558 became payable 2025-01-01, so the table has no APCM rows. Notebook 7e says so instead of plotting zeros; re-run `stack pfs utilization --write --year 2025` when CMS publishes the 2025 file (add its UUID to `DATASETS`). Tests: 12 unit (`tests/pfs/test_utilization.py`), 5 CLI, notebook structure + live run green; pre-commit suites (cli, pfs, notebooks) passed.

kert closed this issue

2026-09-22 20:15:42 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: homelab/stack#694