documentation.md

# Default Cascade Simulation of Banks 2026

## Overview

Interactive Dash application that simulates the impact of commercial real estate (CRE) defaults on U.S. bank capitalization. The app classifies banks into regulatory categories under two frameworks — Prompt Corrective Action (PCA) based on Tangible Equity Ratio, and Basel III based on Estimated CET1 Ratio — and displays the results as stacked bar charts with summary metric cards.

## How It Works

### CRE Loss Calculation

Each bank's CRE losses are computed as:

- `CRE Losses = CRE Total x Default Rate x LGD`

When the Unrealized Losses toggle is ON, total losses also incorporate unrealized securities losses (positive values in the data, representing the magnitude of losses).

### Tangible Equity Ratio (PCA Framework)

Banks are classified by Adjusted Equity-to-Assets:

- `Adjusted Equity-to-Assets = (Total Equity - CRE Losses - Unrealized Losses) / Total Assets`

PCA categories:

| Category | Threshold |
|----------|-----------|
| Well Capitalized | >= 8% |
| Adequately Capitalized | >= 4% |
| Undercapitalized | >= 2% |
| Critically Undercapitalized | >= 0% |
| Insolvent | < 0% |

### Estimated CET1 Ratio (Basel III Framework)

Banks are also classified by Adjusted CET1 Ratio using an estimated Risk-Weighted Assets figure:

- `Estimated RWA = Total Assets x RWA Ratio`
- `Adjusted CET1 = (CET1 Capital - CRE Losses - Unrealized Losses) / Estimated RWA`

Basel III categories:

| Category | Threshold |
|----------|-----------|
| Well Capitalized | >= 6.5% |
| Undercapitalized | >= 4.5% |
| Below Basel III Minimum | >= 0% |
| Insolvent | < 0% |

## Controls

| Control | Range | Default | Description |
|---------|-------|---------|-------------|
| CRE Default Rate | 0-50% | 10% | Percentage of CRE portfolio that defaults |
| Loss Given Default | 0-100% | 50% | Loss severity on defaulted loans |
| Average RWA Ratio | 50-75% | 65% | Assumed ratio of risk-weighted assets to total assets |
| Total Assets | $10-100B | $10B | Minimum bank size filter |
| Unrealized Losses | ON/OFF | OFF | Include unrealized securities losses in stress calculation |
| Has CRE Losses | ON/OFF | OFF | Exclude banks with zero CRE exposure |
| Publicly Traded Only | ON/OFF | OFF | Exclude non-publicly traded banks |

## Display

### Stacked Bar Charts

Two horizontal stacked bar charts show the count of banks in each capitalization category:

- **Tangible Equity Ratio** — Five-shade red bar (PCA categories)
- **Estimated CET1 Ratio** — Four-shade purple bar (Basel III categories)

### Metric Cards

Each framework displays three summary cards:

| Metric | Description |
|--------|-------------|
| Total Losses | Aggregate CRE losses (plus unrealized if toggled) across all filtered banks, in $B |
| Banks Undercapitalized / Below Minimum | Count of banks falling below the adequately capitalized threshold, with their combined total assets |
| Banks Insolvent | Count of banks with negative adjusted ratios, with their combined total assets |

## Data Source

[The Banking Initiative at Florida Atlantic University](https://business.fau.edu/departments/finance/banking-initiative/) — Q3 2025 FFIEC Call Reports.

## Run Locally

```bash
pip install -r requirements.txt
python app.py
# Open http://localhost:8050
```

## Customization

You can use this app with your own data by replacing the `data.csv` file. Your CSV must include the following columns in the same format:

| Column | Description | Example |
|--------|-------------|---------|
| `Ticker` | Stock ticker symbol (blank for non-public banks) | `JPM` |
| `Name` | Bank name | `JPMORGAN CHASE BANK` |
| `ST` | State abbreviation | `NY` |
| `Total Assets ($M)` | Total assets in millions | `3459261` |
| `Total Equity ($M)` | Total equity in millions | `312794` |
| `CRE Total ($M)` | Commercial real estate exposure in millions | `174381` |
| `CET1 Capital ($M)` | Common Equity Tier 1 capital in millions | `291288` |
| `Total Unrealized Loss ($M)` | Unrealized loss on investment securities in millions (positive values) | `1842` |
| `Price` | Latest stock closing price in dollars | `293.70` |
| `Volume` | Average 30-day trading volume | `44276127` |
| `Volatility` | 30-day annualized volatility as percentage | `26.0` |

Only banks with a non-blank `Ticker` and valid `Price` and `Volatility` values will be included in the simulation. All other columns in the CSV are ignored by this app but may be used by companion apps in the Signalpha suite.