Add payout ratio, is the dividend covered by earnings

Dividend yield alone answers "how much", not "how safe" — a name can
carry a high yield precisely because the payout is unsustainable.
payout_ratio divides the dividend rate by trailing EPS, the same
question every income screen eventually asks: is this being paid out
of profit, or out of reserves. Null rather than a misleadingly small
positive number when the name is loss-making, matching the guard
eps_growth already uses on the same denominator.

Classified STATIC_SAFE alongside earnings_yield, whose denominator it
shares: both inputs are slow-moving fundamentals, not today's tape.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qxoe91wVDqAoyoJxhZ15Vf

Author: Ben05-sys

app/screen.py

@@ -37,7 +37,7 @@
            "rs_sector", "sector_change_pct",
            "dollar_volume", "avg_dollar_volume", "day_range_pct", "gap_pct",
            "true_range", "atr_pct", "sma_spread", "intraday_pct",
-           "earnings_yield", "eps_growth"]
+           "earnings_yield", "eps_growth", "payout_ratio"]
 COLUMNS = [n for n, _ in store.UNIVERSE_COLUMNS] + DERIVED
 
 TEXT_COLUMNS = {"symbol", "name", "sector", "industry", "country",
@@ -93,6 +93,10 @@
     # not with the tape — same drift tolerance as the `eps_ttm`/`eps_forward`
     # they're built from.
     "eps_growth",
+    # Dividend rate and trailing EPS are both slow-moving fundamentals, not
+    # today's tape — same drift tolerance as `earnings_yield`, whose
+    # denominator this shares.
+    "payout_ratio",
     # Average dollar volume is a liquidity floor, not a reading of the
     # tape: `avgdvol > 20m` means "this name normally trades enough to get
     # out of", and half a day of price drift does not change that answer.
@@ -113,6 +117,7 @@
     "eps": "eps_ttm", "fpe": "forward_pe", "pricetobook": "pb",
     "eyield": "earnings_yield", "earningsyield": "earnings_yield",
     "epsgrowth": "eps_growth", "growth": "eps_growth",
+    "payout": "payout_ratio", "payoutratio": "payout_ratio",
     "div": "dividend_yield", "divyield": "dividend_yield",
     "hi52": "week52_high", "lo52": "week52_low",
     "high52": "week52_high", "low52": "week52_low",

app/universe.py

@@ -384,6 +384,17 @@ def safe(a, b):
         df["peg"] = safe(df["pe"], df["eps_growth"].where(df["eps_growth"] > 0))
     else:
         df["peg"] = np.nan
+    # Payout ratio: the dividend as a percent of trailing EPS — is the
+    # dividend actually covered by earnings, or is it being paid out of
+    # reserves. Null rather than negative when the name is loss-making:
+    # dividing by a negative eps_ttm would flip the sign into a small
+    # positive-looking number that reads like a *safe*, well-covered payout
+    # when the truth is there is no earnings to cover it from at all.
+    if "dividend_rate" in df.columns and "eps_ttm" in df.columns:
+        df["payout_ratio"] = safe(df["dividend_rate"],
+                                   df["eps_ttm"].where(df["eps_ttm"] > 0)) * 100
+    else:
+        df["payout_ratio"] = np.nan
     # ADRs, from the security type Nasdaq puts in the name. Derived rather
     # than stored so it works on snapshots taken before the field existed —
     # `name` has always been there.

tests/test_screen.py

@@ -620,6 +620,27 @@ def when_for(hour, minute=0):
     check("peg tracks the same slow-moving inputs as pe and eps_growth, so it narrows safely stale",
           "peg" in screen.STATIC_SAFE and "peg" not in screen.LIVE_COLUMNS)
 
+    print("\npayout ratio")
+    pr = derive(pd.DataFrame({
+        "symbol": ["COVERED", "LOSER"], "name": ["C", "L"], "sector": ["T"] * 2,
+        "price": [50.0, 50.0], "change_pct": [0.0] * 2,
+        "volume": [1e6] * 2, "avg_volume_3m": [1e6] * 2, "market_cap": [1e9] * 2,
+        "week52_high": [60.0] * 2, "week52_low": [40.0] * 2,
+        "sma50": [50.0] * 2, "sma200": [50.0] * 2,
+        "eps_ttm": [4.0, -1.0], "dividend_rate": [1.0, 1.0],
+        "earnings_ts": [np.nan] * 2,
+    }))
+    prrow = dict(zip(pr["symbol"], pr.to_dict("records"), strict=True))
+    check("profitable name: payout is dividend over trailing eps, as a percent",
+          abs(prrow["COVERED"]["payout_ratio"] - 25.0) < 1e-9,
+          prrow["COVERED"]["payout_ratio"])
+    check("loss-making name: payout stays null rather than a fake positive number",
+          np.isnan(prrow["LOSER"]["payout_ratio"]), prrow["LOSER"]["payout_ratio"])
+    check("payout resolves", screen.resolve("payout") == "payout_ratio")
+    check("payout ratio tracks dividend and trailing eps, not price, so it narrows safely stale",
+          "payout_ratio" in screen.STATIC_SAFE
+          and "payout_ratio" not in screen.LIVE_COLUMNS)
+
     # Today's dollar volume only rises, so prefiltering on a stale one would
     # drop the names that have since crossed the line. The average is a
     # standing fact about the name and narrows safely.