---
name: Economic Forecast & Portfolio Impact Expert
description: Economic forecast, recession risk, stress test, portfolio impact, probability engine, Markov chain, Monte Carlo, interest rate impact, housing affordability, CPI, inflation, unemployment, FRED, counter-cyclical, scenario planning, liquidity.
---

# Economic Forecast & Portfolio Impact Expert

This skill provides deep reference knowledge for the Sunrise Probability Engine, macroeconomic analysis, and portfolio-level impact forecasting for manufactured housing communities. It covers the three-layer Markov chain model, FRED API integration, property cluster assignments, interest rate and household liquidity modifiers, stress testing methodology, recession analysis, housing affordability dynamics, and calibration governance. All economic thresholds and model parameters reflect the production codebase as of March 2026. FRED series recommendations were researched from official St. Louis Fed documentation. Academic and industry claims should be re-verified against primary sources for board-level materials.

---

## Table of Contents

1. [Sunrise Probability Engine](#sunrise-probability-engine)
2. [Property Cluster Framework](#property-cluster-framework)
3. [Economic Indicator Deep Dive](#economic-indicator-deep-dive)
4. [FRED API Integration](#fred-api-integration)
5. [Recession Analysis](#recession-analysis)
6. [Stress Testing Methodology](#stress-testing-methodology)
7. [Scenario Planning](#scenario-planning)
8. [Interest Rate Impact Analysis](#interest-rate-impact-analysis)
9. [Housing Affordability Connection](#housing-affordability-connection)
10. [Regional Economic Analysis](#regional-economic-analysis)
11. [Inflation and Expense Impact](#inflation-and-expense-impact)
12. [Decision Trees](#decision-trees)
13. [Common Gotchas](#common-gotchas)
14. [Procedures](#procedures)
15. [Output Formats](#output-formats)
16. [References](#references)

---

## Sunrise Probability Engine

### Architecture Overview

The Probability Engine is a three-layer forecasting model that translates macroeconomic conditions into property-level occupancy impact projections. It outputs to the `Economic_Forecast` tab in the Strategic KPI Google Sheet on a quarterly cadence.

**Three Layers:**

| Layer | Name | Input | Output |
|-------|------|-------|--------|
| **Layer 1: Macro** | Economic Regime Markov Chain | 35+ years FRED UNRATE data | State probabilities (5 states) |
| **Layer 2: Micro** | Property Response Probabilities | Regime + cluster assignment | Expected monthly occupancy delta |
| **Layer 3: Modifier** | Interest Rate + Household Liquidity | MORTGAGE30US + PSAVERT | Multiplicative adjustment (0.6x-1.6x) |

**Key Design Decisions:**
- Markov property (memoryless): Future state depends only on current state, not history. This is a deliberate simplification. Real economic cycles have momentum, but Markov chains capture the dominant transition patterns with far less complexity than ARIMA or VAR models.
- 3-month lag between economic state and occupancy impact. Derived from Phase 1 correlation analysis showing that unemployment changes take roughly one quarter to manifest as occupancy changes in MHP portfolios.
- Laplace smoothing (alpha=0.1) on transition matrices prevents zero-probability transitions. This is critical because rare transitions (e.g., Expansion directly to Trough) have happened historically but would be assigned zero probability without smoothing.

### Five Economic States

The model uses a 5-state regime classification, an upgrade from the original 3-state model recommended by the Gemini auditor (2026-01-08).

| State | Unemployment Level | 3-Month Change | Typical Duration | Historical Frequency |
|-------|--------------------|----------------|------------------|---------------------|
| **EXPANSION** | <= 4.5% | < +0.3% | 3-7 years | ~60% of months since 1990 |
| **SLOWDOWN** | <= 4.5% but rising | >= +0.3% | 6-18 months | ~10% of months |
| **RECESSION** | > 6.0% | >= +0.3% | 6-18 months | ~8% of months |
| **TROUGH** | > 6.0% | Stable (< 0.3%) | 2-4 months | ~5% of months |
| **RECOVERY** | Any level | <= -0.3% | 6-12 months | ~17% of months |

**Classification Logic (from `classify_state()`):**
```
IF unemployment > 6.0%:
    IF 3mo_change >= +0.3%  -> RECESSION
    IF 3mo_change <= -0.3%  -> RECOVERY
    ELSE                    -> TROUGH
ELSE:
    IF 3mo_change >= +0.3%  -> SLOWDOWN
    IF 3mo_change <= -0.3%  -> RECOVERY
    ELSE                    -> EXPANSION
```

**Key thresholds (calibrated values in production):**
- `LOW_UNEMPLOYMENT = 4.5%` -- Below this is expansion territory
- `HIGH_UNEMPLOYMENT = 6.0%` -- Above this is recession territory
- `SIGNIFICANT_CHANGE = 0.3%` -- 3-month change threshold for rising/falling

### Transition Matrix

The transition matrix is a 5x5 row-stochastic matrix built from historical FRED data (1990-present). Each row sums to 1.0. The matrix captures observed month-to-month state transitions with Laplace smoothing.

**Representative Transition Probabilities (monthly, from 35 years of data):**

| From / To | EXPANSION | SLOWDOWN | RECESSION | TROUGH | RECOVERY |
|-----------|-----------|----------|-----------|--------|----------|
| EXPANSION | ~92% | ~8% | ~0% | ~0% | ~0% |
| SLOWDOWN | ~30% | ~50% | ~20% | ~0% | ~0% |
| RECESSION | ~0% | ~0% | ~70% | ~30% | ~0% |
| TROUGH | ~0% | ~0% | ~0% | ~30% | ~70% |
| RECOVERY | ~50% | ~0% | ~0% | ~0% | ~50% |

**Reading the matrix:**
- From EXPANSION, there is a ~92% probability of staying in EXPANSION next month and ~8% of transitioning to SLOWDOWN.
- RECESSION is a "sticky" state -- 70% probability of remaining in recession month-over-month, reflecting that recessions typically last 6-18 months.
- TROUGH is the gateway to recovery -- 70% probability of transitioning to RECOVERY reflects the historical pattern that once unemployment stabilizes at its peak, it begins falling.

**Forecasting with the matrix:**
The model forecasts N-month-ahead state probabilities using matrix exponentiation: `P(n) = initial_distribution @ T^n` where T is the transition matrix. This produces a probability distribution over all 5 states at each future month.

### Calibration History

| Date | Change | Trigger |
|------|--------|---------|
| 2025-12-31 | Initial 5-state model built | Phase 2 launch |
| 2026-01-08 | Gemini audit: upgraded from 3 to 5 states; Kimi-K2 audit: fixed lag calculation, added Laplace smoothing | Dual auditor review |
| 2026-01-20 | Added Layer 3 (interest rate modifier + household liquidity); calibrated rate thresholds after backtest (LOW: 5.0->4.5, HIGH: 7.0->6.0) | Backtest validation |
| 2026-01-20 | Model validation framework built (`validate_model_vs_actual.py`) | Production readiness |

### How Forecasting Works End-to-End

1. **Fetch data**: Pull UNRATE, MORTGAGE30US, and PSAVERT from FRED API
2. **Build state histories**: Classify each historical month into economic state, rate environment, and liquidity environment
3. **Build transition matrices**: Count state-to-state transitions, normalize with Laplace smoothing
4. **Identify current state**: Classify the most recent month
5. **Forecast forward**: Use matrix exponentiation to get state probabilities for each of the next 12 months
6. **Apply lag**: For month T in the forecast, use the state distribution from month T-3 (the 3-month lag)
7. **Calculate cluster impacts**: For each cluster, compute expected occupancy delta weighted by state probabilities
8. **Apply modifiers**: Multiply by rate modifier and liquidity modifier (composite, capped at 2.0x)
9. **Aggregate**: Weight cluster impacts by property count to get portfolio-level forecast
10. **Generate recommendations**: Trigger-based action items based on stress thresholds

---

## Property Cluster Framework

### Assignment Methodology

Property clusters were determined in Phase 1 through correlation analysis of each property's historical occupancy against state-level unemployment. The analysis examined 12-24 months of occupancy data from RentManager against FRED state unemployment series.

**Correlation Interpretation:**
- **Negative correlation** (unemployment up, occupancy up) = RESILIENT (counter-cyclical)
- **Positive correlation** (unemployment up, occupancy down) = SENSITIVE (pro-cyclical)
- **Near-zero correlation** = NEUTRAL (uncorrelated)

**Confidence Levels:**
- **HIGH**: Strong correlation signal (|r| > 0.3) with statistically significant p-value
- **MODERATE**: Directionally consistent but weaker correlation or shorter data history
- **UNKNOWN**: New acquisitions or properties with insufficient data

### Current Assignments (Production)

**RESILIENT Cluster (7 properties) -- Counter-cyclical:**

| Property | State | Confidence | Rationale |
|----------|-------|------------|-----------|
| Darby View (OHME Darby MHP, LLC) | OH | HIGH | Strong negative unemployment correlation |
| Ridgebrook Hills (SCI RIDGEBROOK HILLS LLC) | IN | HIGH | Strong negative unemployment correlation |
| Silver Terrace Manor (SCI STM, LLC) | OH | HIGH | Strong negative unemployment correlation |
| Walston (WALSTON MHP, LLC) | MD | HIGH | Strong negative unemployment correlation |
| Bellecrest (SCI BELLECREST MHP LLC) | MS | MODERATE | Directionally consistent, shorter history |
| MNL (SCI MNL, LLC) | OH | MODERATE | Directionally consistent |
| Lakeridge Estates (SCI LAKERIDGE ESTATES LLC) | OH | MODERATE | Directionally consistent |

*Behavioral thesis: These properties see occupancy INCREASE during recessions as people downsize from apartments and site-built homes into manufactured housing. The "move-down" effect is strongest in communities with lower lot rents and proximity to employment centers.*

**SENSITIVE Cluster (7 properties) -- Pro-cyclical:**

| Property | State | Confidence | Rationale |
|----------|-------|------------|-----------|
| Sherman Estates (SCI SHERMAN ESTATES MHP LLC) | KY | HIGH | Strong positive unemployment correlation |
| Mancuso Village (SCI MANCUSO VILLAGE LLC) | IL | HIGH | Strong positive unemployment correlation |
| Rolling Meadows (SCI ROLLING MEADOWS LLC) | IL | HIGH | Strong positive unemployment correlation |
| Timberview (SCI TIMBERVIEW MHP, LLC) | GA | MODERATE | Directionally consistent |
| Dutch Gardens (SCI DUTCH GARDENS MHP LLC) | GA | MODERATE | Directionally consistent |
| Miami Village (SCI MIAMI VILLAGE LLC) | IN | MODERATE | Directionally consistent |
| Park Estates (SCI PARK ESTATES MHP LLC) | MN | MODERATE | Directionally consistent |

*Behavioral thesis: These properties have residents more vulnerable to job loss and income reduction. Tenant base may include single-income households, hourly workers, or residents with thinner financial buffers. Occupancy drops during downturns as residents double up, leave, or face eviction.*

**NEUTRAL Cluster (4 properties) -- Uncorrelated:**

| Property | State | Notes |
|----------|-------|-------|
| Elk Creek (SCI ELK CREEK MHP LLC) | KY | Outlier -- KY property with positive correlation but classified neutral |
| Tilghman (SCI TILGHMAN MHP LLC) | MD | Near-zero correlation |
| APE (SCI APE MHP LLC) | MI | Near-zero correlation |
| Cedarhurst (CEDARHURST MHP, LLC) | MD | Near-zero correlation |

*Behavioral thesis: Occupancy driven primarily by local factors (property condition, management quality, local competition) rather than macroeconomic conditions. Monitor for reclassification as more data accumulates.*

### Occupancy Impact by State and Cluster

The Layer 2 model uses a probabilistic response distribution, not a single point estimate. Each (EconomicState, ClusterType) combination has a probability distribution over five impact levels:

**Impact Level Definitions:**
| Impact Level | Monthly Occupancy Delta | Description |
|-------------|------------------------|-------------|
| significant_gain | +3.0% | Strong demand surge |
| slight_gain | +1.0% | Moderate demand increase |
| stable | 0.0% | No change |
| slight_loss | -1.0% | Moderate demand decrease |
| significant_loss | -3.0% | Severe demand drop |

**Expected Monthly Impact (weighted average across probability distribution):**

| Economic State | RESILIENT | SENSITIVE | NEUTRAL |
|----------------|-----------|-----------|---------|
| EXPANSION | +0.10% | +0.10% | 0.00% |
| SLOWDOWN | +0.20% | -0.55% | -0.10% |
| RECESSION | +1.15% | -1.60% | -0.20% |
| TROUGH | +0.55% | -0.85% | -0.20% |
| RECOVERY | +0.20% | +0.10% | +0.10% |

**Reading the table:** During RECESSION, Resilient properties gain an expected +1.15% occupancy per month while Sensitive properties lose -1.60% per month. Over a 12-month recession, this compounds to roughly +14% vs -19% -- a 33 percentage point divergence that represents the portfolio's "natural hedge."

### Cumulative Impact Calculation

The 12-month cumulative forecast is NOT simply "monthly impact x 12." It accounts for changing state probabilities over time:

```
12-Month Impact = SUM over months 1-12 of:
    SUM over states of:
        P(state at month T-3) * expected_impact(state, cluster) * composite_modifier
```

The 3-month lag means months 1-3 of the forecast reflect the CURRENT known state (since T-3 for T=1,2,3 maps to T=0 or earlier, which is the known present).

### Natural Hedge Effect

The Sunrise portfolio has a structural hedge: 7 Resilient properties offset losses from 7 Sensitive properties during downturns. The 4 Neutral properties provide ballast.

**Portfolio-weighted impact in recession scenario:**
- Resilient (7/18 = 39% weight): +1.15% * 39% = +0.45%
- Sensitive (7/18 = 39% weight): -1.60% * 39% = -0.62%
- Neutral (4/18 = 22% weight): -0.20% * 22% = -0.04%
- **Net portfolio monthly impact: -0.21%**

This means even during a recession, the portfolio's monthly occupancy erosion is only about 0.2% -- far less than the 1.6% that Sensitive properties alone would experience. Over 12 months, the net portfolio impact is roughly -2.5% vs the -19% that a purely Sensitive portfolio would suffer.

---

## Economic Indicator Deep Dive

### Leading Indicators (Signal 6-18 Months Ahead)

These indicators move BEFORE the economy changes state. They are the primary inputs for assessing transition risk.

| Indicator | FRED Series | Signal Thresholds | Lead Time | Relevance to MHP |
|-----------|-------------|-------------------|-----------|-----------------|
| **Yield Curve (10Y-2Y)** | T10Y2Y | Inversion (<0) -> recession in 12-18mo; Re-steepening after inversion -> recession imminent | 12-18 months | Predicts rate environment shift; historically preceded every recession since 1955 |
| **Initial Jobless Claims** | ICSA | >300K sustained -> Slowdown; >400K -> Recession signal | 3-6 months | Direct proxy for job losses affecting MHP tenants |
| **Consumer Confidence** | UMCSENT | <80 -> Caution; <60 -> Recession territory | 3-9 months | Predicts consumer spending pullback; residents defer home purchases |
| **PMI Manufacturing** | (ISM, not on FRED) | <50 -> Contraction; <45 -> Severe contraction | 3-6 months | Critical for Midwest MHP markets dependent on manufacturing |
| **Building Permits** | PERMIT | YoY decline >15% -> Housing slowdown | 6-12 months | Reduced new construction = less competition for MHPs |
| **Sahm Rule** | SAHMREALTIME | >0.50 -> Recession signal triggered | Real-time | The most reliable real-time recession indicator; 3mo avg unemployment rise vs 12mo low |
| **Conference Board LEI** | (not directly on FRED) | 6 consecutive monthly declines -> Recession warning | 6-12 months | Composite of 10 leading indicators |
| **Personal Savings Rate** | PSAVERT | <3% -> Depleted household buffers | 3-6 months | Direct input to Layer 3 liquidity modifier |

**Yield Curve Deep Dive:**
The 10Y-2Y Treasury spread (T10Y2Y) has inverted before every recession since 1955 with a lead time of 12-18 months. However, the 2022-2024 inversion lasted nearly two years without producing a recession, the longest such inversion since 1978. The critical signal is NOT the initial inversion but the RE-STEEPENING that follows, which typically coincides with the Fed cutting rates in response to weakening data. Recessions often begin AFTER the curve un-inverts.

**Sahm Rule Deep Dive:**
Named after economist Claudia Sahm, this indicator triggers when the 3-month moving average of national unemployment rises 0.50 percentage points above its 12-month low. As of late 2025, the indicator was at approximately 0.35 -- elevated but below the trigger threshold. The Sahm Rule has correctly identified every recession since 1970 with zero false positives, though its creator has noted it may behave differently in post-pandemic labor markets with immigration-driven labor force changes.

### Coincident Indicators (Confirm Current State)

These indicators move WITH the economy and are used to classify the current state.

| Indicator | FRED Series | State Thresholds | Update Frequency | Relevance to MHP |
|-----------|-------------|------------------|------------------|-----------------|
| **Unemployment Rate** | UNRATE | <=4.5% = Expansion; >6% = Recession | Monthly (1st Friday) | Primary input to Layer 1 state classification |
| **State Unemployment** | [ST]UR (e.g., OHUR, KYUR, ILUR) | Varies by state | Monthly (3-4 week lag) | More relevant than national for individual property assessment |
| **Non-farm Payrolls** | PAYEMS | Negative 3+ months -> Recession confirmed | Monthly (1st Friday) | Job creation/destruction directly affects MHP demand |
| **Real GDP** | GDPC1 | <1% QoQ annualized -> Recession territory | Quarterly (with revisions) | Broad economic health metric |
| **Industrial Production** | INDPRO | YoY decline -> Manufacturing recession | Monthly | Critical for Midwest/Rust Belt MHP markets |
| **30-Year Mortgage Rate** | MORTGAGE30US | <4.5% = Low (MHP headwind); >6% = High (MHP tailwind) | Weekly (Thursdays) | Primary input to Layer 3 rate modifier |

### Lagging Indicators (Confirm State Transitions)

These indicators move AFTER the economy changes state. They confirm that a transition has occurred.

| Indicator | FRED Series | What It Confirms | Lag Time |
|-----------|-------------|------------------|----------|
| **Corporate Profits** | CP | Recession depth and recovery timing | 1-2 quarters |
| **Consumer Credit** | TOTALSL | Recovery sustainability | 2-4 quarters |
| **Commercial Real Estate Prices** | (various) | Cycle phase, cap rate direction | 2-6 quarters |
| **Average Duration of Unemployment** | UEMPMEAN | Recession severity (longer = deeper) | 3-6 months |
| **CPI (Core)** | CPILFESL | Inflation persistence, Fed response timing | 6-12 months |

### Indicator Correlation with MHP Performance

Based on Phase 1 analysis and industry research:

| Indicator | Correlation with MHP Occupancy | Mechanism |
|-----------|-------------------------------|-----------|
| Unemployment (national) | Negative for Resilient, Positive for Sensitive | Counter-cyclical demand vs income stress |
| Mortgage Rates | Positive (high rates = higher MHP demand) | Housing affordability barrier keeps residents in MHPs |
| Personal Savings Rate | Positive (high savings = stable tenants) | Financial buffer reduces turnover risk |
| Housing Affordability Index | Negative (lower affordability = higher MHP demand) | Priced-out homebuyers move to MHPs |
| Building Permits | Negative (fewer permits = less competition) | Supply constraint supports MHP occupancy |
| CPI Shelter Component | Positive (rising rents = MHP value proposition) | MHP lot rents typically 30-50% below apartment rents |

---

## FRED API Integration

### API Configuration

```python
FRED_BASE_URL = "https://api.stlouisfed.org/fred"
FRED_API_KEY = os.environ.get('FRED_API_KEY')  # or from .env file

# API limits: 120 requests per minute per API key
# Retry: 3 attempts with exponential backoff (2s, 4s, 8s)
# Timeout: 30 seconds per request
```

**API Key Location:** Stored in `Asset Management/probability-engine/.env` as `FRED_API_KEY=<key>`. Free registration at `https://fred.stlouisfed.org/docs/api/api_key.html`. Limit: 120 requests/minute.

### Complete FRED Series Reference

**Primary Model Inputs (fetched every run):**

| Series ID | Description | Frequency | Used In |
|-----------|-------------|-----------|---------|
| `UNRATE` | National Unemployment Rate (seasonally adjusted) | Monthly | Layer 1: Economic state classification |
| `MORTGAGE30US` | 30-Year Fixed Mortgage Rate (weekly, resampled to monthly) | Weekly | Layer 3: Rate modifier |
| `PSAVERT` | Personal Savings as % of Disposable Income | Monthly | Layer 3: Liquidity modifier |

**State-Level Unemployment (for property-specific analysis):**

| Series ID | State | Sunrise Properties |
|-----------|-------|--------------------|
| `OHUR` | Ohio | Darby, Lakeridge, MNL, STM |
| `KYUR` | Kentucky | Sherman, Elk Creek |
| `ILUR` | Illinois | Mancuso, Rolling Meadows |
| `INUR` | Indiana | Ridgebrook, Miami Village |
| `GAUR` | Georgia | Timberview, Dutch Gardens |
| `MDUR` | Maryland | Walston, Tilghman, Cedarhurst |
| `MSUR` | Mississippi | Bellecrest |
| `MIUR` | Michigan | APE |
| `MNUR` | Minnesota | Park Estates |

**Leading/Coincident Indicators (for state assessment):**

| Series ID | Description | Frequency | Use |
|-----------|-------------|-----------|-----|
| `T10Y2Y` | 10Y-2Y Treasury Spread (yield curve) | Daily | Recession prediction (12-18mo lead) |
| `ICSA` | Initial Jobless Claims | Weekly | Labor market deterioration signal |
| `UMCSENT` | University of Michigan Consumer Sentiment | Monthly | Consumer confidence proxy |
| `PAYEMS` | Total Non-farm Payrolls | Monthly | Job creation/destruction |
| `GDPC1` | Real GDP (chained 2017 dollars) | Quarterly | Economic growth confirmation |
| `INDPRO` | Industrial Production Index | Monthly | Manufacturing health |
| `PERMIT` | Building Permits (new private housing) | Monthly | Housing supply leading indicator |
| `HOUST` | Housing Starts | Monthly | Construction activity |
| `SAHMREALTIME` | Real-time Sahm Rule Recession Indicator | Monthly | Recession trigger (>0.50 = recession) |
| `SAHMCURRENT` | Sahm Rule (current vintage) | Monthly | Historical Sahm Rule values |

**Housing and Affordability:**

| Series ID | Description | Frequency | Use |
|-----------|-------------|-----------|-----|
| `FIXHAI` | Housing Affordability Index (Fixed) | Monthly | MHP demand driver (lower = more MHP demand) |
| `MSPUS` | Median Sales Price of Houses Sold | Quarterly | Site-built housing cost benchmark |
| `RRVRUSQ156N` | Rental Vacancy Rate | Quarterly | Rental market tightness |
| `CSUSHPISA` | Case-Shiller Home Price Index (national) | Monthly | Home price trends |
| `CPIHOSSL` | CPI: Shelter Component | Monthly | Shelter inflation tracking |

**Inflation and Costs:**

| Series ID | Description | Frequency | Use |
|-----------|-------------|-----------|-----|
| `CPIAUCSL` | Consumer Price Index (all items) | Monthly | CPI-based rent justification |
| `CPILFESL` | Core CPI (less food and energy) | Monthly | Underlying inflation trend |
| `CUUR0000SEHF01` | CPI: Electricity | Monthly | Utility cost tracking |
| `CUUR0000SEHF02` | CPI: Natural Gas | Monthly | Utility cost tracking |
| `CUUR0000SETB01` | CPI: Gasoline | Monthly | Transportation cost for tenants |

### API Usage Patterns

**Basic series retrieval:**
```python
from fredapi import Fred
fred = Fred(api_key=os.environ['FRED_API_KEY'])

# Get unemployment rate
unemployment = fred.get_series('UNRATE', observation_start='1990-01-01')

# Get latest value
latest = fred.get_series('UNRATE').iloc[-1]
```

**Raw API call (as used in production model):**
```python
import requests

url = f"{FRED_BASE_URL}/series/observations"
params = {
    "series_id": "UNRATE",
    "api_key": FRED_API_KEY,
    "file_type": "json",
    "observation_start": "1990-01-01",
}

response = requests.get(url, params=params, timeout=30)
data = response.json()
observations = data.get("observations", [])

# Handle missing values (FRED uses "." for missing)
for obs in observations:
    if obs.get("value", ".") != ".":
        values.append(float(obs["value"]))
```

**Data quality checks (production code includes):**
- Skip missing values (value == ".")
- Count and log skipped/invalid data points
- Require minimum 12 valid observations
- Exponential backoff retry (3 attempts, 2s base delay)
- Handle 429 rate limiting responses

### API Gotchas

- MORTGAGE30US is weekly data; must resample to monthly (`series.resample('ME').mean()`) for alignment with UNRATE
- PSAVERT is already monthly but use `resample('ME').last()` for consistent indexing
- FRED timestamps may not align perfectly across series; convert to Period('M') for merging
- API returns all historical data by default; use `observation_start` to limit
- Rate limit: 120 requests/minute; the production code's retry logic handles this but batch requests can hit it

---

## Recession Analysis

### Historical MHP Counter-Cyclicality Evidence

Manufactured housing communities have demonstrated counter-cyclical characteristics across multiple recessions. The evidence is strongest for well-located, affordable communities (matching the Resilient cluster profile).

**2001 Recession (Dot-Com Bust):**
- National unemployment rose from 3.9% to 6.3%
- MHP occupancy nationally remained stable to slightly positive
- Mechanism: Tech layoffs concentrated in higher-income brackets; MHP tenant base less exposed

**2007-2009 Great Recession:**
- National unemployment rose from 4.6% to 10.0%
- MHP NOI increased by approximately 87% from 2004-2009 even through the crisis
- Mechanism: Housing crash eliminated site-built competition; mortgage tightening forced former homeowners into rental housing; MHPs absorbed "move-down" demand
- Industry data: Operating income remained stable throughout the depths of the crisis

**2020 COVID Recession:**
- Unemployment spiked from 3.5% to 14.7% in two months (sharpest spike in history)
- MHP occupancy nationally held near 95%+
- Mechanism: Government stimulus (enhanced unemployment, PPP, rent moratoriums) cushioned tenant income; extremely short recession duration (2 months officially); "nowhere cheaper to go" effect
- Complication: Low interest rates (sub-3%) created MHP headwind by making homeownership more accessible -- the rate modifier captures this dynamic

**Key Academic and Industry Findings:**
- MHP REITs are historically among the most "recession-resistant" REIT sectors (Seeking Alpha, NAREIT data)
- The sector has delivered mid-single-digit rent growth regardless of macroeconomic environment
- Peak 95% occupancy achieved in 2025 with 7% rent growth industry-wide (SkyView Advisors Q1 2025 report)
- MHP investment activity surged: transaction volume up 51% year-over-year in H1 2025, with velocity up 66% vs prior year (Northmarq 2025)

**Why Counter-Cyclicality Works:**
1. **Affordability floor**: MHP lot rents are typically 30-50% below apartment rents, making them the cheapest formal housing option
2. **Move-down demand**: During recessions, apartment renters and homeowners facing foreclosure/distress move "down" to manufactured housing
3. **Move-out barriers**: Relocating a manufactured home costs $5,000-$15,000, creating high switching costs even in distress
4. **Supply constraint**: Virtually no new MHP communities are being developed (zoning barriers, NIMBY opposition), so existing supply absorbs all demand increases
5. **Rent inelasticity**: MHP residents have few cheaper alternatives, making them less price-sensitive than apartment tenants

**Why Counter-Cyclicality Can Fail (Sensitive Cluster):**
1. **Single-employer communities**: If a community's tenant base depends on one large employer that closes, occupancy collapses regardless of macro conditions
2. **Rural isolation**: Communities far from employment centers cannot capture "move-down" demand because there are no jobs nearby
3. **Tenant income concentration**: If most tenants work in a single industry (e.g., manufacturing), a sector-specific downturn hits disproportionately
4. **POH-heavy portfolios**: Park-owned homes (POH) carry vacancy risk that tenant-owned homes (TOH) do not; during recessions, filling vacant POH units is harder

### Recession Prediction Framework

The model uses multiple signals in combination rather than relying on any single indicator:

**Early Warning (12-18 months out):**
- Yield curve inversion (T10Y2Y < 0)
- Conference Board LEI declining 6+ consecutive months
- Credit spreads widening (investment grade vs Treasury)

**Intermediate Warning (6-12 months out):**
- Initial claims trending above 300K
- Consumer sentiment below 80
- PMI below 50 for 3+ consecutive months
- Sahm Rule approaching 0.40

**Recession Confirmed:**
- Sahm Rule triggers (>0.50)
- Non-farm payrolls negative for 2+ months
- GDP contracts for 2+ quarters (NBER determines officially, with significant lag)

**State-Level Recession Detection:**
The Fed published research in January 2026 on assessing recession risks with state-level data. For Sunrise's portfolio concentrated in OH, KY, IL, IN, GA, MD, MS, MI, and MN, state-level unemployment divergences from national trends provide earlier and more relevant signals. A state-level recession can occur even without a national recession (e.g., Michigan in 2005-2006 due to auto industry decline).

### NBER Business Cycle Reference Dates

| Peak | Trough | Duration (Peak to Trough) | Relevance to Model Calibration |
|------|--------|---------------------------|-------------------------------|
| Mar 2001 | Nov 2001 | 8 months | Short, mild -- model should show brief Slowdown->Recovery |
| Dec 2007 | Jun 2009 | 18 months | Deep and long -- model's severe scenario benchmark |
| Feb 2020 | Apr 2020 | 2 months | Shortest on record -- tests model's ability to handle rapid transitions |

---

## Stress Testing Methodology

### Scenario Design

The model includes three pre-built stress test scenarios plus the ability to run custom scenarios:

**Pre-Built Scenarios:**

| Scenario | Forced State | Unemployment | Duration | Historical Analog |
|----------|-------------|--------------|----------|-------------------|
| `mild_recession` | SLOWDOWN | 5.5% | 6 months | 2001 recession |
| `moderate_recession` | RECESSION | 7.0% | 12 months | Average post-WWII recession |
| `severe_recession` | RECESSION | 9.0% | 18 months | 2008-2009 Great Recession |

**Stress Test Impact by Scenario:**

| Scenario | RESILIENT (cumulative) | SENSITIVE (cumulative) | NEUTRAL (cumulative) | Portfolio Net |
|----------|----------------------|----------------------|---------------------|--------------|
| Mild | ~+1.2% | ~-3.3% | ~-0.6% | ~-1.0% |
| Moderate | ~+13.8% | ~-19.2% | ~-2.4% | ~-4.0% |
| Severe | ~+20.7% | ~-28.8% | ~-3.6% | ~-6.0% |

*Note: These are BASE model estimates without rate/liquidity modifiers. Actual impact depends on the concurrent rate and liquidity environment.*

### Stress Test Methodology

The stress test differs from the standard forecast in a critical way: it FORCES the economic state for the full duration rather than using probabilistic transitions.

```
stress_impact(scenario, cluster) = expected_impact(forced_state, cluster) * duration_months
```

This produces a WORST CASE estimate because:
1. It assumes the stressed state persists for the full duration (no partial recovery)
2. It does not account for policy responses (Fed rate cuts, fiscal stimulus)
3. It does not account for the natural hedge effect within the stress test itself

### Portfolio-Level Impact Calculation

```
Portfolio Stress Impact = SUM over clusters of:
    (cluster_property_count / total_property_count) * cluster_stress_impact
```

**Financial Translation:**
To convert occupancy impact to dollar impact:
```
NOI Impact = Occupancy Delta * Total Lot Count * Weighted Avg Lot Rent * 12
```

Example for moderate recession:
- Portfolio net impact: -4.0% occupancy
- Total MHP lots: ~1,800
- Weighted avg lot rent: ~$400/month
- Annual NOI impact: -0.04 * 1,800 * $400 * 12 = -$345,600/year

### Rate Scenario Sensitivity

The model can also stress-test rate environments independently by holding the economic state constant and varying only the rate environment across all 6 possibilities. This isolates the interest rate effect:

| Rate Environment | Estimated Rate | Portfolio Effect vs Base |
|-----------------|---------------|------------------------|
| LOW_STABLE | ~4.0% | -30% to -40% dampening |
| LOW_RISING | ~4.5% | -10% dampening |
| MODERATE | ~6.0% | Neutral (1.0x) |
| HIGH_STABLE | ~7.5% | +20% to +30% amplification |
| HIGH_RISING | ~8.0% | +30% to +40% amplification |
| FALLING | ~5.5% | -20% to -30% dampening |

**Reading the table:** In a HIGH_RISING rate environment, the model amplifies the base occupancy impact by 30-40%. For Resilient properties in recession, this means the counter-cyclical GAIN is larger (more demand trapped in MHPs). For Sensitive properties in recession, the LOSS is also larger (affordability crisis compounds job loss stress).

### Custom Stress Testing

For ad-hoc scenarios (e.g., "What if tariffs cause a manufacturing recession in Ohio?"):

1. Override the forced state and duration
2. Optionally override the rate environment (e.g., HIGH_RISING for a stagflation scenario)
3. Optionally filter to specific properties or states
4. Apply the composite modifier calculation

This is done by calling `ScenarioEngine.stress_test()` with custom parameters or by constructing a manual scenario.

---

## Scenario Planning

### Base / Bull / Bear Framework

The Probability Engine supports three scenario types that map to business planning:

**Base Case (50th percentile):**
- Uses the standard Markov chain forecast with current transition probabilities
- Represents the most likely economic path based on historical patterns
- This is what the quarterly dashboard export produces

**Bull Case (optimistic, 20th percentile):**
- Force EXPANSION state for 12 months
- Apply LOW_STABLE or MODERATE rate environment
- Represents a "Goldilocks" scenario: strong economy, moderate rates
- MHP implications: Stable occupancy but some resident attrition to homeownership in low-rate scenario; strong rent growth opportunity

**Bear Case (pessimistic, 80th percentile):**
- Run moderate or severe recession stress test
- Apply HIGH_RISING rate environment (stagflation scenario)
- Represents maximum stress: job losses + housing affordability crisis
- MHP implications: Resilient cluster thrives (counter-cyclical demand surge); Sensitive cluster under severe stress; portfolio natural hedge partially offsets

### Monte Carlo Simulation (Future Enhancement)

The current model uses deterministic Markov chain forecasting. A Monte Carlo enhancement would:

1. **Sample state paths**: Instead of using expected values, randomly sample a specific state path for each simulation run using the transition matrix probabilities
2. **Run 10,000+ simulations**: Each run produces a different 12-month state sequence
3. **Build outcome distribution**: Plot the distribution of cumulative portfolio impact across all runs
4. **Extract percentiles**: Report the 5th, 25th, 50th, 75th, and 95th percentile outcomes

**Implementation approach:**
```python
import numpy as np

n_simulations = 10000
months_ahead = 12
results = []

for _ in range(n_simulations):
    current_state = current_state_idx
    cumulative_impact = 0.0

    for month in range(months_ahead):
        # Sample next state from transition probabilities
        next_state = np.random.choice(
            range(5),
            p=transition_matrix[current_state]
        )
        # Calculate impact for this month
        for cluster in clusters:
            impact = expected_impact(EconomicState(next_state), cluster)
            cumulative_impact += impact * cluster_weight
        current_state = next_state

    results.append(cumulative_impact)

# Percentile analysis
p5 = np.percentile(results, 5)    # Worst case (bear)
p50 = np.percentile(results, 50)  # Base case
p95 = np.percentile(results, 95)  # Best case (bull)
```

**Advantages over deterministic forecast:**
- Captures the RANGE of possible outcomes, not just the expected value
- Produces confidence intervals for portfolio impact
- Identifies tail risks (5th percentile scenarios)
- More honest about uncertainty -- a probability distribution is more informative than a point estimate

**Current status:** Not implemented in production. The deterministic Markov chain forecast combined with the three stress test scenarios provides adequate coverage for current decision-making. Monte Carlo should be considered if the model is used for investor-facing materials or capital allocation decisions where tail risk quantification matters.

---

## Interest Rate Impact Analysis

### Rate Environment Classification

The Layer 3 rate modifier uses a 6-state classification based on the 30-year fixed mortgage rate (MORTGAGE30US):

| Environment | Rate Level | 3-Month Trend | Impact on MHP |
|-------------|-----------|---------------|---------------|
| **LOW_STABLE** | < 4.5% | Not rising | HEADWIND: Residents can buy homes; attrition risk |
| **LOW_RISING** | < 4.5% | Rising >= 0.5% | Transition: Headwind weakening |
| **MODERATE** | 4.5% - 6.0% | Stable | Neutral: No significant rate effect |
| **HIGH_STABLE** | > 6.0% | Stable | TAILWIND: Housing unaffordable; residents stay |
| **HIGH_RISING** | > 6.0% | Rising >= 0.5% | STRONG TAILWIND: Acute affordability crisis |
| **FALLING** | Any level | Falling > 0.5% | HEADWIND: Easing encourages homebuying |

**Threshold Calibration History:**
- Original thresholds (2026-01-20): LOW < 5.0%, HIGH > 7.0%
- After backtest (2026-01-20): LOW adjusted to 4.5%, HIGH adjusted to 6.0%
- Rationale: Historical backtest showed 7.0% was too high -- only breached briefly in 2022-2023; 6.0% better captures the "restrictive" threshold that was relevant in the 2000s-2010s

### Rate Modifier Matrix

The modifier is a multiplicative adjustment applied to the Layer 2 base impact. Key combinations:

**High-Impact Combinations (modifier furthest from 1.0):**

| Economic State | Rate Environment | Cluster | Modifier | Business Logic |
|---------------|-----------------|---------|----------|---------------|
| RECESSION | HIGH_RISING | RESILIENT | 1.6x | Maximum MHP demand: job losses + nowhere to buy |
| RECESSION | HIGH_RISING | SENSITIVE | 1.5x | Even sensitive gains: affordability crisis traps residents |
| EXPANSION | FALLING | RESILIENT | 0.6x | Maximum attrition: strong economy + cheap mortgages |
| RECOVERY | LOW_STABLE | RESILIENT | 0.7x | Recovery + cheap rates = residents leaving to buy |
| RECOVERY | FALLING | RESILIENT | 0.6x | Strongest headwind: improving economy + easing rates |

**The Modifier Logic for MHPs:**
- HIGH rates generally HELP MHPs (housing unaffordable, residents stay)
- LOW rates generally HURT MHPs (residents can buy homes, leave)
- FALLING rates HURT most (active easing = residents actively pursuing homeownership)
- This interacts with economic state: HIGH rates + RECESSION = maximum demand pressure into MHPs ("nowhere else to go")

### Cap Rate and Valuation Impact

Interest rates affect MHP valuations through two channels:

**Channel 1: Cap Rate Compression/Expansion**
- Industry cap rates for stabilized MHCs: approximately 5.5%-6.3% in 2024-2025
- Top-tier MH assets: 4%-5% cap rates
- Cap rate spread to 10-year Treasury historically averages 250-350 bps for MHP
- A 100bp rise in risk-free rates typically translates to 50-75bp cap rate expansion for MHP (partial pass-through due to counter-cyclical demand characteristics)

**Channel 2: Demand Effect**
- Higher rates -> higher mortgage payments -> more residents priced out of homeownership -> more MHP demand -> higher occupancy -> higher NOI -> lower cap rates (partially offsetting Channel 1)
- This creates a "natural shock absorber" where MHP valuations are less rate-sensitive than other CRE sectors

**Practical Application:**
When modeling acquisition targets, the rate environment should inform:
1. Exit cap rate assumptions (adjust for expected rate direction)
2. Occupancy growth assumptions (apply rate modifier to baseline occupancy trajectory)
3. Rent growth assumptions (higher occupancy = more pricing power)

### Backtest Results (Historical Validation)

The rate modifier was backtested against three historical periods:

**2004-2006 Fed Tightening:**
- Rates: 5.3% -> 6.4%
- Model correctly predicted MHP tailwind (positive rate effect)
- Rate environments observed: MODERATE, HIGH_STABLE
- PASS: Directional accuracy confirmed

**2019-2020 COVID Crash:**
- Rates: 4.5% -> 2.7%
- Model correctly predicted mixed effects (falling rates = headwind, recession = tailwind)
- Rate environments observed: LOW_STABLE, FALLING
- Model detected RECESSION months during unemployment spike
- PASS: Mixed signal correctly captured

**2022-2023 Rapid Hiking:**
- Rates: 3.2% -> 7.8%
- Model correctly predicted strong MHP tailwind
- Rate environments observed: LOW_RISING -> MODERATE -> HIGH_RISING -> HIGH_STABLE
- 2022-2023 rate effect > 2004-2006 effect (correctly reflecting more dramatic rate move)
- PASS: Magnitude ordering correct

---

## Housing Affordability Connection

### NAR Housing Affordability Index (HAI)

The National Association of Realtors Housing Affordability Index is the primary metric linking site-built housing costs to MHP demand. Available on FRED as `FIXHAI`.

**Methodology:**
- HAI = (Median Family Income / Qualifying Income) * 100
- Qualifying Income = income needed to qualify for a mortgage on the median-priced home
- Assumes 20% down payment, 25% qualifying ratio (monthly P&I cannot exceed 25% of income)
- HAI of 100 = median family has exactly enough income to qualify
- HAI of 120 = median family has 120% of needed income (affordable)
- HAI below 100 = median family cannot afford median home (unaffordable)

**MHP Connection:**
- When HAI drops below 100, the pool of potential homebuyers shrinks, increasing demand for rental housing including MHPs
- HAI declined sharply from 2021 (>170) to 2023 (<90) due to both home price appreciation and rate increases
- This correlated with the strongest MHP demand and rent growth period in decades
- Inverse correlation: Lower HAI = Higher MHP demand = Higher MHP occupancy

**MHP-Specific Affordability Advantage:**
- Average manufactured home cost: ~$125,000 (vs ~$400,000 median site-built)
- Average MHP lot rent: ~$400/month (vs ~$1,200-1,800/month apartment rent in same markets)
- MHP total housing cost (lot rent + home payment) typically 40-60% below comparable apartment rent
- This gap WIDENS during high-rate environments: a $400K home at 7% costs $2,661/month vs the same at 3.5% costs $1,796/month -- a $865/month increase that pushes marginal buyers toward MHPs

### Affordability Trigger Thresholds

| HAI Level | Affordability Assessment | MHP Demand Implication |
|-----------|------------------------|----------------------|
| > 150 | Highly affordable | Low MHP demand pressure; resident attrition risk |
| 120-150 | Moderately affordable | Stable MHP demand |
| 100-120 | Marginally affordable | Increasing MHP demand |
| 80-100 | Unaffordable | Strong MHP demand surge |
| < 80 | Severely unaffordable | Maximum MHP demand; counter-cyclical effect amplified |

---

## Regional Economic Analysis

### Sunrise Portfolio Geographic Concentration

The portfolio is concentrated in the Midwest and Mid-Atlantic with exposure to the South:

| Region | States | Properties | % of Portfolio |
|--------|--------|------------|---------------|
| **Midwest** | OH, IN, IL, MI, MN | 10 | 56% |
| **Mid-Atlantic** | MD, KY | 5 | 28% |
| **South** | GA, MS | 3 | 17% |

### Midwest Economic Characteristics Relevant to MHP

**Strengths for MHP operations:**
- Lower cost of living supports MHP affordability thesis
- Manufacturing recovery (construction in eastern Midwest tripled in recent years)
- Relatively lower home prices mean the MHP-to-homeownership gap is smaller -- but this also means MHP lot rents can be higher relative to local incomes
- Infrastructure investment (reshoring, EV plants) creating new employment in traditional Rust Belt markets

**Risks for MHP operations:**
- Legacy manufacturing dependence: After 2000, Midwest manufacturing employment declined by 1.2 million jobs
- Single-employer concentration: Many smaller MHP markets depend on one or two large employers
- Population loss: Some Rust Belt communities continue to lose population to Sun Belt states
- College attainment gap: Local labor markets with higher college attainment show 9.1 percentage points higher employment growth per decade -- many MHP markets have below-average attainment

### Local Employer Shock Analysis

One of the model's primary blind spots is local employer concentration risk. A community may be classified as RESILIENT at the macro level but be devastated by a plant closure.

**Risk Assessment Framework:**

| Risk Factor | Assessment Method | Data Source |
|-------------|-------------------|-------------|
| Top employer dependency | % of residents employed by single employer | Property manager survey |
| Employer industry | Cyclicality of dominant local industry | BLS QCEW data |
| Employer financial health | Public filings, news monitoring | SEC EDGAR, Google Alerts |
| Labor market diversity | HHI of employment by industry | County-level BLS data |
| Commute radius | How far residents commute to work | Census ACS commute data |

**Employer Shock Impact Pattern:**
1. **Announcement** (Month 0): News of closure/layoffs; no immediate occupancy impact
2. **Severance period** (Months 1-3): Residents use severance/savings; occupancy stable but applications decline
3. **Income stress** (Months 3-6): Savings depleted; delinquency rises; some residents leave
4. **Stabilization** (Months 6-12): Residents who found new jobs stay; others leave; occupancy finds a new floor
5. **Recovery** (Months 12-24): New employers or commute patterns establish; occupancy slowly rebuilds

**Mitigation:** The model's 3-month lag partially captures this pattern, but a local employer shock is fundamentally different from a macroeconomic recession because it does NOT generate offsetting "move-down" demand (the crisis is local, not nationwide). Properties in single-employer markets should be classified as SENSITIVE regardless of their macro-level correlation.

### State-Level Divergence from National Trends

National unemployment can mask significant state-level variation. Examples from the Sunrise portfolio's history:

- Ohio can lag national recovery by 3-6 months due to manufacturing cycle timing
- Georgia tends to lead national employment trends due to Atlanta's diversified economy
- Kentucky follows a unique pattern driven by coal, bourbon, and automotive manufacturing
- Minnesota typically has unemployment 1-2 points below the national average

**Practical Application:** When the model classifies the national state as EXPANSION but a state like Ohio is experiencing localized slowdown, property managers at OH properties should operate on the more conservative state-level signal. The quarterly dashboard should flag these divergences.

---

## Inflation and Expense Impact

### CPI-Based Rent Justification Methodology

Several states in the Sunrise portfolio have statutory frameworks linking allowable rent increases to CPI:

**Maryland (3 Sunrise properties: Walston, Tilghman, Cedarhurst):**
- 10% rent cap for 3 years post-acquisition (per mhp-regulatory skill)
- After cap period, rent increases must be "reasonable" -- CPI provides the baseline justification

**Delaware Framework (reference model):**
- Delaware's "Rent Justification Act" for manufactured housing communities requires that annual rent increases exceeding CPI must be justified through arbitration if contested
- This is the most formal CPI-linked framework and serves as a template for how other states may legislate

**Minnesota (Park Estates):**
- 90-day notice required for any rent increase
- No statutory CPI linkage, but CPI evidence strengthens justification in disputes
- No admin/capital/distribution markup allowed on utility billing

**CPI-Based Justification Strategy:**
1. Track local-area CPI (or national CPI if local unavailable) using FRED series `CPIAUCSL`
2. Calculate trailing 12-month CPI change as the "inflation floor" for rent increases
3. Add property-specific cost increases (taxes, insurance, utilities) as documented justification
4. For increases above CPI + documented costs, provide market comp evidence (comparable MHP lot rents in the area)

### Inflation Pass-Through Dynamics

MHP operators face an asymmetric inflation environment:

**Costs that INCREASE with inflation:**
- Property taxes (typically lag CPI by 1-2 years)
- Insurance premiums (can exceed CPI significantly after catastrophic weather years)
- Utility costs (electricity, water, sewer -- CPI sub-indices: `CUUR0000SEHF01`, `CUUR0000SEHF02`)
- Maintenance and repair costs (labor + materials)
- Management and administrative costs

**Revenue that CAN increase with inflation (but with friction):**
- Lot rents (subject to notice requirements: 30-90 days depending on state)
- Utility billing (subject to state-specific passthrough rules; MN prohibits markups)
- Late fees and other fees (subject to lease terms and statutory limits)

**The Squeeze:**
In high-inflation environments, costs rise immediately but revenue increases face:
1. Notice period delays (30-90 days)
2. Tenant resistance and potential vacancy
3. Statutory caps in some jurisdictions
4. Political/PR risk of aggressive increases during economic stress
5. The resident/investor tension inherent in the value-add model

**FRED Series for Expense Tracking:**

| Expense Category | FRED Series | Typical % of OpEx |
|-----------------|-------------|-------------------|
| Utilities (electricity) | CUUR0000SEHF01 | 15-25% |
| Utilities (gas) | CUUR0000SEHF02 | 5-10% |
| Insurance | (no direct FRED series; use CPIHOSSL as proxy) | 8-12% |
| Property taxes | (local; no FRED series) | 15-25% |
| Maintenance labor | CUUR0000SAE1 (CPI: Services less rent of shelter) | 10-15% |
| All items | CPIAUCSL | Benchmark |

### Inflation Impact on the Model

Inflation is not directly modeled in the Probability Engine (the model tracks occupancy, not financials). However, inflation affects model inputs indirectly:

1. **Fed response to inflation -> Rate changes -> Rate modifier impact**: High inflation -> Fed tightens -> HIGH_RISING rate environment -> MHP tailwind
2. **Inflation erodes household savings -> Liquidity modifier impact**: Persistent inflation -> lower real savings rate -> THIN or DEPLETED liquidity -> higher turnover risk
3. **Inflation-driven rent increases -> Tenant stress on Sensitive properties**: If lot rent increases outpace wage growth, Sensitive properties may see accelerated occupancy loss

---

## Decision Trees

### Current State Assessment

```
START: What is the current unemployment rate and 3-month trend?

IF Unemployment <= 4.5%:
    IF 3-month change >= +0.3%:
        STATE = SLOWDOWN
        ACTION: Monitor weekly claims; alert if > 300K
    IF 3-month change <= -0.3%:
        STATE = RECOVERY
        ACTION: Push rent increases; recovery window
    ELSE:
        STATE = EXPANSION
        ACTION: Standard operations

IF Unemployment > 6.0%:
    IF 3-month change >= +0.3%:
        STATE = RECESSION
        ACTION: Activate Sensitive cluster reserves; accelerate Resilient rent increases
    IF 3-month change <= -0.3%:
        STATE = RECOVERY
        ACTION: Aggressive rent catch-up across portfolio
    ELSE:
        STATE = TROUGH
        ACTION: Maintain reserves; prepare recovery playbook

THEN: Check rate environment and liquidity to complete the picture
```

### When to Run a Stress Test

```
TRIGGER: Run stress test when ANY of the following occur:

1. Yield curve inverts (T10Y2Y < 0)
   -> Run mild + moderate recession scenarios
   -> Timeline: 12-18 months to potential recession

2. Sahm Rule crosses 0.40
   -> Run moderate + severe recession scenarios
   -> Timeline: 0-6 months to potential recession

3. Initial claims exceed 300K for 4+ weeks
   -> Run mild recession scenario
   -> Monitor weekly for escalation

4. Fed begins hiking cycle (after period of cuts)
   -> Run rate sensitivity comparison (all 6 rate environments)
   -> Assess valuation impact on acquisition pipeline

5. Major employer announces closure in a Sunrise market
   -> Run custom stress test for affected properties
   -> Consider reclassifying property from NEUTRAL/RESILIENT to SENSITIVE

6. Quarterly routine (Q1, Q2, Q3, Q4)
   -> Run full model refresh with latest FRED data
   -> Compare current forecast to prior quarter
```

### Alert Trigger Thresholds

| Alert Level | Trigger | Action Required |
|-------------|---------|----------------|
| **GREEN** | All leading indicators positive; HAI > 120 | Standard operations |
| **YELLOW** | 1-2 leading indicators negative OR state shows SLOWDOWN | Increase monitoring frequency to monthly; review Sensitive cluster reserves |
| **ORANGE** | 3+ leading indicators negative OR Sahm Rule > 0.40 | Run full stress test; brief leadership; activate contingency reserves |
| **RED** | Sahm Rule triggers (>0.50) OR non-farm payrolls negative 2+ months | Full recession playbook; maximize Resilient rent increases; marketing push for Sensitive properties; defer non-essential CapEx |

---

## Common Gotchas

### Model Limitations

1. **Markov memorylessness**: The model treats each month independently. In reality, a recession that has lasted 12 months is more likely to end soon than one that just started. The transition matrix captures average persistence but not duration-dependent dynamics.

2. **National vs. local unemployment**: The Layer 1 model uses national UNRATE. State-level unemployment (OHUR, etc.) can diverge significantly. A national EXPANSION can coexist with a state-level RECESSION (e.g., Michigan in 2005).

3. **Static cluster assignments**: Cluster assignments are treated as permanent. In reality, a property can shift clusters if its tenant base changes (e.g., new large employer opens nearby, converting a SENSITIVE property to RESILIENT).

4. **Heuristic modifiers**: The Layer 3 rate and liquidity modifiers are calibrated by expert judgment and historical backtest, NOT trained on actual MHP occupancy data. They capture directional effects correctly but magnitudes are approximate.

5. **3-month lag assumption**: The lag is a population average. Some properties respond faster (within 1 month for properties near large employers) and some slower (6+ months for rural communities with diverse employment bases).

6. **No supply-side modeling**: The model assumes constant housing supply. A surge in apartment construction in a Sunrise market could reduce MHP demand even during a macro tailwind.

7. **No local competition modeling**: A new MHP or mobile home dealer opening nearby would affect individual property occupancy independent of macro conditions.

8. **Rent increase impact not modeled**: Aggressive rent increases can reduce occupancy independent of economic conditions. The model forecasts "natural" occupancy change, not the joint effect of economic conditions + management decisions.

### Overconfidence Traps

- **Do not present Markov chain forecasts as precise predictions.** They are probability-weighted expected values with substantial uncertainty bands. A "portfolio impact of -2.3%" really means "somewhere between -6% and +1% with -2.3% as the center estimate."

- **Do not extrapolate short-term trends.** If the model shows EXPANSION with 92% persistence, that does NOT mean we will stay in expansion for 12 months. It means there is a ~40% chance of transitioning to a different state at some point in the next 12 months (1 - 0.92^12 = 0.37).

- **Do not treat the stress test as the worst case.** The severe recession scenario uses 2008-level unemployment (9%). The COVID spike hit 14.7% -- a scenario not in the pre-built set. True tail events can exceed modeled scenarios.

- **Do not ignore base rates.** Since 1990, the US has spent roughly 60% of months in EXPANSION. Even with negative leading indicators, the prior probability of remaining in expansion is high.

### Data Quality Issues

- **FRED data revisions**: Unemployment data is revised for 2-3 months after initial release. The model uses the latest available data, which means forecasts made immediately after a data release may change when revisions occur.

- **MORTGAGE30US gaps**: The weekly series occasionally has missing values (represented as "." in FRED). The production code skips these and resamples to monthly means, but this can introduce slight inaccuracies if gaps cluster in a particular week.

- **PSAVERT volatility**: Personal savings rate is notably volatile and subject to large revisions. The COVID stimulus period produced extreme readings (>30%) that distort the historical distribution. The model's thresholds (STRONG > 8%, NORMAL 5-8%, THIN 3-5%, DEPLETED < 3%) were calibrated on the non-COVID distribution.

### Auditor-Identified Issues (Addressed)

| Issue | Identified By | Resolution | Date |
|-------|--------------|------------|------|
| 3-state model too coarse | Gemini | Upgraded to 5-state model | 2026-01-08 |
| Lag calculation bug (redundant matrix powers) | Kimi-K2 | Pre-compute all state distributions | 2026-01-08 |
| Division by zero in portfolio weighting | Kimi-K2 | Added guard against zero total properties | 2026-01-08 |
| Missing row normalization validation | Kimi-K2 | Added `np.allclose` check with relaxed tolerance | 2026-01-08 |
| Rate thresholds too high | Backtest validation | LOW: 5.0->4.5, HIGH: 7.0->6.0 | 2026-01-20 |
| Composite modifier can be unbounded | Auditor recommendation | Capped at 2.0x maximum | 2026-01-20 |

---

## Procedures

### Quarterly Model Refresh

**Cadence:** Start of each quarter (January, April, July, October) or when economic state changes.

**Steps:**

1. **Fetch latest data:**
```bash
cd ~/Documents/IA/Projects/Asset\ Management/probability-engine
python3 export_forecast_dashboard.py
```

2. **Review output:**
   - Current economic state (does it match your qualitative assessment?)
   - State probabilities (any surprising shifts from last quarter?)
   - Cluster impacts (Resilient still positive? Sensitive still negative?)
   - Recommendations (actionable and current?)

3. **Verify against reality:**
   - Compare forecast occupancy direction with actual occupancy trends from the Occupancy Dashboard
   - If forecast and actuals diverge significantly (>3% over a quarter), investigate:
     - Is the divergence local (one property) or systematic (one cluster)?
     - Has a property's cluster assignment become outdated?
     - Is there a local factor not captured by the model?

4. **Update the dashboard:**
   - The script automatically updates the `Economic_Forecast` tab in the Strategic KPI Sheet
   - Sheet: `https://docs.google.com/spreadsheets/d/{KPI_SHEET_ID_STRATEGIC}`

5. **Document:**
   - Note any threshold changes, cluster reassignments, or model adjustments
   - Update `PROJECT_MEMORY.md` under the Probability Engine section

### Ad-Hoc Stress Test

**When:** Any alert trigger from the Decision Trees section fires.

**Steps:**

1. **Determine scenario:**
   - Use pre-built scenarios (mild/moderate/severe) for general assessment
   - Build custom scenario for specific risks (local employer, sector-specific)

2. **Run the test:**
```python
from markov_chain_model import ScenarioEngine, EconomicRegime

economic_model = EconomicRegime()
economic_model.fetch_historical_unemployment(start_year=1990)
economic_model.build_state_history()
economic_model.build_transition_matrix()

engine = ScenarioEngine(economic_model=economic_model)
results = engine.stress_test("moderate_recession")
```

3. **Translate to dollars:**
   - Convert occupancy impact to revenue impact using current lot rents and unit counts
   - Estimate NOI impact including potential rent increase deferrals
   - Compare required reserves to current reserve levels

4. **Brief leadership:**
   - Use the Stress Test Report output format (below)
   - Focus on portfolio net impact (not individual cluster detail)
   - Lead with the actionable recommendation

### Indicator Monitoring

**Daily (automated or glance check):**
- Yield curve (T10Y2Y): Available on FRED or financial dashboards
- Major economic news that could affect MHP markets

**Weekly:**
- Initial jobless claims (ICSA): Released Thursdays
- MORTGAGE30US: Updated weekly

**Monthly (first week):**
- Unemployment rate (UNRATE): Released first Friday
- Consumer sentiment (UMCSENT): Released mid-month
- Check if any state-level unemployment diverges from national trend

**Quarterly:**
- Full model refresh (see procedure above)
- GDP release (GDPC1)
- Housing Affordability Index (FIXHAI)
- Review and update cluster assignments if warranted

### Model Validation

**Cadence:** Semi-annually or after any model change.

**Steps:**

1. **Run validation script:**
```bash
cd ~/Documents/IA/Projects/Asset\ Management/probability-engine
python3 validate_model_vs_actual.py
```

2. **Review metrics:**
   - MAE (Mean Absolute Error): Target < 2.0% per property-month
   - Direction accuracy: Target > 60% (model predicts correct direction of occupancy change)
   - Cluster ranking: Resilient should outperform Sensitive (PASS/FAIL)
   - Correlation: Predicted vs actual > 0.3 (PASS), > 0.5 (GOOD)

3. **Address issues:**
   - If MAE > 2.0%, investigate whether specific properties are outliers
   - If cluster ranking fails, reassess cluster assignments
   - If correlation is weak, consider adding local variables or adjusting thresholds

4. **Document findings:**
   - Save to `VALIDATION_RESULTS.json`
   - Note any recommended threshold or assignment changes
   - Track model error trends over time

### Calibration Governance

**Who can change model parameters:**
- Threshold changes (unemployment levels, rate levels): Requires backtest validation + auditor review
- Cluster reassignments: Requires 12+ months of new data + correlation analysis
- New modifier values: Requires backtest across 3+ historical periods

**Change log requirement:**
Every parameter change must be documented with:
1. What changed and from what to what
2. Why the change was made (data evidence)
3. Validation results before and after
4. Who approved the change

**Backtest protocol:**
Before any threshold change goes to production, backtest against:
1. 2004-2006 Fed Tightening
2. 2019-2020 COVID Crash
3. 2022-2023 Rapid Hiking

All three periods must show directionally correct results and the change must improve at least one period without degrading others. The `backtest_rate_modifiers.py` script automates this.

---

## Output Formats

### Current Economic Assessment

Use this format for quarterly updates and ad-hoc state assessments:

```markdown
## Economic Assessment: [Date]

### Current State: [STATE]
**Confidence:** [HIGH/MODERATE/LOW]
**Rate Environment:** [RATE_ENV] (mortgage rate: X.XX%)
**Liquidity Environment:** [LIQUIDITY_ENV] (savings rate: X.X%)

### Key Indicators
| Indicator | Current | Trend | Signal |
|-----------|---------|-------|--------|
| Unemployment | X.X% | [up/down/stable] | [Interpretation] |
| Yield Curve (10Y-2Y) | +/-X bp | [up/down/stable] | [Normal/Inverted/Steepening] |
| Initial Claims | XXXK | [up/down/stable] | [Healthy/Caution/Alarm] |
| Consumer Sentiment | XX.X | [up/down/stable] | [Confident/Cautious/Pessimistic] |
| Sahm Rule | X.XX | [up/down/stable] | [Green/Yellow/Triggered] |
| Housing Affordability | XXX | [up/down/stable] | [Affordable/Tight/Unaffordable] |
| Mortgage Rate | X.XX% | [up/down/stable] | [Low/Moderate/High] |

### State Probability (Next 12 Months)
| State | Probability |
|-------|-------------|
| EXPANSION | X% |
| SLOWDOWN | X% |
| RECESSION | X% |
| TROUGH | X% |
| RECOVERY | X% |

### Portfolio Implications
- **Resilient Cluster (7 properties):** [Forecast impact, rate-adjusted]
- **Sensitive Cluster (7 properties):** [Forecast impact, rate-adjusted]
- **Neutral Cluster (4 properties):** [Forecast impact]
- **Portfolio Total (18 properties):** [Net forecast impact]

### Rate Environment Impact
[Description of how current rate environment modifies the base forecast]

### Recommended Actions
1. [Priority action]
2. [Secondary action]
3. [Monitoring action]

### Confidence: [HIGH/MODERATE/LOW]
[Basis for confidence rating]
```

### Stress Test Report

Use this format when presenting stress test results to leadership:

```markdown
## Portfolio Stress Test: [Scenario Name]

### Scenario Parameters
- **Trigger:** [What causes this scenario]
- **Duration:** [X months]
- **Peak Unemployment:** [X%]
- **Rate Environment Assumption:** [Rate environment used]
- **Historical Analog:** [Most similar past recession]

### Property-Level Impact
| Property | State | Cluster | Confidence | Baseline Occ | Stressed Occ | Change |
|----------|-------|---------|------------|--------------|--------------|--------|
| [Name] | [ST] | [Type] | [H/M/L] | XX% | XX% | -X.X% |
...

### Financial Impact
| Metric | Baseline | Stressed | Variance |
|--------|----------|----------|----------|
| Portfolio Occupancy | XX.X% | XX.X% | -X.X% |
| Monthly Revenue | $XXX,XXX | $XXX,XXX | -$XX,XXX |
| Annual NOI Impact | | | -$XXX,XXX |
| Reserve Requirement | | | $XXX,XXX |

### Natural Hedge Effect
- Resilient cluster gains partially offset Sensitive losses
- Net portfolio impact [X%] vs Sensitive-only impact [Y%]
- Hedge effectiveness: [X/Y]%

### Mitigation Strategies
1. **Sensitive properties:** [Specific actions - retention programs, marketing, payment plans]
2. **Reserve allocation:** [Amount needed, source of funds]
3. **CapEx timing:** [Which projects to defer, which to accelerate]
4. **Rent strategy:** [Accelerate at Resilient, hold at Sensitive, CPI-justified at Neutral]

### Confidence: [HIGH/MODERATE/LOW]
[Basis for confidence -- historical analog quality, model validation results]
```

### Forecast Dashboard (Google Sheets)

The `export_forecast_dashboard.py` script outputs the following sections to the `Economic_Forecast` tab:

1. **Header** -- Generation timestamp, cadence recommendation
2. **Current Economic Conditions** -- State, state probabilities, transition probabilities
3. **Cluster Forecast Summary** -- 12-month cumulative impact by cluster with portfolio weights
4. **Recommendations** -- Trigger-based action items
5. **Property-Level Forecast** -- Per-property cluster, confidence, impact, and recommended action
6. **Stress Test Scenarios** -- Mild/Moderate/Severe impact by cluster
7. **Methodology** -- Model description for sheet readers

---

## References

### Codebase

| File | Location | Purpose |
|------|----------|---------|
| `markov_chain_model.py` | `/Asset Management/probability-engine/` | Core 3-layer model (1,600+ lines) |
| `export_forecast_dashboard.py` | `/Asset Management/probability-engine/` | Quarterly export to Google Sheets |
| `interest_rate_modifier.py` | `/Asset Management/probability-engine/` | Layer 3 prototype and comparison tools |
| `backtest_rate_modifiers.py` | `/Asset Management/probability-engine/` | Historical backtest validation (3 periods) |
| `validate_model_vs_actual.py` | `/Asset Management/probability-engine/` | Model vs actual occupancy validation |
| `validate_model_historical.py` | `/Asset Management/probability-engine/` | Historical validation framework |
| `indicator_correlation_analysis.py` | `/Asset Management/probability-engine/` | Phase 1 indicator correlation analysis |
| `economic_correlation_analysis.py` | `/Asset Management/probability-engine/` | Unemployment-occupancy correlation |
| `export_occupancy_for_validation.py` | `/Asset Management/probability-engine/` | Exports occupancy data for validation |
| `test_markov_chain_model.py` | `/Asset Management/probability-engine/` | Unit tests for the model |

### External Data Sources

| Source | URL | Data Used |
|--------|-----|-----------|
| FRED (St. Louis Fed) | `https://fred.stlouisfed.org` | UNRATE, MORTGAGE30US, PSAVERT, T10Y2Y, ICSA, and all series listed in FRED section |
| FRED API | `https://fred.stlouisfed.org/docs/api/fred/` | Programmatic data retrieval (API key required) |
| NAR Housing Affordability | `https://www.nar.realtor/research-and-statistics/housing-statistics/housing-affordability-index` | HAI methodology and data |
| NBER Business Cycles | `https://www.nber.org/research/data/us-business-cycle-expansions-and-contractions` | Official recession dates |
| BLS Employment Data | `https://www.bls.gov/` | State and local unemployment, QCEW |

### Research and Industry Sources

| Source | Key Finding | Relevance |
|--------|-------------|-----------|
| Seeking Alpha (2023) | MHP REITs among most recession-resistant REIT sectors | Supports counter-cyclicality thesis |
| SkyView Advisors Q1 2025 | Peak 95% occupancy, 7% rent growth | Current MHP market strength benchmark |
| Northmarq 2025 | Transaction volume up 51% YoY, velocity up 66% | Investment market activity |
| Multi-Housing News (2026) | MHP is investor favorite for 2026 | Market demand confirmation |
| Urban Institute (2022) | Role of manufactured housing in affordable supply | Policy and demand framework |
| CFPB (2021) | Manufactured housing finance insights from HMDA | Financing landscape |
| CBRE (2024) | Interest rate cuts impact on CRE cap rates | Cap rate methodology |
| Fed FEDS Notes (2026-01-07) | Assessing recession risks with state-level data | State-level recession detection methodology |
| ECB Working Paper | How to predict financial stress using Markov switching | Markov chain methodology for regime detection |
| Columbia University | Conditional Markov chain application in economic analysis | Theoretical foundation for state-dependent transitions |

### Related Sunrise Skills and Documents

| Resource | Location | Relationship |
|----------|----------|-------------|
| MHP Operations Expert | `/.claude/skills/mhp-operations-expert/` | Property-level operational context |
| MHP Regulatory Expert | `/.claude/skills/mhp-regulatory/` | State-specific rent increase rules |
| RM Accounting Expert | `/.claude/skills/rm-accounting-expert/` | Revenue recognition, NOI calculation |
| Data Dictionary | `/Operations/data-pipeline-consolidation/DATA_DICTIONARY.md` | Canonical metric definitions |
| Strategic Blueprint | `/AI Implementation/Strategic Blueprint V2.pdf` | AI project alignment |
| Q1 2026 Rocks | `/Q1-2026-Rocks/Q1_2026_Rocks_SIMPLE.md` | Property Prescriptions Rock uses forecast data |

---

*Last updated: March 2026. Review trigger: quarterly model refresh, new model release, or significant economic state change. FRED series availability and API behavior should be verified before any automated pipeline changes.*