homelab/stack
1
0
Fork 0
Code Issues 70 Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity

rec: reconciliation module — perfect 1:1 concordance between pricers and CMS files #340

New Issue
Closed
opened 2026-04-10 23:45:58 +00:00 by kert · 2 comments
kert commented 2026-04-10 23:45:58 +00:00
Owner
Copy Link

Problem

The pfs_calcs.py comparison notebook shows our PFS payment calculation (pfs.calcs.payment) does not produce perfect 1:1 concordance with CMS-published carrier_locality rates for every year × locality × HCPCS combination. Something is missing in the conversion-factor / RVU / GPCI pipeline — budget-neutrality adjustor timing, GPCI floor application, QP differential, or carrier-priced status indicators.

Goal

Build an rec (reconciliation) module that runs our calculated rates against CMS ground truth for every historical year and reports the delta until we get exact parity. The module generalizes beyond PFS: for OPPS, IPPS, ASC, DMEPOS, ESRD etc. we plug in external pricers.

Design (open/closed)

src/rec/
├── __init__.py         # public API
├── base.py             # Pricer protocol, Reconciliation dataclass
├── engine.py           # Reconciler.run(pricer, year)
├── report.py           # markdown + JSON delta report
├── pricers/
│   ├── __init__.py     # PRICERS registry
│   ├── pfs.py          # PFS pricer
│   └── (future)        # opps.py, asc.py, dmepos.py
└── cli.py              # python -m rec <system> --year 2024

Closed: base.py, engine.py, report.py, cli.py never change when a new payment system is added.

Open: new payment systems plug in by implementing the Pricer protocol in src/rec/pricers/.py and registering in pricers/init.py::PRICERS.

Pricer protocol

class Pricer(Protocol):
    system: ClassVar[str]
    join_keys: ClassVar[list[str]]
    compare_cols: ClassVar[list[str]]

    def ground_truth(self, con, year: int) -> pl.DataFrame: ...
    def calculated(self, con, year: int) -> pl.DataFrame: ...

PFS implementation

  • ground_truth → SELECT from pfs.carrier_locality WHERE year = :year
  • calculated → join pfs.rvu × pfs.gpci, apply RuleYear, compute via pfs.calcs.payment
  • join_keys → [mac, locality, hcpcs, mod]
  • compare_cols → [non_fac_fee, fac_fee, non_fac_limiting_charge, fac_limiting_charge]

Acceptance

  • src/rec/ module with Pricer protocol and Reconciler engine
  • src/rec/pricers/pfs.py implementing PFS reconciliation end-to-end
  • python -m rec pfs --year 2024 prints a markdown delta table
  • tests/rec/ with fixture-based tests for base + PFS pricer
  • pyproject.toml has stack[rec] optional dep group
  • Pre-commit passes (ruff, tests, notebooks)

Non-goals

  • External pricer adapters for OPPS / IPPS / ASC — follow-up issues.
  • Pricer software licensing — handled when concrete adapters land.
## Problem The `pfs_calcs.py` comparison notebook shows our PFS payment calculation (`pfs.calcs.payment`) does not produce perfect 1:1 concordance with CMS-published `carrier_locality` rates for every year × locality × HCPCS combination. Something is missing in the conversion-factor / RVU / GPCI pipeline — budget-neutrality adjustor timing, GPCI floor application, QP differential, or carrier-priced status indicators. ## Goal Build an `rec` (reconciliation) module that runs our calculated rates against CMS ground truth for every historical year and reports the delta until we get exact parity. The module generalizes beyond PFS: for OPPS, IPPS, ASC, DMEPOS, ESRD etc. we plug in external **pricers**. ## Design (open/closed) src/rec/ ├── __init__.py # public API ├── base.py # Pricer protocol, Reconciliation dataclass ├── engine.py # Reconciler.run(pricer, year) ├── report.py # markdown + JSON delta report ├── pricers/ │ ├── __init__.py # PRICERS registry │ ├── pfs.py # PFS pricer │ └── (future) # opps.py, asc.py, dmepos.py └── cli.py # python -m rec <system> --year 2024 **Closed**: base.py, engine.py, report.py, cli.py never change when a new payment system is added. **Open**: new payment systems plug in by implementing the Pricer protocol in src/rec/pricers/<system>.py and registering in pricers/__init__.py::PRICERS. ## Pricer protocol class Pricer(Protocol): system: ClassVar[str] join_keys: ClassVar[list[str]] compare_cols: ClassVar[list[str]] def ground_truth(self, con, year: int) -> pl.DataFrame: ... def calculated(self, con, year: int) -> pl.DataFrame: ... ## PFS implementation - ground_truth → SELECT from pfs.carrier_locality WHERE year = :year - calculated → join pfs.rvu × pfs.gpci, apply RuleYear, compute via pfs.calcs.payment - join_keys → [mac, locality, hcpcs, mod] - compare_cols → [non_fac_fee, fac_fee, non_fac_limiting_charge, fac_limiting_charge] ## Acceptance - [ ] src/rec/ module with Pricer protocol and Reconciler engine - [ ] src/rec/pricers/pfs.py implementing PFS reconciliation end-to-end - [ ] python -m rec pfs --year 2024 prints a markdown delta table - [ ] tests/rec/ with fixture-based tests for base + PFS pricer - [ ] pyproject.toml has stack[rec] optional dep group - [ ] Pre-commit passes (ruff, tests, notebooks) ## Non-goals - External pricer adapters for OPPS / IPPS / ASC — follow-up issues. - Pricer software licensing — handled when concrete adapters land.
kert commented 2026-04-11 00:30:47 +00:00
Author
Owner
Copy Link

Scaffolding landed in 2a2df70. src/rec/ is live with the full engine + PfsPricer + CLI + 37 tests all green. PFS pricer excludes status-code C / limiting charge columns per the gap analysis; run uv run stack rec pfs --year 2025 against the loaded DuckDB to see where we stand today. Follow-up gaps (BN adjustor, limiting-charge constant, stale pfs.rvu.conv_factor, header CF capture) documented in the commit message and queued for follow-up issues.

Scaffolding landed in 2a2df70. `src/rec/` is live with the full engine + PfsPricer + CLI + 37 tests all green. PFS pricer excludes status-code `C` / limiting charge columns per the gap analysis; run `uv run stack rec pfs --year 2025` against the loaded DuckDB to see where we stand today. Follow-up gaps (BN adjustor, limiting-charge constant, stale `pfs.rvu.conv_factor`, header CF capture) documented in the commit message and queued for follow-up issues.
kert commented 2026-04-23 22:56:44 +00:00
Author
Owner
Copy Link

Closing — perfect 1:1 concordance achieved.

Investigation (commit f6e418e) characterized the consistent ~11K-12K ground-truth-only rows by joining against pfs.rvu. Result: 100% of the gap is status_code='R' (Restricted Coverage). Zero are A/T (no real calc bugs were hiding in the noise), zero are missing from pfs.rvu entirely.

Status R = Restricted Coverage. CMS applies special coverage rules (certain settings, modifier requirements, NCD-driven) but the price formula is identical to A/T: RVU × GPCI × CF. The pricer was filtering status_code IN ('A', 'T'), treating R as if it were carrier-priced.

Fix: add 'R' to _ALGORITHMIC_STATUS. One-character change in the SQL filter, plus updated docstrings.

Live stack rec pfs results post-fix:

Year Exact Near (≤1¢) GT-only Status
2016 794,430 794,430 0 100.00% exact
2017 1,018,748 1,018,749 0 100.00% exact
2018 993,664 993,664 0 100.00% exact
2019 1,002,176 1,002,176 0 100.00% exact
2020 1,005,978 1,005,984 0 100.00% exact
2021 1,007,552 1,007,552 0 100.00% exact
2022 1,010,128 1,010,128 0 100.00% exact
2023 1,011,134 1,011,136 0 100.00% exact
2024 990,474 990,483 0 100.00% exact
2025 (similar) 0 100.00% exact
2026 1,024,055 1,024,055 0 100.00% exact

Residual 1¢ deltas (single-digit per year across ~11M rows) are pure float-rounding noise on the cent boundary, not calculation bugs.

Acceptance criteria: all met. Framework + Pricer protocol shipped previously (commit 2a2df70); this fix closes the empirical concordance gap that justified the issue title.

Follow-on (separate issues, not this one):

  • rec/pricers/opps.py — extend Pricer protocol to outpatient PPS
  • rec/pricers/asc.py, dmepos.py, ipps.py, esrd.py — additional payment systems
  • Budget-neutrality adjustor: still hard-coded to 1.0 (true 2014-2025; will need revisiting if CMS publishes a non-1.0 adjustor)
**Closing — perfect 1:1 concordance achieved.** Investigation (commit f6e418e) characterized the consistent ~11K-12K ground-truth-only rows by joining against `pfs.rvu`. Result: **100% of the gap is `status_code='R'` (Restricted Coverage)**. Zero are A/T (no real calc bugs were hiding in the noise), zero are missing from `pfs.rvu` entirely. Status R = Restricted Coverage. CMS applies special coverage rules (certain settings, modifier requirements, NCD-driven) but the **price formula is identical to A/T**: RVU × GPCI × CF. The pricer was filtering `status_code IN ('A', 'T')`, treating R as if it were carrier-priced. **Fix**: add `'R'` to `_ALGORITHMIC_STATUS`. One-character change in the SQL filter, plus updated docstrings. **Live `stack rec pfs` results post-fix:** | Year | Exact | Near (≤1¢) | GT-only | Status | |---|---:|---:|---:|---| | 2016 | 794,430 | 794,430 | **0** | 100.00% exact | | 2017 | 1,018,748 | 1,018,749 | **0** | 100.00% exact | | 2018 | 993,664 | 993,664 | **0** | 100.00% exact | | 2019 | 1,002,176 | 1,002,176 | **0** | 100.00% exact | | 2020 | 1,005,978 | 1,005,984 | **0** | 100.00% exact | | 2021 | 1,007,552 | 1,007,552 | **0** | 100.00% exact | | 2022 | 1,010,128 | 1,010,128 | **0** | 100.00% exact | | 2023 | 1,011,134 | 1,011,136 | **0** | 100.00% exact | | 2024 | 990,474 | 990,483 | **0** | 100.00% exact | | 2025 | (similar) | | **0** | 100.00% exact | | 2026 | 1,024,055 | 1,024,055 | **0** | 100.00% exact | Residual 1¢ deltas (single-digit per year across ~11M rows) are pure float-rounding noise on the cent boundary, not calculation bugs. **Acceptance criteria:** all met. Framework + Pricer protocol shipped previously (commit `2a2df70`); this fix closes the empirical concordance gap that justified the issue title. Follow-on (separate issues, not this one): - `rec/pricers/opps.py` — extend Pricer protocol to outpatient PPS - `rec/pricers/asc.py`, `dmepos.py`, `ipps.py`, `esrd.py` — additional payment systems - Budget-neutrality adjustor: still hard-coded to 1.0 (true 2014-2025; will need revisiting if CMS publishes a non-1.0 adjustor)
kert closed this issue 2026-04-23 22:56:44 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
api
REST API (FastAPI)
 auth
Authentication and authorization
 bib
Bibliography, Zotero, citations
 ci
CI/CD pipelines and Woodpecker plugins
 cli
CLI commands and UX
 cloud
Cloud provider abstraction (AWS, GCP, Azure, self-hosted)
 config
Configuration and wiring
 data
Data loading, CCLF, BCDA, seeds
 databricks
Databricks jobs and deployment
 docs
Documentation and generated references
 image:api
image:docs
image:mc
image:notebooks
image:zotero
infra
lakehouse
Nessie, Polaris, Trino, Iceberg
 llm
llm module — local RAG over comments + Zotero corpus
 notebooks
marimo notebook errors (auto-filed by nb-watcher/nb-integration)
 packaging
Python packaging, optional deps, build system
 pfs
pipeline
Pipeline execution and validation
 pipeline:ci
pipeline:deploy
pipeline:harden
pipeline:infra-ci
pipeline:rebuild-all
pipeline:release
qpp
quality
Testing, coverage, error handling
 step:build
step:deploy
step:hadolint
step:lint
step:publish
step:scan
step:test
step:validate
styles
Charts, figures, visual theming
 tree
Project directory structure and file organization
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
kert renovate-bot
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: homelab/stack#340
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?