Files
stack/src/pfs/__init__.py
2026-02-07 16:18:44 -05:00

147 lines
6.7 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""pfs — Physician Fee Schedule data models, ingestion, and calculations.
Ingests CMS Physician Fee Schedule data files (RVU files, direct PE
inputs, GPCIs, carrier payment files, and annual rule addenda) into
clean narwhals DataFrames. Provides calculation functions for RVU-based
payment, practice expense valuation, and time-intensity analysis.
Architecture
------------
``pfs`` is a peer module to ``aco``, ``ccw``, and ``rex``. It follows
the same SQLTable model pattern as ``ccw.table`` and uses ``rex`` for
file parsing where mainframe artifacts are present.
::
CMS Downloads (ZIP → CSV/Excel)
│
▼
┌───────┐
│ pfs │ files → table → calcs → rules
└───────┘
│
▼ narwhals DataFrames
┌───────┐
│ aco │ input_layer / core / analytics
└───────┘
Submodules
----------
``pfs.table``
Pydantic ``SQLTable`` models for every CMS PFS data entity:
RVU file, clinical labor, medical supplies, medical equipment,
GPCIs, carrier payments, physician work time, and annual
addenda tables.
``pfs.files``
``rex.Format`` and ``rex.Sieve`` definitions for each CMS file
type. Maps raw CMS column names to ``pfs.table`` field names,
handles quarterly release naming conventions (``RVUyyA`` through
``RVUyyD``), ZIP extraction, and encoding quirks.
``pfs.calcs``
``@nw.narwhalify`` expression functions for:
- Payment calculation (Work + PE + MP RVUs × GPCIs × CF)
- Direct PE cost build-up (labor + supply + equipment)
- Time-intensity ratios and comparison cohort analysis
- Budget-neutrality adjustments
- Multiple Procedure Payment Reduction (MPPR)
``pfs.rules``
Annual rule parameters: conversion factors, budget-neutrality
adjustors, GPCI floor policies, telehealth code lists, and
phase-in schedules. One ``RuleYear`` model per calendar year
(2010–2026) with all parameters needed to reproduce CMS's
published payment amounts.
CMS Data Files
--------------
Six core file families, all keyed on HCPCS/CPT code:
::
┌─────────────────────────────────────────────────────────────────┐
│ File Family │ Release │ Format │ Key Columns │
├─────────────────────────────────────────────────────────────────┤
│ RVU (National) │ Quarterly│ CSV/ZIP │ HCPCS, MOD, │
│ RVUyyA–D.zip │ Jan→Oct │ │ Work/PE/MP RVU, │
│ │ │ │ Status, Global, │
│ │ │ │ CF │
├─────────────────────────────────────────────────────────────────┤
│ Clinical Labor │ Annual │ CSV/XLSX │ HCPCS, activity, │
│ (Direct PE input) │ w/ rule │ │ NF/F minutes, │
│ │ │ │ rate/min │
├─────────────────────────────────────────────────────────────────┤
│ Medical Supplies │ Annual │ CSV/XLSX │ HCPCS, item, │
│ (Direct PE input) │ w/ rule │ │ NF/F quantity, │
│ │ │ │ price │
├─────────────────────────────────────────────────────────────────┤
│ Medical Equipment │ Annual │ CSV/XLSX │ HCPCS, item, │
│ (Direct PE input) │ w/ rule │ │ NF/F minutes, │
│ │ │ │ price, life, mins │
├─────────────────────────────────────────────────────────────────┤
│ GPCIs │ Annual │ CSV │ Locality, │
│ (Geographic) │ w/ RVU │ │ Work/PE/MP GPCI │
├─────────────────────────────────────────────────────────────────┤
│ Carrier Payments │ Annual │ CSV/ZIP │ Locality, HCPCS, │
│ (Locality $) │ │ │ MOD, NF/F fee │
└─────────────────────────────────────────────────────────────────┘
Additionally, the annual Final Rule publishes 20+ addenda files
(Addenda A–E, analytic crosswalks, utilization data, specialty
impacts, telehealth lists, etc.). These are modeled in
``pfs.table.addendum`` and parsed via ``pfs.files``.
Payment Formula
---------------
::
Payment = [(Work_RVU × Work_GPCI)
+ (PE_RVU × PE_GPCI)
+ (MP_RVU × MP_GPCI)]
× Conversion_Factor
Where PE_RVU is either facility or non-facility depending on
place of service. The conversion factor is set annually in the
Final Rule (e.g. $32.3465 for CY2026).
Practice Expense Valuation
--------------------------
Direct PE for a given HCPCS code:
::
Direct_PE = Labor_Cost + Supply_Cost + Equipment_Cost
Labor_Cost = Σ (minutes × rate_per_minute) over all activities
Supply_Cost = Σ (quantity × price) over all supply items
Equipment_Cost = Σ ((price / life / mins_yr) × time) over all equip
Indirect PE is allocated from specialty-level practice cost
surveys, proportional to direct PE and physician work.
Usage
-----
::
from pfs.table import Rvu, ClinicalLabor, MedicalSupply
from pfs.calcs import payment, direct_pe_cost
from pfs.rules import cy2026
# Load RVU data
rvu_df = ... # from rex.extract or DuckDB
# Calculate payment for a locality
paid = payment(rvu=rvu_df, gpci=gpci_df)
# Build up direct PE costs
pe = direct_pe_cost(labor=labor_df, supply=supply_df, equipment=equip_df)
"""