pitbacktest 0.2.0__tar.gz → 0.2.1__tar.gz

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pitbacktest
-Version: 0.2.0
+Version: 0.2.1
 Summary: Backtest harness for factor screening, event signals and portfolio alphas, built to make common backtest errors hard
 Author: Janghyuk Choi
 License-Expression: MIT

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/__init__.py

@@ -22,6 +22,6 @@ from .ledger import Ledger
 from .weights import backtest_weights, capacity_curve, ImpactModel
 from .shorting import shortable_from_bans
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 __all__ = ["shortable_from_bans", "execution", "validation", "analytics", "Ledger", "backtest_weights", "capacity_curve", "ImpactModel", "Panel", "build_pit_eligible", "GateConfig", "screen",
            "backtest_event", "backtest_portfolio", "assert_timing"]

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/core/panel.py

@@ -14,6 +14,7 @@ Timing convention (the only one used in the whole project)
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field, replace
 from typing import Iterable
 
@@ -63,6 +64,17 @@ class Panel:
         self.close = self.close.sort_index()
         if self.close.index.has_duplicates:                    # before any reindex, which would fail with a less helpful pandas message
             raise ValueError("close.index has duplicate dates")
+        if self.close.columns.has_duplicates:
+            dup = list(self.close.columns[self.close.columns.duplicated()][:3])
+            raise ValueError(f"close has duplicate ticker names (for example {dup}): a reindex by name would pick the wrong column")
+        px = self.close.to_numpy(dtype=np.float64, na_value=np.nan)
+        badpx = ~np.isnan(px) & ~(np.isfinite(px) & (px > 0))      # zero, negative and infinite prices (a halted name written as 0 by a vendor)
+        if badpx.any():
+            i, j = np.argwhere(badpx)[0]
+            warnings.warn(f"{int(badpx.sum())} prices are zero, negative or infinite (first: {self.close.columns[j]} on {self.close.index[i].date()}, value {px[i, j]!r}); "
+                          "they are treated as missing. Left in, a zero price makes a return of -100% followed by an infinite one", stacklevel=3)
+            self.close = self.close.where(~pd.DataFrame(badpx, index=self.close.index, columns=self.close.columns))
+        self._check_periods_per_year()
         self.eligible = self.eligible.reindex(
             index=self.close.index, columns=self.close.columns
         ).fillna(False).astype(bool)
@@ -82,6 +94,19 @@ class Panel:
                 setattr(self, k, v.reindex(index=self.close.index, columns=self.close.columns).fillna(False).astype(bool))
         self.validate()
 
+    def _check_periods_per_year(self) -> None:
+        """Warn when `periods_per_year` does not fit the spacing of the dates (weekly dates with the default 252 annualise by the wrong factor)."""
+        if len(self.close.index) < 3:
+            return
+        gap = self.close.index.to_series().diff().dropna().median()
+        if not gap or gap <= pd.Timedelta(0):
+            return
+        implied = pd.Timedelta(days=365.25) / gap
+        ratio = self.periods_per_year / implied
+        if ratio > 2.0 or ratio < 0.5:
+            warnings.warn(f"the dates are about {gap} apart (roughly {implied:.0f} bars a year) but periods_per_year={self.periods_per_year}: CAGR, Sharpe and "
+                          "volatility are annualised by that number, so set periods_per_year to the real number of bars in a year (52 for weekly, 12 for monthly)", stacklevel=3)
+
     def validate(self) -> None:
         """Raise ValueError if the panel breaks its invariants: the date index ascending and without duplicates, at least one eligible
         security, `entry_lag` not negative, and at least 10 eligible securities on half of the dates or more. Runs on construction."""
@@ -304,3 +329,19 @@ def build_pit_eligible(close: pd.DataFrame, *, listed: pd.DataFrame | None = Non
     if exclude is not None:
         ok &= ~exclude.reindex_like(close).fillna(False).astype(bool)
     return ok.fillna(False)
+
+
+def check_alignment(panel: Panel, x, what: str) -> None:
+    """Refuse an input table whose dates or tickers do not line up with the panel, and warn when only part of it does.
+
+    The engines align a signal to the panel by label, and a label that is missing becomes NaN. A factor with other column names, transposed, or with a
+    different time zone then aligned to nothing, every score was NaN, no position was ever taken, and the result was an unremarkable Sharpe of 0.0."""
+    if not isinstance(x, pd.DataFrame):
+        raise ValueError(f"{what} must be a pandas DataFrame of dates x tickers, got {type(x).__name__}")
+    d_share = float(panel.dates.isin(x.index).mean())
+    t_share = float(panel.tickers.isin(x.columns).mean())
+    if d_share == 0.0 or t_share == 0.0:
+        raise ValueError(f"{what} has no date or no ticker in common with the panel (dates in common: {d_share:.0%}, tickers in common: {t_share:.0%}). "
+                         "Check that it is dates x tickers (not transposed), uses the same ticker names, and the same time zone handling as the panel")
+    if d_share < 0.5 or t_share < 0.5:
+        warnings.warn(f"{what} covers only {d_share:.0%} of the panel's dates and {t_share:.0%} of its tickers; the rest count as missing", stacklevel=3)

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/event.py

@@ -23,7 +23,7 @@ import pandas as pd
 from .core.controls import build_controls, xs_norm
 from .core.estimators import fama_macbeth, newey_west_t, paired_diff
 from .core.gates import GateConfig, fire_structure, run_gates
-from .core.panel import Panel
+from .core.panel import Panel, check_alignment
 
 
 @dataclass
@@ -113,6 +113,7 @@ def backtest_event(panel: Panel, signal: pd.DataFrame, *,
         raise ValueError(f"horizons must be whole numbers of periods, at least 1, got {horizons!r}")
     if not (cost_bp >= 0 and np.isfinite(cost_bp)):
         raise ValueError(f"cost_bp must be finite and not negative, got {cost_bp!r}")
+    check_alignment(panel, signal, "signal")
     sig = signal.reindex(index=panel.dates, columns=panel.tickers).fillna(False)
     fire = (sig.astype(bool) & panel.eligible).values
     ev = panel.eligible.values

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/portfolio.py

@@ -20,7 +20,7 @@ import numpy as np
 import pandas as pd
 
 from .core.costs import apply_side_cost, apply_turnover_cost, side_cost_input, turnover
-from .core.panel import Panel
+from .core.panel import Panel, check_alignment
 from .execution import check_freeze_return, exec_masks, freeze_hits, realize
 
 ANN = 252
@@ -83,6 +83,20 @@ def _normalize(mask_or_w: np.ndarray) -> np.ndarray:
     return np.where(np.isfinite(s), w / s, 0.0)
 
 
+def stop_at_ruin(net: np.ndarray, cut: int) -> tuple[np.ndarray, int | None]:
+    """An account that loses 100 percent or more in a day is gone: from the first such day (within the first `cut` rows) the return is -100 percent and
+    every later return is 0. Without this, compounding goes on with negative equity (a 30x long that falls 4 percent), and CAGR, drawdown and Sharpe describe an
+    account that could not exist (a real one is liquidated first). Returns the series and the row of the ruin, None when there is none. The input is not changed."""
+    bad = np.flatnonzero(np.asarray(net[:cut]) <= -1.0)
+    if bad.size == 0:
+        return net, None
+    i = int(bad[0])
+    out = np.array(net, dtype=np.float64, copy=True)
+    out[i] = -1.0
+    out[i + 1:] = 0.0
+    return out, i
+
+
 def metrics(net: np.ndarray, dates: pd.DatetimeIndex, ann: int = ANN) -> dict:
     """Annualised figures of a net return series: CAGR, MDD, Sharpe, Sortino (downside deviation, target 0), Calmar, vol, years, the share of
     positive days and the drawdown dates. With fewer than `ann // 2` observations it warns and returns NaN for CAGR, MDD and Sharpe only."""
@@ -118,7 +132,13 @@ def _forward_arrays(panel: Panel, funding: bool, delist_return: float | None):
     fwdf[d]      funding rate over the same day (0 unless `funding` and the panel has it); positive means longs pay
     hit_next[d]  True where that day is the delisting day
     The last lag + 1 rows of fwd and fwdf are 0: their holding period is not in the sample."""
-    ret = np.nan_to_num(panel.ret1().values.astype(np.float64), nan=0.0)
+    ret = panel.ret1().values.astype(np.float64)
+    big = (ret > 10.0) & panel.eligible.to_numpy()
+    if big.any():
+        i, j = np.unravel_index(np.argmax(np.where(big, ret, -np.inf)), ret.shape)
+        warnings.warn(f"{int(big.sum())} daily moves above +1000% on eligible securities (largest: {panel.tickers[j]} on {panel.dates[i].date()}, {ret[i, j]:+.0%}); "
+                      "they are taken at face value. Look for an unadjusted split or consolidation or a bad price before believing the result", stacklevel=3)
+    ret = np.nan_to_num(ret, nan=0.0)
     nxt = np.zeros(ret.shape, dtype=bool)
     if panel.delist_after is not None:
         da = panel.delist_after.reindex(index=panel.dates, columns=panel.tickers).fillna(False).values.astype(bool)
@@ -169,6 +189,8 @@ def _check_portfolio_args(factor, long_q, short_q, hold, weighting, spread_bp, b
         raise ValueError(f"long_q must be in (0, 1], got {long_q!r}")
     if short_q is not None and not (0 < short_q <= 1):
         raise ValueError(f"short_q must be in (0, 1], or None for a long-only portfolio, got {short_q!r}")
+    if short_q is not None and long_q + short_q > 1.0 + 1e-12:
+        raise ValueError(f"long_q + short_q = {long_q + short_q:g} is above 1: the same security would sit in both legs (long_q={long_q!r}, short_q={short_q!r})")
     if isinstance(hold, bool) or not isinstance(hold, (int, np.integer)) or hold < 1:
         raise ValueError(f"hold must be a whole number of periods, at least 1, got {hold!r}")
     _check_cost(spread_bp, "spread_bp")
@@ -229,6 +251,7 @@ def backtest_portfolio(panel: Panel, factor: pd.DataFrame, *,
     freeze_return = check_freeze_return(freeze_return)
     bb = side_cost_input(buy_bp, panel.dates, panel.tickers, "buy_bp")
     sb = side_cost_input(sell_bp, panel.dates, panel.tickers, "sell_bp")
+    check_alignment(panel, factor, "factor")
     f = factor.reindex(index=panel.dates, columns=panel.tickers)
     el = panel.eligible
     rk = f.where(el).rank(axis=1, pct=True, na_option="keep")
@@ -289,10 +312,15 @@ def backtest_portfolio(panel: Panel, factor: pd.DataFrame, *,
     net = gross - cost - fcost
 
     cut = len(panel.dates) - (panel.entry_lag + 1)
+    net, ruin = stop_at_ruin(net, cut)
+    if ruin is not None:
+        warnings.warn(f"the account lost 100% or more on {panel.dates[ruin].date()}: from that day the return is -100% and then 0 (a leveraged account would have been liquidated); read CAGR and drawdown, not Sharpe, which no longer describes an account", stacklevel=2)
     m = metrics(net[:cut], panel.dates, panel.periods_per_year)
+    m["ruined"] = ruin is not None
+    m["ruin_date"] = None if ruin is None else str(panel.dates[ruin].date())
     m["turnover_daily"] = float(turn[:cut].mean())
     m["cost_annual_bp"] = float(cost[:cut].mean() * panel.periods_per_year * 1e4)
-    m["gross_CAGR"] = metrics(gross[:cut], panel.dates, panel.periods_per_year)["CAGR"]
+    m["gross_CAGR"] = metrics(stop_at_ruin(gross, cut)[0][:cut], panel.dates, panel.periods_per_year)["CAGR"]
     if fz is not None:
         m["freeze_markdown_annual_bp"] = float(mark[:cut].mean() * panel.periods_per_year * 1e4)        # negative: the return given up
         m["freeze_markdown_events"] = int(((hl > 0) & fz)[:cut].sum())
@@ -309,7 +337,11 @@ def backtest_portfolio(panel: Panel, factor: pd.DataFrame, *,
         m["short_leg_empty_days"] = int((el.to_numpy(bool).any(axis=1) & ~el_s.to_numpy(bool).any(axis=1))[:cut].sum())   # eligible names exist, none can be sold short
     m["funding_annual_bp"] = float(fcost[:cut].mean() * panel.periods_per_year * 1e4)   # positive = a cost
     m["delist_events_held"] = int((held & hit_next)[:cut].sum())
-    m["avg_positions"] = float((hl > 0).sum(axis=1)[(hl > 0).sum(axis=1) > 0].mean())
+    npos = (hl > 0).sum(axis=1)
+    m["avg_positions"] = float(npos[npos > 0].mean()) if (npos > 0).any() else float("nan")
+    if not (npos > 0).any():
+        warnings.warn("no position was held on any day: the factor gave no usable score on eligible securities (all NaN, no ranking, or the legs came out empty), "
+                      "so the zero return below is not a result", stacklevel=2)
 
     bench = bexc = None
     bret = None

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/screen.py

@@ -23,7 +23,7 @@ from .core.controls import build_controls, neutralize, xs_norm
 from .core.estimators import (decile_profile, fama_macbeth, newey_west_t,
                               shuffle_columns, shuffle_null)
 from .core.gates import GateConfig, fire_structure, run_gates
-from .core.panel import Panel
+from .core.panel import Panel, check_alignment
 
 
 @dataclass
@@ -103,6 +103,7 @@ def screen(panel: Panel, factors: dict[str, pd.DataFrame], *,
 
     rows, detail = [], {}
     for name, raw in factors.items():
+        check_alignment(panel, raw, f"factor {name!r}")
         f = xs_norm(raw.reindex(index=panel.dates, columns=panel.tickers), el)
         fm = fama_macbeth(f, fwd, ctrl, el)
         rk = f.rank(axis=1, pct=True, na_option="keep")

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/validation.py

@@ -36,8 +36,12 @@ def deflated_sharpe(R: np.ndarray, *, trials: int | None = None, periods_per_yea
     variants you did not keep in R (and say so honestly)."""
     R = np.asarray(R, dtype=np.float64)
     T, n = R.shape
-    sr_all = R.mean(axis=0) / R.std(axis=0, ddof=1)
-    j = int(np.nanargmax(sr_all))
+    with np.errstate(invalid="ignore", divide="ignore"):
+        sr_all = R.mean(axis=0) / R.std(axis=0, ddof=1)
+    if not np.isfinite(sr_all).any():
+        raise ValueError("no column of R has a usable Sharpe ratio: every column contains NaN or inf, or has zero variance (a strategy that never traded). "
+                         "Columns with a NaN are ignored, so drop or fill the NaN rows if all of them have one")
+    j = int(np.nanargmax(np.where(np.isfinite(sr_all), sr_all, np.nan)))
     x = R[:, j]
     sr = float(sr_all[j])
     z = (x - x.mean()) / x.std(ddof=0)

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest/weights.py

@@ -39,21 +39,22 @@ If `panel.shortable` is given, opening or increasing a short in a security that
 """
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
 
 import numpy as np
 import pandas as pd
 
 from .core.costs import apply_side_cost, apply_turnover_cost, side_cost_input
-from .core.panel import Panel
+from .core.panel import Panel, check_alignment
 from .execution import check_freeze_return, exec_masks, freeze_hits, realize
-from .portfolio import (PortfolioResult, _benchmark_returns, _check_benchmark, _check_cost, _forward_arrays, _side_config,
+from .portfolio import (PortfolioResult, _benchmark_returns, _check_benchmark, _check_cost, _forward_arrays, _side_config, stop_at_ruin,
                         _side_label, metrics)
 
 
 @dataclass(frozen=True)
 class ImpactModel:
-    aum: float                 # dollars of capital
+    aum: float                 # money, in the currency of close x volume (dollars for US stocks and USDT contracts, won for KRX); participation = trade x aum / ADV
     y: float = 1.0             # coefficient of the square-root law
     vol_window: int = 20
     adv_window: int = 30
@@ -61,7 +62,7 @@ class ImpactModel:
 
     def __post_init__(self) -> None:
         if not (self.aum >= 0 and np.isfinite(self.aum)):
-            raise ValueError(f"aum must be a finite number of dollars, not negative, got {self.aum!r}")
+            raise ValueError(f"aum must be a finite amount of money (same currency as close x volume), not negative, got {self.aum!r}")
         if not (self.y >= 0 and np.isfinite(self.y)):
             raise ValueError(f"y must be finite and not negative, got {self.y!r}")
         if self.vol_window < 2 or self.adv_window < 1:
@@ -117,6 +118,7 @@ def backtest_weights(panel: Panel, weights: pd.DataFrame, *, spread_bp=0.0, buy_
     freeze_return = check_freeze_return(freeze_return)
     bb = side_cost_input(buy_bp, panel.dates, panel.tickers, "buy_bp")
     sb = side_cost_input(sell_bp, panel.dates, panel.tickers, "sell_bp")
+    check_alignment(panel, weights, "weights")
     W = weights.reindex(index=panel.dates, columns=panel.tickers)
     raw = W.to_numpy(float)
     if np.isinf(raw).any():
@@ -188,10 +190,18 @@ def backtest_weights(panel: Panel, weights: pd.DataFrame, *, spread_bp=0.0, buy_
     net = gross - spread - side - borrow - imp - fcost
 
     ppy = panel.periods_per_year
+    net, ruin = stop_at_ruin(net, cut)
+    if ruin is not None:
+        warnings.warn(f"the account lost 100% or more on {panel.dates[ruin].date()}: from that day the return is -100% and then 0 (a leveraged account would have been liquidated)", stacklevel=2)
     m = metrics(net[:cut], panel.dates, ppy)
+    m["ruined"] = ruin is not None
+    if float(np.abs(H[:cut]).sum()) == 0.0:
+        warnings.warn("no position was held on any day: the weights are all zero or NaN, or `capital` is too small to buy one lot of anything; "
+                      "the zero return is not a result", stacklevel=2)
+    m["ruin_date"] = None if ruin is None else str(panel.dates[ruin].date())
     tr = np.zeros_like(H)
     tr[1:] = np.abs(np.diff(H, axis=0))
-    m.update({"turnover_daily": float(0.5 * tr[:cut].sum(axis=1).mean()), "gross_CAGR": metrics(gross[:cut], panel.dates, ppy)["CAGR"],
+    m.update({"turnover_daily": float(0.5 * tr[:cut].sum(axis=1).mean()), "gross_CAGR": metrics(stop_at_ruin(gross, cut)[0][:cut], panel.dates, ppy)["CAGR"],
               "spread_annual_bp": float(spread[:cut].mean() * ppy * 1e4), "borrow_annual_bp": float(borrow[:cut].mean() * ppy * 1e4),
               "side_cost_annual_bp": float(side[:cut].mean() * ppy * 1e4),
               "impact_annual_bp": float(imp[:cut].mean() * ppy * 1e4), "funding_annual_bp": float(fcost[:cut].mean() * ppy * 1e4),

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pitbacktest
-Version: 0.2.0
+Version: 0.2.1
 Summary: Backtest harness for factor screening, event signals and portfolio alphas, built to make common backtest errors hard
 Author: Janghyuk Choi
 License-Expression: MIT

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pitbacktest.egg-info/SOURCES.txt

@@ -46,11 +46,13 @@ tests/test_delisting_and_guards.py
 tests/test_docs_scripts.py
 tests/test_equity.py
 tests/test_execution.py
+tests/test_hardening_021.py
 tests/test_intraday.py
 tests/test_krx.py
 tests/test_ledger.py
 tests/test_packaging.py
 tests/test_reconcile.py
+tests/test_ruin.py
 tests/test_side_costs_shorting.py
 tests/test_symbol_rules.py
 tests/test_synthetic.py

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pitbacktest"
-version = "0.2.0"
+version = "0.2.1"
 description = "Backtest harness for factor screening, event signals and portfolio alphas, built to make common backtest errors hard"
 readme = "README.md"
 license = "MIT"

{pitbacktest-0.2.0 → pitbacktest-0.2.1}/tests/test_argument_checks.py

@@ -43,6 +43,7 @@ def test_portfolio_arguments():
     _raises(lambda: run(long_q=float("nan")), "long_q")
     _raises(lambda: run(short_q=0.0), "short_q", "None for a long-only")
     _raises(lambda: run(short_q=-0.1), "short_q")
+    _raises(lambda: run(long_q=0.7, short_q=0.7), "long_q + short_q", "both legs")       # the same security long and short at once
     _raises(lambda: run(hold=0), "hold")
     _raises(lambda: run(hold=2.5), "hold")
     _raises(lambda: run(hold=True), "hold")
@@ -51,7 +52,7 @@ def test_portfolio_arguments():
     _raises(lambda: run(spread_bp=pd.DataFrame(-1.0, index=p.dates, columns=p.tickers).to_numpy()), "spread_bp")
     _raises(lambda: run(factor=(f.rank(axis=1, pct=True) >= 0.9)), "boolean factor", "backtest_event")
     # the boundary values and every documented option still run
-    for kw in (dict(long_q=1.0, short_q=None), dict(long_q=0.05, short_q=1.0), dict(hold=1), dict(spread_bp=0.0), dict(spread_bp=0),
+    for kw in (dict(long_q=1.0, short_q=None), dict(long_q=0.5, short_q=0.5), dict(hold=1), dict(spread_bp=0.0), dict(spread_bp=0),
                dict(weighting="equal"), dict(weighting="signal"), dict(weighting="rank"),
                dict(benchmark="cap"), dict(benchmark="equal"), dict(benchmark=None), dict(hold=np.int64(3))):
         with warnings.catch_warnings():

pitbacktest-0.2.1/tests/test_hardening_021.py

@@ -0,0 +1,137 @@
+"""Guards added after hostile-input review (0.2.1).
+
+HD1 prices      a zero, negative or infinite price is treated as missing, with a warning; a held name with a zero price gives the same result as one with a missing
+                price (before, the return was 3.6e307)
+HD2 alignment   a factor, weights or signal with other ticker names, transposed, a different time zone, or not a DataFrame is refused with the reason; half covered warns
+HD3 panel       duplicate ticker names raise; weekly dates with periods_per_year=252 warn, and the usual daily, 24/7 and 5-minute settings do not
+HD4 big moves   a daily move above +1000% on an eligible security warns and changes nothing in the numbers
+HD5 no trades   an all-NaN or constant factor, all-zero weights, and a capital too small for one lot warn that nothing was held
+HD6 dsr         a matrix with no usable column says so
+"""
+from __future__ import annotations
+import sys, warnings
+from dataclasses import replace
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import numpy as np
+import pandas as pd
+import pitbacktest as q
+from test_argument_checks import _raises
+from test_synthetic import make_panel
+
+
+def _warns(fn, *needles):
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+        out = fn()
+    msgs = [str(w.message) for w in ws]
+    assert all(any(n in m for m in msgs) for n in needles), (needles, msgs)
+    return out
+
+
+def _quiet(fn):
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+        out = fn()
+    return out, [str(w.message) for w in ws]
+
+
+def test_bad_prices():
+    p, rng = make_panel(n_days=400, n_stocks=40)
+    f = pd.DataFrame(rng.standard_normal(p.close.shape), index=p.dates, columns=p.tickers)
+    f.iloc[95:110, 3] = 99.0                                                       # name 3 is in the long leg around day 100
+    results = {}
+    for label, bad in (("nan", np.nan), ("zero", 0.0), ("negative", -5.0), ("inf", np.inf)):
+        c = p.close.copy()
+        c.iloc[100, 3] = bad
+        if label == "nan":
+            pp = replace(p, close=c)
+            out, _ = _quiet(lambda: q.backtest_portfolio(pp, f, hold=1, spread_bp=10))
+        else:
+            out = _warns(lambda: q.backtest_portfolio(replace(p, close=c), f, hold=1, spread_bp=10), "zero, negative or infinite")
+        results[label] = out.net_returns.to_numpy()
+        assert np.isfinite(results[label]).all() and np.abs(results[label]).max() < 1.0, (label, np.abs(results[label]).max())
+    for label in ("zero", "negative", "inf"):
+        assert np.array_equal(results[label], results["nan"]), label                # the same as a price that is simply missing
+    print("HD1 zero, negative and infinite prices are missing prices (warned), and a held name with a zero price no longer returns 3.6e307  PASS")
+
+
+def test_alignment():
+    p, rng = make_panel(n_days=400, n_stocks=40)
+    f = pd.DataFrame(rng.standard_normal(p.close.shape), index=p.dates, columns=p.tickers)
+    W = f.rank(axis=1, pct=True).ge(0.9).astype(float)
+    W = W.div(W.sum(axis=1).replace(0, np.nan), axis=0).fillna(0.0).where(p.eligible, 0.0)
+    E = f > 1.5
+    for what, call in (("factor", lambda x: q.backtest_portfolio(p, x, hold=5, spread_bp=10)),
+                       ("weights", lambda x: q.backtest_weights(p, x, spread_bp=5)),
+                       ("signal", lambda x: q.backtest_event(p, x, horizons=(5,), neutralize_check=False))):
+        good = {"factor": f, "weights": W, "signal": E}[what]
+        _raises(lambda: call(good.rename(columns=lambda c: "z" + c)), what, "no date or no ticker in common", "tickers in common: 0%")
+        _raises(lambda: call(good.T), what, "no date or no ticker in common")
+        _raises(lambda: call(good.tz_localize("UTC")), what, "dates in common: 0%")                  # a time zone on one side only
+        _raises(lambda: call(good.to_numpy()), what, "DataFrame", "ndarray")
+        _raises(lambda: call(good.iloc[:, 0]), what, "DataFrame", "Series")
+    sc = {"a": f}
+    _raises(lambda: q.screen(p, {"a": f.rename(columns=lambda c: "z" + c)}, horizons=(5,), primary_h=5, n_null=10), "factor 'a'", "no date or no ticker")
+    _warns(lambda: q.backtest_portfolio(p, f.iloc[:, :10], hold=5, spread_bp=10), "covers only", "25% of its tickers")
+    _, msgs = _quiet(lambda: q.backtest_portfolio(p, f.iloc[:, :30], hold=5, spread_bp=10))           # 75 percent covered: no warning
+    assert not any("covers only" in m for m in msgs), msgs
+    print("HD2 renamed, transposed, time-zone-shifted, array and Series inputs are refused with the reason in all four engines; a quarter of the tickers warns  PASS")
+
+
+def test_panel_checks():
+    p, _ = make_panel(n_days=300, n_stocks=20)
+    c = p.close.copy(); c.columns = ["A"] * 20
+    _raises(lambda: q.Panel(close=c, eligible=pd.DataFrame(True, index=c.index, columns=c.columns)), "duplicate ticker names")
+    wk = p.close.resample("W-FRI").last(); we = p.eligible.resample("W-FRI").last().astype(bool)
+    _warns(lambda: q.Panel(close=wk, eligible=we), "periods_per_year=252", "52 for weekly")
+    _, msgs = _quiet(lambda: q.Panel(close=wk, eligible=we, periods_per_year=52))
+    assert not any("periods_per_year" in m for m in msgs), msgs
+    _, msgs = _quiet(lambda: q.Panel(close=p.close, eligible=p.eligible))                              # business days with 252
+    assert not any("periods_per_year" in m for m in msgs), msgs
+    cal = pd.date_range("2020-01-01", periods=300, freq="D")                                            # a 24/7 market with 365
+    _, msgs = _quiet(lambda: q.Panel(close=pd.DataFrame(100.0, index=cal, columns=p.tickers), eligible=pd.DataFrame(True, index=cal, columns=p.tickers), periods_per_year=365))
+    assert not any("periods_per_year" in m for m in msgs), msgs
+    five = pd.date_range("2020-01-01", periods=2000, freq="5min")
+    _, msgs = _quiet(lambda: q.Panel(close=pd.DataFrame(100.0, index=five, columns=p.tickers), eligible=pd.DataFrame(True, index=five, columns=p.tickers), periods_per_year=105120))
+    assert not any("periods_per_year" in m for m in msgs), msgs
+    print("HD3 duplicate tickers raise; weekly dates with 252 warn; business days with 252, calendar days with 365 and 5-minute bars with 105120 do not  PASS")
+
+
+def test_big_moves_and_no_trades():
+    p, rng = make_panel(n_days=400, n_stocks=40)
+    f = pd.DataFrame(rng.standard_normal(p.close.shape), index=p.dates, columns=p.tickers)
+    c = p.close.copy(); c.iloc[200:, 5] = c.iloc[200:, 5] * 50.0                                      # a +4900% day
+    out = _warns(lambda: q.backtest_portfolio(replace(p, close=c), f, hold=5, spread_bp=10), "daily moves above +1000%", p.tickers[5])
+    ref, msgs = _quiet(lambda: q.backtest_portfolio(p, f, hold=5, spread_bp=10))
+    assert not any("+1000%" in m for m in msgs), msgs
+    _warns(lambda: q.backtest_portfolio(p, f * np.nan, hold=5, spread_bp=10), "no position was held")
+    _warns(lambda: q.backtest_portfolio(p, f * 0 + 1.0, hold=5, spread_bp=10), "no position was held")      # a constant factor has no ranking
+    W = f.rank(axis=1, pct=True).ge(0.9).astype(float).where(p.eligible, 0.0)
+    W = W.div(W.sum(axis=1).replace(0, np.nan), axis=0).fillna(0.0)
+    _warns(lambda: q.backtest_weights(p, W * 0, spread_bp=5), "no position was held")
+    _warns(lambda: q.backtest_weights(p, W, spread_bp=5, capital=1.0, price=p.close), "no position was held", "capital")
+    _, msgs = _quiet(lambda: q.backtest_weights(p, W, spread_bp=5))
+    assert not any("no position" in m for m in msgs), msgs
+    print("HD4/HD5 a +4900% day warns (numbers unchanged); an all-NaN or constant factor, zero weights and a capital below one lot warn that nothing was held  PASS")
+
+
+def test_dsr_message():
+    R = np.random.default_rng(0).normal(0, 0.01, (400, 5))
+    bad = np.where(np.random.default_rng(1).random(R.shape) < 0.1, np.nan, R)                          # every column has a NaN
+    _raises(lambda: q.validation.deflated_sharpe(bad, periods_per_year=252), "no column of R has a usable Sharpe")
+    _raises(lambda: q.validation.deflated_sharpe(np.zeros((400, 3)), periods_per_year=252), "no column of R has a usable Sharpe")
+    ok = R.copy(); ok[5, 2] = np.nan                                                                    # one column with a NaN is ignored, as documented
+    assert q.validation.deflated_sharpe(ok, periods_per_year=252)["best"] != 2
+    print("HD6 a matrix with no usable column raises a clear message; one NaN column is still ignored  PASS")
+
+
+if __name__ == "__main__":
+    test_bad_prices()
+    test_alignment()
+    test_panel_checks()
+    test_big_moves_and_no_trades()
+    test_dsr_message()
+    print("hardening tests: all passed")

pitbacktest-0.2.1/tests/test_ruin.py

@@ -0,0 +1,81 @@
+"""An account that is wiped out stays wiped out.
+
+RU1 weights   a 30x long that falls 50 percent in one name: the return that day is -100 percent, every later return is 0, the drawdown is -100 percent, the
+              date is named, a warning is raised; before the ruin day nothing changes
+RU2 portfolio the same for `backtest_portfolio` (weighting by signal gives a gross above 1 only through hold, so the ruin is built with a huge cost)
+RU3 no ruin   a result that never loses 100 percent has `ruined` False and is identical with and without the guard (a hand-computed series)
+"""
+from __future__ import annotations
+import sys, warnings
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import numpy as np
+import pandas as pd
+import pitbacktest as q
+from pitbacktest.portfolio import stop_at_ruin
+
+
+def _flat_panel(n_days=300, n=12, drop_day=150, drop=-0.5):
+    dates = pd.bdate_range("2020-01-01", periods=n_days)
+    close = pd.DataFrame(100.0, index=dates, columns=[f"A{i}" for i in range(n)])
+    close.iloc[drop_day:, 0] = 100.0 * (1 + drop)                       # the first name falls once and stays there
+    return q.Panel(close=close, eligible=pd.DataFrame(True, index=dates, columns=close.columns), market="TEST")
+
+
+def test_weights_ruin():
+    p = _flat_panel()
+    w = pd.DataFrame(0.0, index=p.dates, columns=p.tickers)
+    w.iloc[100:, 0] = 30.0
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+        r = q.backtest_weights(p, w, spread_bp=0, benchmark=None)
+    net = r.net_returns.to_numpy()
+    i = 148                                                             # row d earns close(d+1) -> close(d+2): the drop at row 150 is earned by row 148
+    assert abs(net[i] + 1.0) < 1e-12 and (net[i + 1:] == 0.0).all() and (net[:i] == 0.0).all(), (net[i - 1:i + 3])
+    assert r.metrics["ruined"] is True and r.metrics["ruin_date"] == str(p.dates[i].date())
+    assert abs(r.metrics["MDD"] + 1.0) < 1e-12, r.metrics["MDD"]
+    assert any("lost 100%" in str(x.message) for x in ws), [str(x.message) for x in ws]
+    assert abs(r.metrics["CAGR"] + 1.0) < 1e-9 or np.isfinite(r.metrics["CAGR"])      # a finite number, not NaN from a negative base
+    print(f"RU1 a 30x long that falls 50% is ruined on {r.metrics['ruin_date']}: -100%, then 0, MDD -100%, a warning  PASS")
+
+
+def test_portfolio_ruin():
+    p = _flat_panel(n_days=400, n=40)
+    f = pd.DataFrame(np.random.default_rng(0).standard_normal(p.close.shape), index=p.dates, columns=p.tickers)
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+        r = q.backtest_portfolio(p, f, long_q=0.5, short_q=0.5, hold=1, spread_bp=1e6)          # cost 100x the traded weight each day
+    net = r.net_returns.to_numpy()
+    first = int(np.flatnonzero(net <= -1.0)[0])
+    assert r.metrics["ruined"] and (net[first + 1:] == 0.0).all() and abs(net[first] + 1.0) < 1e-12
+    assert any("lost 100%" in str(x.message) for x in ws)
+    print("RU2 backtest_portfolio stops at the ruin day as well  PASS")
+
+
+def test_no_ruin_is_unchanged():
+    r0 = np.array([0.01, -0.02, 0.0, 0.03, -0.5, 0.2])
+    out, i = stop_at_ruin(r0, len(r0))
+    assert i is None and out is r0                                      # nothing to do: the very same array
+    r1 = np.array([0.01, -1.0, 0.5, 0.5])
+    out, i = stop_at_ruin(r1, 4)
+    assert i == 1 and out.tolist() == [0.01, -1.0, 0.0, 0.0] and r1.tolist() == [0.01, -1.0, 0.5, 0.5]    # input untouched
+    out, i = stop_at_ruin(np.array([0.1, -3.0, 0.2]), 2)
+    assert i == 1 and out.tolist() == [0.1, -1.0, 0.0]                  # beyond the cut the value is not looked at; within it -300% becomes -100%
+    out, i = stop_at_ruin(np.array([0.1, 0.1, -5.0]), 2)
+    assert i is None                                                    # a ruin in the rows cut away (outside the sample) is not counted
+    p = _flat_panel()
+    w = pd.DataFrame(0.0, index=p.dates, columns=p.tickers); w.iloc[100:, 0] = 1.0
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")                                  # no warning when nothing is lost beyond 100%
+        r = q.backtest_weights(p, w, spread_bp=0, benchmark=None)
+    assert r.metrics["ruined"] is False and r.metrics["ruin_date"] is None
+    assert abs(r.metrics["MDD"] + 0.5) < 1e-12                          # the plain 50% fall of an unleveraged long
+    print("RU3 no ruin: the same array comes back, the input is never changed, no warning, MDD -50% for an unleveraged long  PASS")
+
+
+if __name__ == "__main__":
+    test_weights_ruin()
+    test_portfolio_ruin()
+    test_no_ruin_is_unchanged()
+    print("ruin tests: all passed")