147 lines
6.7 KiB
Python
147 lines
6.7 KiB
Python
"""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)
|
||
"""
|