Merge pull request #3 from timothyhartzog/copilot/gap-analysis-healthcare-finance

Build out healthcare finance modeling toolkit from gap analysis

Author: timothyhartzog

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master", "copilot/**"]
+  pull_request:
+    branches: ["main", "master"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Julia ${{ matrix.julia-version }} — ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ["1.10", "1.11"]
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Julia ${{ matrix.julia-version }}
+        uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - name: Cache Julia packages
+        uses: julia-actions/cache@v2
+
+      - name: Install dependencies
+        uses: julia-actions/julia-buildpkg@v1
+
+      - name: Run tests
+        uses: julia-actions/julia-runtest@v1
+
+      - name: Upload coverage (Codecov)
+        if: matrix.julia-version == '1.10' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: lcov.info
+          fail_ci_if_error: false

Project.toml

@@ -1,14 +1,16 @@
 name = "HealthcareFinance"
 uuid = "6f7d9b44-0d76-4ac4-9b12-8e3f2f5a1001"
 authors = ["Timothy Hartzog"]
-version = "0.1.0"
+version = "0.2.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
@@ -18,3 +20,4 @@ Distributions = "0.25"
 GLM = "1"
 JuMP = "1"
 julia = "1.10"
+

book/chapters/04_financial_analysis.md

@@ -0,0 +1,142 @@
+# Chapter 4: Financial Analysis for Healthcare Organizations
+
+## Learning Objectives
+After completing this chapter, students will be able to:
+1. Construct and interpret hospital income statements using HFMA conventions
+2. Compute and benchmark key financial ratios for health systems
+3. Apply DuPont analysis to decompose return on equity (net assets)
+4. Evaluate financial performance using bond-rating agency frameworks
+
+---
+
+## 4.1 Healthcare Financial Statements
+
+Hospital financial statements differ from those of for-profit corporations in
+important ways:
+
+- **Revenue deductions** (contractual adjustments, charity care, bad debt) are
+  netted against gross charges to arrive at *net patient revenue*
+- **Non-profit status** means equity is replaced by *net assets* (unrestricted,
+  temporarily restricted, permanently restricted) per FASB ASC 958
+- **Community benefit** reporting is required on IRS Form 990, Schedule H
+
+### Net Patient Revenue Waterfall
+
+```
+Gross Charges
+  − Contractual Adjustments     (negotiated write-offs to payers)
+  − Charity Care                (free care at cost to qualifying patients)
+  − Bad Debt                    (uncollectible after good-faith billing)
+= Net Patient Revenue
+  + Other Operating Revenue     (grants, cafeteria, parking, etc.)
+= Total Operating Revenue
+  − Operating Expenses
+= Operating Income (Excess of Revenue over Expenses)
+```
+
+### Julia Example
+
+```julia
+using HealthcareFinance
+
+stmt = income_statement(
+    50_000_000.0,   # gross charges
+    18_000_000.0,   # contractual adjustments
+    500_000.0,      # bad debt
+    1_000_000.0,    # charity care
+    27_000_000.0;   # operating expenses
+    other_income = 500_000.0
+)
+
+println("Net patient revenue: \$", stmt.net_patient_revenue)
+println("Operating margin:    ", round(stmt.total_margin * 100, digits=2), "%")
+```
+
+---
+
+## 4.2 Key Financial Ratios
+
+### Profitability
+| Ratio | Formula | Typical Benchmark |
+|---|---|---|
+| Operating margin | Operating income / Total operating revenue | 2–4% |
+| Total margin | Excess revenue / Total revenue | 3–5% |
+| EBITDA margin | EBITDA / Total operating revenue | 8–12% |
+| Return on assets | Net income / Total assets | 2–4% |
+
+### Liquidity
+| Ratio | Formula | Typical Benchmark |
+|---|---|---|
+| Current ratio | Current assets / Current liabilities | ≥ 2.0 |
+| Days cash on hand | Cash / (Operating expenses / 365) | ≥ 150 days |
+| Days in AR | AR balance / (Net revenue / 365) | ≤ 50 days |
+
+### Leverage (Credit)
+| Ratio | Formula | Moody's A Benchmark |
+|---|---|---|
+| Debt-to-capitalization | LTD / (LTD + Net assets) | < 35% |
+| DSCR | (Income + D&A) / Debt service | ≥ 2.0× |
+| Maximum annual debt service | MADS / Operating revenue | < 3% |
+
+### Julia Example: Balance Sheet Analysis
+
+```julia
+ratios = balance_sheet_ratios(
+    12_000_000.0,   # current assets
+    5_000_000.0,    # current liabilities
+    3_000_000.0,    # cash
+    80_000_000.0,   # total assets
+    45_000_000.0,   # total liabilities
+    35_000_000.0,   # net assets
+    30_000_000.0    # long-term debt
+)
+
+println("Current ratio:    ", round(ratios.current_ratio, digits=2))
+println("D/Cap ratio:      ", round(ratios.long_term_debt_to_capitalization * 100, digits=1), "%")
+dscr = debt_service_coverage_ratio(2_000_000.0, 4_000_000.0, 2_500_000.0)
+println("DSCR:             ", round(dscr, digits=2))
+```
+
+---
+
+## 4.3 DuPont Analysis for Healthcare
+
+The DuPont framework decomposes return on net assets (RONA):
+
+```
+RONA = Net Profit Margin × Asset Turnover × Equity Multiplier
+```
+
+Where:
+- **Net profit margin** = Net income / Revenue
+- **Asset turnover** = Revenue / Total assets
+- **Equity multiplier** = Total assets / Net assets
+
+---
+
+## 4.4 Community Benefit and Non-Profit Accountability
+
+Under IRS Schedule H, non-profit hospitals must quantify:
+1. Financial assistance (charity care at cost)
+2. Unreimbursed Medicaid
+3. Health professions education
+4. Community health improvement services
+5. Research
+
+Industry average is 7–10% of total operating expense.
+
+```julia
+cbr = charitable_community_benefit_rate(7_500_000.0, 100_000_000.0)
+println("Community benefit rate: ", round(cbr * 100, digits=1), "%")
+```
+
+---
+
+## Key Terms
+- **Contractual adjustment**: Write-off of the difference between billed charges and
+  a payer's allowed amount per contract
+- **EBITDA**: Earnings before interest, taxes, depreciation, and amortization — key
+  credit metric used by Moody's, S&P, and Fitch
+- **Days cash on hand**: Liquidity indicator; number of days operations could
+  continue using only available cash and investments
+- **DSCR**: Debt service coverage ratio; measures ability to service debt obligations

book/chapters/05_budgeting.md

@@ -0,0 +1,124 @@
+# Chapter 5: Budgeting and Variance Analysis
+
+## Learning Objectives
+1. Build an operating budget using fixed and variable cost structures
+2. Construct a flexible budget adjusted to actual volume
+3. Decompose total variance into volume, price, efficiency, and mix components
+4. Rank and select capital projects using NPV and strategic scoring
+5. Apply zero-based budgeting to healthcare service lines
+
+---
+
+## 5.1 The Operating Budget
+
+Healthcare budgets integrate clinical activity (volume) with financial targets.
+
+**Basic structure:**
+```
+Revenue = Price × Volume
+Variable Costs = Variable Cost Rate × Volume
+Contribution Margin = Revenue − Variable Costs
+Operating Income = Contribution Margin − Fixed Costs
+```
+
+### Julia Example
+
+```julia
+using HealthcareFinance
+
+# Cardiology clinic: 8,000 visits budgeted at $150/visit
+bud = operating_budget(600_000.0, 45.0, 8_000, 150.0)
+println("Budgeted operating income: \$", bud.operating_income)
+println("Break-even volume: ", break_even_units(600_000.0, 150.0, 45.0), " visits")
+```
+
+---
+
+## 5.2 Flexible Budgeting
+
+A *static budget* is prepared at the start of the period. A *flexible budget*
+adjusts the cost and revenue targets to the actual volume, isolating whether
+variance is from volume or other factors.
+
+```julia
+# Actual volume was 8,800 (10% above budget)
+flex = flex_budget(600_000.0, 45.0, 8_800, 150.0)
+
+# Variance analysis
+vol_var   = volume_variance(150.0 - 45.0, 8_800, 8_000)   # CM × ΔVolume
+price_var = price_variance(148.0, 150.0, 8_800)            # actual price was $148
+
+println("Volume variance (F/U): \$", vol_var)
+println("Price variance (F/U):  \$", price_var)
+```
+
+---
+
+## 5.3 Four-Variance Decomposition
+
+| Variance | Formula | Meaning |
+|---|---|---|
+| **Volume** | Budgeted CM/unit × (Actual − Budgeted volume) | More/fewer encounters |
+| **Price (Rate)** | (Actual price − Budget price) × Actual volume | Revenue per unit |
+| **Efficiency** | Budgeted cost × (Actual inputs − Standard inputs) | Resource productivity |
+| **Mix** | Shift in composition across service lines or payers | Patient/payer mix effect |
+
+Favorable variances increase operating income; unfavorable reduce it.
+
+---
+
+## 5.4 Capital Budgeting
+
+Capital projects in healthcare often require Certificate of Need (CON) approval
+and involve long useful lives (10–30 years for buildings, 5–10 for equipment).
+
+**Decision criteria:**
+1. **NPV > 0**: creates economic value
+2. **IRR > WACC**: returns exceed cost of capital
+3. **DSCR ≥ 1.25**: can service associated debt
+
+```julia
+cfs = [-2_000_000.0, 500_000.0, 600_000.0, 700_000.0, 800_000.0, 600_000.0]
+project_npv = npv(0.07, cfs)
+project_irr = irr(cfs)
+println("NPV:         \$", round(project_npv))
+println("IRR:         ", round(project_irr * 100, digits=2), "%")
+println("PI:          ", profitability_index(project_npv, 2_000_000.0))
+```
+
+### Capital Project Ranking
+
+```julia
+projects = [
+    (name="OR Renovation",    npv=800_000.0,  strategic_score=9.0),
+    (name="MRI Replacement",  npv=600_000.0,  strategic_score=8.0),
+    (name="Parking Structure", npv=200_000.0, strategic_score=4.0),
+    (name="Telehealth Platform", npv=400_000.0, strategic_score=9.5),
+]
+ranked = capital_budget_rank(projects; npv_weight=0.6, strategic_weight=0.4)
+for (i, p) in enumerate(ranked)
+    println("$i. $(p.name): score = $(round(p.composite_score, digits=2))")
+end
+```
+
+---
+
+## 5.5 Zero-Based Budgeting in Healthcare
+
+ZBB requires each budget line item to be justified from scratch each period,
+rather than incrementing prior year. Useful for administrative overhead review.
+
+```julia
+# Score a telehealth program for ZBB approval
+score = zero_based_budget_score(9.0, 8.5, 9.0;
+                                  weights=(0.4, 0.3, 0.3))
+println("ZBB score (0–10): ", round(score, digits=2))
+```
+
+---
+
+## Key Terms
+- **Contribution margin**: Revenue minus variable costs; the amount available to cover fixed costs and generate profit
+- **Flexible budget**: A budget restated at actual volume to isolate non-volume variances
+- **Capital rationing**: Situation where available capital is insufficient to fund all positive-NPV projects
+- **Zero-based budgeting**: Budget methodology requiring justification of all expenditures from zero