Update app.py

app.py

@@ -4,6 +4,7 @@ import pandas_datareader.data as web
 import yfinance as yf
 import datetime
 import plotly.graph_objs as go
+import numpy as np
 
 # ---------- Page config (must be the first Streamlit call) ----------
 st.set_page_config(layout="wide")
@@ -46,6 +47,7 @@ with st.sidebar.expander("How to Use", expanded=False):
 
 st.sidebar.header("Select Indicators")
 with st.sidebar.expander("Indicators", expanded=True):
+    # Removed "Federal Funds Rate" per your request
     indicators = {
         'Sahm Recession Indicator': 'SAHMREALTIME',
         'U.S. Recession Probabilities': 'RECPROUSM156N',
@@ -53,7 +55,7 @@ with st.sidebar.expander("Indicators", expanded=True):
         'Stock Market (S&P 500)': 'SP500',          # Fetched from yfinance
         'VIX': 'VIX',                               # Fetched from yfinance
         'Treasury Rates': ('GS10', 'DGS2', 'DGS1MO', 'TB3MS'),
-        'Federal Funds Rate': 'FEDFUNDS',
+        # 'Federal Funds Rate': 'FEDFUNDS',         # <-- removed
         'Unemployment Rate': 'UNRATE',
         'Nonfarm Payrolls': 'PAYEMS',
         'Jobless Claims': 'ICSA',
@@ -65,7 +67,7 @@ with st.sidebar.expander("Indicators", expanded=True):
     }
     selected_indicators = {key: st.checkbox(key, value=True) for key in indicators.keys()}
 
-# Single Run button (no clear buttons)
+# Single Run button (no explicit "clear" — re-running implies clearing)
 if st.sidebar.button("Run Analysis"):
     st.session_state.run_analysis = True
 
@@ -92,6 +94,45 @@ crash_periods = {
     '2020-02-01': '2020-04-01'
 }
 
+# ---------- Helpers ----------
+def pct_rank(series: pd.Series, value: float) -> float:
+    s = pd.to_numeric(series, errors="coerce").dropna()
+    if s.empty or not np.isfinite(value):
+        return np.nan
+    return float((s < value).mean() * 100.0)
+
+def fmt_pct(x, decimals=1):
+    return "n/a" if pd.isna(x) else f"{x*100:.{decimals}f}%"
+
+def fmt_val(x, decimals=2):
+    return "n/a" if pd.isna(x) else f"{x:.{decimals}f}"
+
+def series_change(s: pd.Series, periods: int = 1, pct: bool = True):
+    if len(s) <= periods:
+        return np.nan
+    if pct:
+        return float((s.iloc[-1] / s.iloc[-(periods+1)] - 1.0))
+    else:
+        return float(s.iloc[-1] - s.iloc[-(periods+1)])
+
+def current_and_date(s: pd.Series):
+    if s is None or s.empty:
+        return np.nan, "n/a"
+    return float(s.iloc[-1]), s.index[-1].date().isoformat()
+
+def inversion_streak(series: pd.Series):
+    """Consecutive periods the series has been < 0 at the end of series."""
+    if series is None or series.dropna().empty:
+        return 0
+    v = (series < 0).astype(int).to_numpy()
+    streak = 0
+    for x in v[::-1]:
+        if x == 1:
+            streak += 1
+        else:
+            break
+    return streak
+
 # ---------- Cached data fetchers ----------
 @st.cache_data(ttl=6 * 60 * 60, show_spinner=False)
 def fetch_fred_series(series_code: str, start: datetime.datetime, end: datetime.datetime) -> pd.Series:
@@ -196,8 +237,8 @@ def finalize_layout(fig: go.Figure, title: str, ytitle: str):
         xaxis_title='Date',
         yaxis_title=ytitle,
         template='plotly_dark',                 # dark-friendly defaults
-        paper_bgcolor='rgba(0,0,0,0)',          # transparent to match Streamlit theme
-        plot_bgcolor='rgba(0,0,0,0)',           # transparent to match Streamlit theme
+        paper_bgcolor='rgba(0,0,0,0)',          # transparent to match theme background
+        plot_bgcolor='rgba(0,0,0,0)',           # transparent to match theme background
         font=dict(color="white"),
         xaxis=dict(
             tickformat="%Y",
@@ -243,6 +284,181 @@ def finalize_layout(fig: go.Figure, title: str, ytitle: str):
     )
     fig.update_traces(hovertemplate='%{x|%b %d, %Y}<br>%{y}<extra></extra>')
 
+# ---------- Interpretation blocks ----------
+def show_interpretation_for(key: str, column, data: pd.DataFrame):
+    with st.expander("Interpretation", expanded=False):
+        # Helper to write a bullet line
+        def blt(text): st.write(f"- {text}")
+
+        if key == 'Sahm Recession Indicator' and 'SAHMREALTIME' in data.columns:
+            s = data['SAHMREALTIME'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            ch_3 = series_change(s, 3, pct=False)
+            ma3 = s.rolling(3, min_periods=2).mean().iloc[-1] if len(s) else np.nan
+            blt(f"Latest reading ({d}): **{fmt_val(cur, 2)}**; historical percentile: **{fmt_val(pr,1)}**.")
+            blt("Rule-of-thumb threshold is **0.5** (dashed line in the chart). Values above this often coincide with recessions.")
+            if not pd.isna(ch_3):
+                blt(f"3-period change (approx. 3 months for monthly data): **{fmt_val(ch_3, 2)}** points.")
+            if not pd.isna(ma3):
+                blt(f"Trend check: the indicator is {'above' if cur>ma3 else 'below' if cur<ma3 else 'near'} its 3-period average.")
+            st.write("**How to read**: A sharp rise above 0.5 historically flags ongoing recessions; falling values suggest recovery.")
+
+        elif key == 'U.S. Recession Probabilities' and 'RECPROUSM156N' in data.columns:
+            s = data['RECPROUSM156N'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            ch_3 = series_change(s, 3, pct=False)
+            blt(f"Latest probability ({d}): **{fmt_val(cur, 1)}%**; historical percentile: **{fmt_val(pr,1)}**.")
+            if not pd.isna(ch_3):
+                blt(f"3-period change: **{fmt_val(ch_3,1)}** percentage points.")
+            blt("Sustained moves to elevated probabilities (e.g., >50%) tend to align with recession periods, but short spikes can be false alarms.")
+
+        elif key == 'Yield Spread (10Y - 2Y)' and 'Yield_Spread' in data.columns:
+            s = data['Yield_Spread'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            inv_streak = inversion_streak(s)
+            ch_3 = series_change(s, 3, pct=False)
+            blt(f"Latest spread ({d}): **{fmt_val(cur,2)} pp**; historical percentile: **{fmt_val(pr,1)}**.")
+            if cur < 0:
+                blt(f"**Inversion** is active (10Y < 2Y). Current inversion streak: **{inv_streak}** observations.")
+            else:
+                blt("Curve is **not inverted** currently.")
+            if not pd.isna(ch_3):
+                blt(f"3-period change: **{fmt_val(ch_3,2)}** pp.")
+            st.write("**How to read**: Deep or persistent inversion often precedes recessions by several months; steepening from very negative levels can signal normalization.")
+
+        elif key == 'Stock Market (S&P 500)' and 'SP500' in data.columns:
+            s = data['SP500'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            r_21 = series_change(s, 21, pct=True)
+            r_63 = series_change(s, 63, pct=True)
+            r_252 = series_change(s, 252, pct=True)
+            rolling_max = s.cummax()
+            drawdown = float(s.iloc[-1] / rolling_max.iloc[-1] - 1.0) if len(s) else np.nan
+            vol20 = float(s.pct_change().rolling(20).std(ddof=0).iloc[-1] * np.sqrt(252)) if len(s) >= 20 else np.nan
+            blt(f"Last close ({d}): **{fmt_val(cur,2)}**; percentile vs history: **{fmt_val(pr,1)}**.")
+            blt(f"Returns — 1m: **{fmt_pct(r_21)}**, 3m: **{fmt_pct(r_63)}**, 12m: **{fmt_pct(r_252)}**.")
+            if not pd.isna(drawdown):
+                blt(f"Drawdown from peak: **{fmt_pct(drawdown)}**.")
+            if not pd.isna(vol20):
+                blt(f"Realized vol (20d, annualized): **{fmt_pct(vol20)}**.")
+            st.write("**How to read**: Equity weakness often leads or coincides with recessions; watch for persistent downtrends and elevated volatility near shaded bands.")
+
+        elif key == 'VIX' and 'VIX' in data.columns:
+            s = data['VIX'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            m20 = float(s.rolling(20).mean().iloc[-1]) if len(s) >= 20 else np.nan
+            m60 = float(s.rolling(60).mean().iloc[-1]) if len(s) >= 60 else np.nan
+            blt(f"Latest VIX ({d}): **{fmt_val(cur,2)}**; percentile vs history: **{fmt_val(pr,1)}**.")
+            if not pd.isna(m20):
+                blt(f"Position vs 20-day avg: **{('above' if cur>m20 else 'below' if cur<m20 else 'near')}** ({fmt_val(m20,2)}).")
+            if not pd.isna(m60):
+                blt(f"Position vs 60-day avg: **{('above' if cur>m60 else 'below' if cur<m60 else 'near')}** ({fmt_val(m60,2)}).")
+            st.write("**How to read**: High percentiles indicate stress; falling VIX from high levels can mark stabilization, while spikes from low levels often accompany drawdowns.")
+
+        elif key == 'Treasury Rates':
+            cols = [c for c in ['GS10', 'DGS2', 'TB3MS', 'DGS1MO'] if c in data.columns]
+            if cols:
+                latests = {c: current_and_date(data[c].dropna())[0] for c in cols}
+                # Spread diagnostics if available
+                s_10_2 = data['GS10'] - data['DGS2'] if {'GS10', 'DGS2'}.issubset(data.columns) else None
+                s_10_3m = data['GS10'] - data['TB3MS'] if {'GS10', 'TB3MS'}.issubset(data.columns) else None
+                blt("Latest yields (percent): " + ", ".join([f"**{k}={fmt_val(v,2)}**" for k, v in latests.items() if not pd.isna(v)]))
+                if s_10_2 is not None:
+                    cur = float(s_10_2.dropna().iloc[-1])
+                    blt(f"10Y−2Y spread: **{fmt_val(cur,2)} pp** ({'inverted' if cur<0 else 'normal'}).")
+                if s_10_3m is not None:
+                    cur = float(s_10_3m.dropna().iloc[-1])
+                    blt(f"10Y−3M spread: **{fmt_val(cur,2)} pp** ({'inverted' if cur<0 else 'normal'}).")
+                st.write("**How to read**: Rising short rates vs long rates flatten/invert the curve. Inversions often precede recessions; re-steepening from very negative levels can precede recoveries.")
+
+        elif key == 'Unemployment Rate' and 'UNRATE' in data.columns:
+            s = data['UNRATE'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            ch_3 = series_change(s, 3, pct=False)
+            ch_12 = series_change(s, 12, pct=False)
+            blt(f"Latest unemployment ({d}): **{fmt_val(cur,2)}%**; percentile vs history: **{fmt_val(pr,1)}**.")
+            if not pd.isna(ch_3): blt(f"Change over 3 periods: **{fmt_val(ch_3,2)} pp**.")
+            if not pd.isna(ch_12): blt(f"Change over 12 periods: **{fmt_val(ch_12,2)} pp**.")
+            st.write("**How to read**: Rapid rises often occur around recessions; peaks typically lag recession start dates.")
+
+        elif key == 'Nonfarm Payrolls' and 'PAYEMS' in data.columns:
+            s = data['PAYEMS'].dropna()
+            cur, d = current_and_date(s)
+            ch_1 = series_change(s, 1, pct=False)
+            ch_3 = series_change(s, 3, pct=False)
+            yoy = series_change(s, 12, pct=True)
+            blt(f"Latest payrolls ({d}): **{fmt_val(cur,0)}k jobs**.")
+            if not pd.isna(ch_1): blt(f"1-period change: **{fmt_val(ch_1,0)}k**.")
+            if not pd.isna(ch_3): blt(f"3-period change: **{fmt_val(ch_3,0)}k**.")
+            if not pd.isna(yoy):  blt(f"12-period growth: **{fmt_pct(yoy)}**.")
+            st.write("**How to read**: Payroll growth slows before and during recessions; contractions are strong signals of broad weakness.")
+
+        elif key == 'Jobless Claims' and 'ICSA' in data.columns:
+            s = data['ICSA'].dropna()
+            cur, d = current_and_date(s)
+            ma4 = float(s.rolling(4).mean().iloc[-1]) if len(s) >= 4 else np.nan
+            yoy = series_change(s, 52, pct=True)  # weekly series (approx.)
+            blt(f"Latest claims ({d}): **{fmt_val(cur,0)}**; 4-wk avg: **{fmt_val(ma4,0)}**.")
+            if not pd.isna(yoy): blt(f"YoY change (approx.): **{fmt_pct(yoy)}**.")
+            st.write("**How to read**: Persistent uptrends in the 4-week average often precede rising unemployment and recessions.")
+
+        elif key == 'Retail Sales' and 'RSXFS' in data.columns:
+            s = data['RSXFS'].dropna()
+            cur, d = current_and_date(s)
+            mom = series_change(s, 1, pct=True)
+            qoq = series_change(s, 3, pct=True)
+            yoy = series_change(s, 12, pct=True)
+            blt(f"Latest ({d}): **{fmt_val(cur,2)}** (index). MoM: **{fmt_pct(mom)}**, QoQ: **{fmt_pct(qoq)}**, YoY: **{fmt_pct(yoy)}**.")
+            st.write("**How to read**: Retail sales proxy consumption strength; broad slowdowns or contractions often align with late-cycle and recessionary phases.")
+
+        elif key == 'Industrial Production' and 'INDPRO' in data.columns:
+            s = data['INDPRO'].dropna()
+            pct = data.get('INDPRO_PCT', pd.Series(dtype='float64')).dropna()
+            cur, d = current_and_date(s)
+            yoy = series_change(s, 12, pct=True)
+            blt(f"Level ({d}): **{fmt_val(cur,2)}** (index). YoY: **{fmt_pct(yoy)}**.")
+            if not pct.empty:
+                blt(f"Latest monthly change: **{fmt_val(pct.iloc[-1],2)}%**; average over last 6m: **{fmt_val(pct.tail(6).mean(),2)}%**.")
+            st.write("**How to read**: Production falls and negative monthly prints tend to cluster near recessions; rebounds suggest early recovery.")
+
+        elif key == 'Housing Starts' and 'HOUST' in data.columns:
+            s = data['HOUST'].dropna()
+            cur, d = current_and_date(s)
+            mom = series_change(s, 1, pct=True)
+            yoy = series_change(s, 12, pct=True)
+            blt(f"Latest starts ({d}): **{fmt_val(cur,0)}k** (annualized). MoM: **{fmt_pct(mom)}**, YoY: **{fmt_pct(yoy)}**.")
+            st.write("**How to read**: Housing is interest-rate sensitive and typically weakens well before recessions; stabilization often leads broader upturns.")
+
+        elif key == 'Consumer Confidence' and 'UMCSENT' in data.columns:
+            s = data['UMCSENT'].dropna()
+            cur, d = current_and_date(s)
+            pr = pct_rank(s, cur)
+            mom = series_change(s, 1, pct=False)
+            yoy = series_change(s, 12, pct=False)
+            blt(f"Latest sentiment ({d}): **{fmt_val(cur,1)}**; percentile vs history: **{fmt_val(pr,1)}**.")
+            if not pd.isna(mom): blt(f"1-period change: **{fmt_val(mom,1)}** points.")
+            if not pd.isna(yoy): blt(f"12-period change: **{fmt_val(yoy,1)}** points.")
+            st.write("**How to read**: Collapses in sentiment often occur around recessions; recovering sentiment can confirm early-cycle improvement.")
+
+        elif key == 'Inflation (CPI)' and 'CPIAUCSL' in data.columns:
+            s = data['CPIAUCSL'].dropna()
+            mom = data.get('CPIAUCSL_PCT', pd.Series(dtype='float64')).dropna()
+            cur, d = current_and_date(s)
+            yoy = series_change(s, 12, pct=True)
+            blt(f"CPI level ({d}): **{fmt_val(cur,1)}** (index). YoY: **{fmt_pct(yoy)}**.")
+            if not mom.empty:
+                blt(f"Latest month-over-month change: **{fmt_val(mom.iloc[-1],2)}%**; 3-month average: **{fmt_val(mom.tail(3).mean(),2)}%**.")
+            st.write("**How to read**: Cooling inflation eases pressure on policy and supports soft-landing scenarios; re-acceleration risks tighter financial conditions.")
+
+        else:
+            st.write("No interpretation available for this selection (insufficient data).")
+
 # ---------- Main render ----------
 if st.session_state.run_analysis:
     with st.spinner("Fetching data and building charts..."):
@@ -321,7 +537,7 @@ if st.session_state.run_analysis:
                     fig.add_trace(go.Scatter(
                         x=combined_data.index, y=combined_data[column], mode='lines', name=key
                     ))
-                    if column == 'SAHMREALTIME':
+                    if key == 'Sahm Recession Indicator':
                         fig.add_hline(
                             y=0.5, line=dict(color="#ff6b6b", dash="dash"),
                             annotation_text="Recession Threshold",
@@ -339,6 +555,8 @@ if st.session_state.run_analysis:
             # Only render if we actually added something beyond the shading
             if fig.data:
                 st.plotly_chart(fig, use_container_width=True)
+                # --- Interpretation for this panel ---
+                show_interpretation_for(key, column, combined_data)
 
 # ---------- Hide default Streamlit branding ----------
 hide_streamlit_style = """