Validation & Reproducibility

"""
NIV (National Impact Velocity) Calculator
Reproduce the NIV formula using FRED data
"""

import pandas as pd
import numpy as np
from fredapi import Fred

# Get your free API key at: https://fred.stlouisfed.org/docs/api/api_key.html
fred = Fred(api_key='YOUR_FRED_API_KEY')

# Fetch required FRED series
series = {
    'GPDIC1': fred.get_series('GPDIC1'),      # Private Investment
    'M2SL': fred.get_series('M2SL'),          # M2 Money Supply
    'FEDFUNDS': fred.get_series('FEDFUNDS'),  # Federal Funds Rate
    'GDPC1': fred.get_series('GDPC1'),        # Real GDP
    'TCU': fred.get_series('TCU'),            # Capacity Utilization
    'T10Y3M': fred.get_series('T10Y3M'),      # Yield Spread
    'CPIAUCSL': fred.get_series('CPIAUCSL'),  # CPI
}

# Merge into monthly DataFrame (forward-fill quarterly data)
df = pd.DataFrame(series).resample('M').last().ffill()

# Calculate components
def calculate_niv(df, eta=1.5, epsilon=0.001):
    results = []

    for i in range(12, len(df)):
        curr = df.iloc[i]
        prev = df.iloc[i-1]
        year_ago = df.iloc[i-12]

        # Skip if missing data
        if pd.isna([curr['GPDIC1'], curr['M2SL'], curr['FEDFUNDS'],
                    curr['GDPC1'], curr['TCU'], curr['CPIAUCSL']]).any():
            continue

        # 1. THRUST (u)
        dG = (curr['GPDIC1'] - year_ago['GPDIC1']) / year_ago['GPDIC1']  # Investment YoY
        dA = (curr['M2SL'] - year_ago['M2SL']) / year_ago['M2SL']        # M2 YoY
        dr = curr['FEDFUNDS'] - prev['FEDFUNDS']                          # Rate change
        thrust = np.tanh(1.0 * dG + 1.0 * dA - 0.7 * dr)

        # 2. EFFICIENCY (P)
        efficiency = (curr['GPDIC1'] * 1.15) / curr['GDPC1']
        efficiency_sq = efficiency ** 2

        # 3. SLACK (X)
        slack = 1.0 - (curr['TCU'] / 100.0)

        # 4. DRAG (F)
        inflation = (curr['CPIAUCSL'] - year_ago['CPIAUCSL']) / year_ago['CPIAUCSL']
        spread = curr.get('T10Y3M', 0) or 0
        yield_penalty = abs(spread / 100) if spread < 0 else 0
        real_rate = max(0, (curr['FEDFUNDS'] / 100) - inflation)

        # 12-month Fed Funds volatility
        fed_window = df.iloc[i-11:i+1]['FEDFUNDS']
        volatility = fed_window.std() / 100

        drag = 0.4 * yield_penalty + 0.4 * real_rate + 0.2 * volatility

        # 5. MASTER FORMULA
        numerator = thrust * efficiency_sq
        safe_base = max(slack + drag, epsilon)
        denominator = safe_base ** eta
        niv = numerator / denominator

        results.append({
            'date': df.index[i],
            'thrust': thrust,
            'efficiency': efficiency,
            'slack': slack,
            'drag': drag,
            'niv': niv
        })

    return pd.DataFrame(results)

# Run calculation
niv_results = calculate_niv(df)
print(niv_results.tail(10))

# Compare with dashboard values
print("\n--- Latest NIV Value ---")
print(f"NIV Score: {niv_results.iloc[-1]['niv'] * 100:.2f}")

=== Excel Reproduction Steps ===

1. DOWNLOAD FRED DATA
   - Go to https://fred.stlouisfed.org
   - Download each series (GPDIC1, M2SL, FEDFUNDS, GDPC1, TCU, T10Y3M, CPIAUCSL)
   - Merge into one sheet by date

2. CALCULATE GROWTH RATES (Column H onwards)
   Investment YoY (dG):  =IF(A14<>"", (B14-B2)/B2, "")
   M2 YoY (dA):          =IF(A14<>"", (C14-C2)/C2, "")
   Rate Change (dr):     =D14-D13

3. CALCULATE COMPONENTS
   Thrust (u):      =TANH(H14 + I14 - 0.7*J14)
   Efficiency (P):  =(B14 * 1.15) / E14
   Slack (X):       =1 - (F14 / 100)

4. CALCULATE DRAG
   Inflation:       =(G14 - G2) / G2
   Yield Penalty:   =IF(G14<0, ABS(G14)/100, 0)
   Real Rate:       =MAX(0, D14/100 - [Inflation])
   Volatility:      =STDEV(D3:D14) / 100
   Drag (F):        =0.4*[YieldPen] + 0.4*[RealRate] + 0.2*[Vol]

5. FINAL NIV FORMULA
   NIV = (Thrust * Efficiency^2) / (Slack + Drag)^1.5

   Cell formula:
   =[Thrust] * [Efficiency]^2 / MAX([Slack]+[Drag], 0.001)^1.5