crucible-quant 0.1.0__py3-none-any.whl

crucible/__init__.py

@@ -0,0 +1,10 @@
+"""crucible — run a trading strategy through the crucible; weak edges don't survive.
+
+The capital-free core lives in :mod:`crucible.edge`: a trade log goes in, an edge
+verdict — with a confidence interval and a p-value — comes out. No account, no
+position sizing, no equity curve.
+"""
+from crucible import edge, strategies, validation
+
+__version__ = "0.1.0"
+__all__ = ["edge", "strategies", "validation", "__version__"]

crucible/edge/__init__.py

@@ -0,0 +1,28 @@
+"""
+crucible.edge — the raw mathematical edge of a signal, capital-free.
+
+Trade log in, edge verdict out. No account, no position sizing, no equity curve.
+If you want a $ equity curve, hand the :class:`TradeLog` to quantstats — this
+package stops at the edge.
+"""
+from crucible.edge.trade_log import TradeLog
+from crucible.edge.metrics import (
+    edge_report, EdgeReport,
+    expectancy, profit_factor, payoff_ratio, win_rate, sqn,
+    excursion_ratio, e_ratio, time_asymmetry, exit_efficiency,
+)
+from crucible.edge.stats import (
+    bootstrap_ci, p_value_positive, reality_check, random_entry_null,
+    CI, Verdict,
+)
+from crucible.edge.simulator import barrier_trades, random_entries
+
+__all__ = [
+    "TradeLog",
+    "edge_report", "EdgeReport",
+    "expectancy", "profit_factor", "payoff_ratio", "win_rate", "sqn",
+    "excursion_ratio", "e_ratio", "time_asymmetry", "exit_efficiency",
+    "bootstrap_ci", "p_value_positive", "reality_check", "random_entry_null",
+    "CI", "Verdict",
+    "barrier_trades", "random_entries",
+]

crucible/edge/metrics.py

@@ -0,0 +1,191 @@
+"""Capital-free edge metrics. Every function takes plain arrays; `edge_report`
+assembles the full scorecard from whatever columns a TradeLog carries.
+
+Lineage of the less-obvious ones:
+  excursion_ratio / e_ratio  — MFE/MAE efficiency (Sweeney; Faith, "Way of the Turtle")
+  sqn                        — System Quality Number (Van Tharp)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+import numpy as np
+
+from crucible.edge.trade_log import TradeLog
+
+
+def _arr(x) -> np.ndarray:
+    a = np.asarray(x, dtype=float)
+    return a[~np.isnan(a)]
+
+
+def win_rate(r) -> float:
+    r = _arr(r)
+    return float((r > 0).mean()) if len(r) else 0.0
+
+
+def expectancy(r) -> float:
+    """Normalized expectancy: win_rate*avg_win − loss_rate*avg_loss (in R)."""
+    r = _arr(r)
+    n = len(r)
+    if n == 0:
+        return 0.0
+    wins, losses = r[r > 0], r[r < 0]
+    wr, lr = len(wins) / n, len(losses) / n
+    avg_win = wins.mean() if len(wins) else 0.0
+    avg_loss = abs(losses.mean()) if len(losses) else 0.0
+    return float(wr * avg_win - lr * avg_loss)
+
+
+def profit_factor(r) -> float:
+    """Gross profit / gross loss. +inf if there are no losers."""
+    r = _arr(r)
+    gp = r[r > 0].sum()
+    gl = abs(r[r < 0].sum())
+    if gl == 0:
+        return float("inf") if gp > 0 else 0.0
+    return float(gp / gl)
+
+
+def payoff_ratio(r) -> float:
+    """Average win / average loss (terminal risk-reward)."""
+    r = _arr(r)
+    wins, losses = r[r > 0], r[r < 0]
+    if not len(wins) or not len(losses):
+        return float("inf") if len(wins) else 0.0
+    return float(wins.mean() / abs(losses.mean()))
+
+
+def sqn(r, cap: int = 100) -> float:
+    """Van Tharp System Quality Number: mean/std × √n, n capped (default 100)."""
+    r = _arr(r)
+    n = len(r)
+    if n < 2:
+        return 0.0
+    sd = r.std(ddof=1)
+    if sd == 0:
+        return 0.0
+    return float(r.mean() / sd * np.sqrt(min(n, cap)))
+
+
+def excursion_ratio(mfe, mae) -> float:
+    """mean(MFE) / |mean(MAE)| — how far trades run for vs. against you."""
+    mfe, mae = _arr(mfe), _arr(mae)
+    if not len(mfe) or not len(mae):
+        return float("nan")
+    m = abs(mae.mean())
+    return float(mfe.mean() / m) if m else float("inf")
+
+
+def e_ratio(mfe_k, mae_k) -> float:
+    """Edge ratio at a fixed horizon k (Faith): mean(MFE_k)/|mean(MAE_k)|.
+    >1 means the signal has directional edge before any exit rule is applied."""
+    return excursion_ratio(mfe_k, mae_k)
+
+
+def time_asymmetry(bars_held, r) -> float:
+    """avg bars in winners / avg bars in losers. >1 = let winners run, cut losers."""
+    bars_held, r = np.asarray(bars_held, dtype=float), np.asarray(r, dtype=float)
+    win_bars = bars_held[r > 0]
+    loss_bars = bars_held[r < 0]
+    if not len(win_bars) or not len(loss_bars):
+        return float("nan")
+    denom = loss_bars.mean()
+    return float(win_bars.mean() / denom) if denom else float("inf")
+
+
+def exit_efficiency(r, mfe) -> float:
+    """Among winners: captured return / available MFE. How much of the favorable
+    move the exit actually banked (1.0 = sold the top)."""
+    r, mfe = np.asarray(r, dtype=float), np.asarray(mfe, dtype=float)
+    mask = r > 0
+    if not mask.any():
+        return float("nan")
+    avail = mfe[mask].mean()
+    return float(r[mask].mean() / avail) if avail > 0 else float("nan")
+
+
+def _calibration(prob, r) -> dict:
+    """Win rate within model-confidence bins — is prob well-calibrated?"""
+    import pandas as pd
+    bins = [0.0, 0.5, 0.6, 0.7, 0.8, 1.0001]
+    labels = ["<50%", "50-60%", "60-70%", "70-80%", "80%+"]
+    df = pd.DataFrame({"prob": prob, "r": r}).dropna()
+    if df.empty:
+        return {}
+    df["bin"] = pd.cut(df["prob"], bins=bins, labels=labels, right=False)
+    out = {}
+    for name, g in df.groupby("bin", observed=True):
+        if len(g):
+            out[str(name)] = {"trades": int(len(g)),
+                              "win_rate": float((g["r"] > 0).mean())}
+    return out
+
+
+@dataclass
+class EdgeReport:
+    n: int
+    win_rate: float
+    expectancy: float
+    profit_factor: float
+    payoff_ratio: float
+    sqn: float
+    excursion_ratio: Optional[float] = None
+    e_ratio: Optional[float] = None
+    time_asymmetry: Optional[float] = None
+    exit_efficiency: Optional[float] = None
+    calibration: Optional[dict] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def __str__(self) -> str:
+        def flag(ok, warn_only=False):
+            return "[PASS]" if ok else ("[WARN]" if warn_only else "[FAIL]")
+
+        L = ["=" * 56, " EDGE REPORT (capital-free)", "=" * 56]
+        L.append(f"Trades              : {self.n}")
+        L.append(f"Win rate            : {self.win_rate * 100:.1f} %")
+        L.append("-" * 56)
+        L.append(f"Expectancy          : {self.expectancy:+.3f} R      {flag(self.expectancy > 0)}")
+        pf = self.profit_factor
+        L.append(f"Profit factor       : {pf:.2f}          {flag(pf > 1.25, warn_only=True)}")
+        L.append(f"Payoff ratio        : {self.payoff_ratio:.2f}          [INFO]")
+        L.append(f"SQN-100             : {self.sqn:.2f}          [INFO]")
+        if self.excursion_ratio is not None:
+            L.append("-" * 56)
+            L.append(f"Excursion ratio     : {self.excursion_ratio:.2f}          {flag(self.excursion_ratio > 1.0)}")
+        if self.e_ratio is not None:
+            L.append(f"E-ratio (k-bar)     : {self.e_ratio:.2f}          {flag(self.e_ratio > 1.0, warn_only=True)}")
+        if self.time_asymmetry is not None:
+            L.append(f"Time asymmetry      : {self.time_asymmetry:.2f}          {flag(self.time_asymmetry > 1.0, warn_only=True)}")
+        if self.exit_efficiency is not None:
+            L.append(f"Exit efficiency     : {self.exit_efficiency * 100:.1f} %        [INFO]")
+        if self.calibration:
+            L.append("-" * 56)
+            L.append("Calibration (confidence -> win rate):")
+            for k, v in self.calibration.items():
+                L.append(f"  {k:8s} -> {v['win_rate'] * 100:5.1f}%  (n={v['trades']})")
+        L.append("=" * 56)
+        return "\n".join(L)
+
+
+def edge_report(trades: TradeLog) -> EdgeReport:
+    """Every capital-free edge metric the TradeLog has the columns to support."""
+    r = trades.r
+    mfe, mae = trades.col("mfe"), trades.col("mae")
+    bars, prob = trades.col("bars_held"), trades.col("prob")
+    return EdgeReport(
+        n=trades.n,
+        win_rate=win_rate(r),
+        expectancy=expectancy(r),
+        profit_factor=profit_factor(r),
+        payoff_ratio=payoff_ratio(r),
+        sqn=sqn(r),
+        excursion_ratio=excursion_ratio(mfe, mae) if mfe is not None and mae is not None else None,
+        e_ratio=None,  # populate when you pass a fixed-horizon MFE/MAE via e_ratio()
+        time_asymmetry=time_asymmetry(bars, r) if bars is not None else None,
+        exit_efficiency=exit_efficiency(r, mfe) if mfe is not None else None,
+        calibration=_calibration(prob, r) if prob is not None else None,
+    )

crucible/edge/simulator.py

@@ -0,0 +1,115 @@
+"""A generic, capital-free barrier simulator: OHLC + entry signal -> TradeLog in R.
+
+No instrument specifics, no position sizing, no capital — just the geometry of
+"enter here, exit at TP / SL / timeout" turned into R-multiple trades so the edge
+metrics can read them. Look-ahead-free: barriers are sized off the SIGNAL bar
+(known at entry), exits are scanned from the entry bar forward.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from crucible.edge.trade_log import TradeLog
+
+_OHLC = ("Open", "High", "Low", "Close")
+_TRADE_COLS = ["r", "mfe", "mae", "bars_held", "entry_date", "exit_date", "exit_reason"]
+
+
+def atr(df: pd.DataFrame, span: int = 14) -> pd.Series:
+    """Wilder-ish ATR via EWM of true range."""
+    hl = df["High"] - df["Low"]
+    hc = (df["High"] - df["Close"].shift()).abs()
+    lc = (df["Low"] - df["Close"].shift()).abs()
+    tr = pd.concat([hl, hc, lc], axis=1).max(axis=1)
+    return tr.ewm(span=span, adjust=False).mean()
+
+
+def barrier_trades(df: pd.DataFrame, entries, side: str = "long", *,
+                   tp: float = 2.0, sl: float = 1.0, timeout: int = 20,
+                   risk_unit: str = "atr", atr_col: str = "ATR",
+                   entry: str = "next_open") -> TradeLog:
+    """Enter on each True bar of `entries`; exit at TP / SL / timeout.
+
+    tp, sl        barrier distances in `risk_unit`s (ATR multiples by default)
+    risk_unit     'atr' (1 unit = ATR of the signal bar) or 'price' (1 unit = 1.0)
+    entry         'next_open' (conservative) or 'close' (fill on the signal bar)
+
+    1R = sl × unit, so returns pool cleanly across instruments. Positions never
+    overlap: the scan resumes the bar after each exit.
+    """
+    missing = [c for c in _OHLC if c not in df.columns]
+    if missing:
+        raise ValueError(f"barrier_trades needs OHLC columns; missing {missing}")
+
+    df = df.copy()
+    if risk_unit == "atr" and atr_col not in df.columns:
+        df[atr_col] = atr(df)
+
+    entries = pd.Series(entries).reindex(df.index, fill_value=False).to_numpy(dtype=bool)
+    o, h, l, c = (df[x].to_numpy(dtype=float) for x in _OHLC)
+    unit_arr = df[atr_col].to_numpy(dtype=float) if risk_unit == "atr" else np.ones(len(df))
+    dates = df.index.to_numpy()
+    s = 1 if side == "long" else -1
+    n = len(df)
+
+    trades = []
+    i = 0
+    while i < n - 1:
+        if not entries[i]:
+            i += 1
+            continue
+        ei = i + 1 if entry == "next_open" else i
+        ep = o[ei] if entry == "next_open" else c[i]
+        unit = unit_arr[i]                      # sized off the SIGNAL bar (no look-ahead)
+        if not (ep > 0 and unit > 0):
+            i += 1
+            continue
+        risk = sl * unit
+        tp_px = ep + s * tp * unit
+        sl_px = ep - s * sl * unit
+
+        mfe = mae = 0.0
+        xp = xr = None
+        j = ei
+        while j < n:
+            fav = s * (h[j] - ep) if s > 0 else s * (l[j] - ep)
+            adv = s * (l[j] - ep) if s > 0 else s * (h[j] - ep)
+            mfe, mae = max(mfe, fav), min(mae, adv)
+            if s > 0:
+                if l[j] <= sl_px:
+                    xp, xr = sl_px, "SL"; break
+                if h[j] >= tp_px:
+                    xp, xr = tp_px, "TP"; break
+            else:
+                if h[j] >= sl_px:
+                    xp, xr = sl_px, "SL"; break
+                if l[j] <= tp_px:
+                    xp, xr = tp_px, "TP"; break
+            if j - ei >= timeout:
+                xp, xr = c[j], "timeout"; break
+            j += 1
+        if xp is None:
+            xp, xr, j = c[-1], "eod", n - 1
+
+        trades.append({
+            "r": s * (xp - ep) / risk,
+            "mfe": mfe / risk, "mae": mae / risk,
+            "bars_held": j - ei,
+            "entry_date": dates[ei], "exit_date": dates[j], "exit_reason": xr,
+        })
+        i = j + 1                                # no overlapping positions
+
+    frame = pd.DataFrame(trades, columns=_TRADE_COLS)
+    return TradeLog(frame)
+
+
+def random_entries(df: pd.DataFrame, n: int, seed: int = 0) -> pd.Series:
+    """A boolean entry series with `n` random bars set True — the null model
+    used by :func:`crucible.edge.stats.random_entry_null`."""
+    rng = np.random.default_rng(seed)
+    n = min(n, len(df) - 1)
+    mask = np.zeros(len(df), dtype=bool)
+    if n > 0:
+        mask[rng.choice(len(df) - 1, size=n, replace=False)] = True
+    return pd.Series(mask, index=df.index)

crucible/edge/stats.py

@@ -0,0 +1,129 @@
+"""The honesty layer — the reason crucible.edge exists.
+
+A positive expectancy on a trade log means nothing until you know it could not
+have come from noise. These tools answer that with a confidence interval, a
+resampling p-value, and — when you have the price series — a random-entry null.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+
+from crucible.edge.trade_log import TradeLog
+from crucible.edge.metrics import expectancy
+
+Metric = Callable[[np.ndarray], float]
+
+
+@dataclass
+class CI:
+    point: float
+    low: float
+    high: float
+    alpha: float
+
+    def __str__(self) -> str:
+        lvl = int(round((1 - self.alpha) * 100))
+        return f"{self.point:+.3f}  {lvl}% CI [{self.low:+.3f}, {self.high:+.3f}]"
+
+
+@dataclass
+class Verdict:
+    metric: str
+    point: float
+    ci: CI
+    p_value: float          # one-sided: P(metric <= 0) under resampling
+    label: str              # "HELD" | "FRAGILE" | "FAIL"
+
+    def __str__(self) -> str:
+        lvl = int(round((1 - self.ci.alpha) * 100))
+        note = {
+            "HELD": "the edge clears zero across resamples.",
+            "FRAGILE": "point positive, but the CI straddles zero — not "
+                       "distinguishable from noise at this sample size. Do NOT size it up.",
+            "FAIL": "no positive edge.",
+        }[self.label]
+        return (f"VERDICT ({self.metric}): {self.point:+.3f} R   "
+                f"{lvl}% CI [{self.ci.low:+.3f}, {self.ci.high:+.3f}]\n"
+                f"                     p(edge>0) = {1 - self.p_value:.3f}"
+                f"        ->  {self.label}\n  {note}")
+
+
+def _resample(r: np.ndarray, metric: Metric, n_boot: int, rng) -> np.ndarray:
+    n = len(r)
+    draws = np.empty(n_boot)
+    for i in range(n_boot):
+        draws[i] = metric(rng.choice(r, size=n, replace=True))
+    return draws
+
+
+def bootstrap_ci(trades: TradeLog, metric: Metric = expectancy,
+                 n_boot: int = 10_000, alpha: float = 0.05, seed: int = 0) -> CI:
+    """Bootstrap confidence interval for any per-trade-return metric.
+
+    The point estimate alone badly understates sampling noise at the trade
+    counts real strategies produce (tens to low hundreds); the CI is the honest
+    read. `metric` is any callable over the return array (expectancy,
+    profit_factor, sqn, ...)."""
+    r = trades.r
+    if len(r) == 0:
+        return CI(float("nan"), float("nan"), float("nan"), alpha)
+    rng = np.random.default_rng(seed)
+    draws = _resample(r, metric, n_boot, rng)
+    finite = draws[np.isfinite(draws)]
+    lo = float(np.percentile(finite, alpha / 2 * 100)) if len(finite) else float("nan")
+    hi = float(np.percentile(finite, (1 - alpha / 2) * 100)) if len(finite) else float("nan")
+    return CI(point=float(metric(r)), low=lo, high=hi, alpha=alpha)
+
+
+def p_value_positive(trades: TradeLog, metric: Metric = expectancy,
+                     n_boot: int = 10_000, seed: int = 0) -> float:
+    """One-sided bootstrap probability that the metric is > 0 (1.0 = strong)."""
+    r = trades.r
+    if len(r) == 0:
+        return 0.0
+    rng = np.random.default_rng(seed)
+    draws = _resample(r, metric, n_boot, rng)
+    finite = draws[np.isfinite(draws)]
+    return float((finite > 0).mean()) if len(finite) else 0.0
+
+
+def reality_check(trades: TradeLog, metric: Metric = expectancy,
+                  metric_name: str = "expectancy", n_boot: int = 10_000,
+                  alpha: float = 0.05, seed: int = 0) -> Verdict:
+    """Point estimate + bootstrap CI + p-value, folded into a verdict:
+
+      HELD     point > 0 and CI lower bound > 0
+      FRAGILE  point > 0 but the CI straddles zero
+      FAIL     otherwise
+
+    This is the whole point of the package — the call backtesters never make."""
+    ci = bootstrap_ci(trades, metric, n_boot, alpha, seed)
+    p_pos = p_value_positive(trades, metric, n_boot, seed)
+    if ci.point > 0 and ci.low > 0:
+        label = "HELD"
+    elif ci.point > 0:
+        label = "FRAGILE"
+    else:
+        label = "FAIL"
+    return Verdict(metric=metric_name, point=ci.point, ci=ci,
+                   p_value=1 - p_pos, label=label)
+
+
+def random_entry_null(prices, side: str, n_entries: int, hold: int, *,
+                      tp: float = 2.0, sl: float = 1.0, n_sims: int = 1_000,
+                      seed: int = 0) -> np.ndarray:
+    """The strong test: expectancy of `n_sims` random-entry trade logs, each with
+    `n_entries` random entries held `hold` bars under the same barriers, on the
+    SAME prices. Compare your real edge against this distribution — did the signal
+    beat coin-flip timing on this instrument? Returns the null expectancies."""
+    from crucible.edge.simulator import barrier_trades, random_entries  # avoid cycle
+    rng = np.random.default_rng(seed)
+    out = np.empty(n_sims)
+    for i in range(n_sims):
+        entries = random_entries(prices, n_entries, seed=int(rng.integers(1 << 31)))
+        tl = barrier_trades(prices, entries, side=side, tp=tp, sl=sl, timeout=hold)
+        out[i] = expectancy(tl.r) if len(tl) else np.nan
+    return out

crucible/edge/trade_log.py

@@ -0,0 +1,84 @@
+"""The TradeLog contract — the one schema everything in crucible.edge speaks."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Mapping, Sequence
+
+import numpy as np
+import pandas as pd
+
+# Canonical schema. `r` is the only required column; the rest unlock more of the
+# report (excursion metrics need mfe/mae, time metrics need bars_held, etc.).
+REQUIRED = ("r",)
+OPTIONAL = ("mfe", "mae", "bars_held", "prob", "entry_date", "exit_date")
+
+
+@dataclass(frozen=True)
+class TradeLog:
+    """A set of closed trades, returns in a risk-normalized unit (R-multiples).
+
+    Columns (canonical names):
+      r          per-trade return in R (1R = the risk taken at entry)   [required]
+      mfe, mae   max favorable / adverse excursion, in R                [excursion]
+      bars_held  holding period, in bars                                [time]
+      prob       model confidence at entry, 0..1                        [calibration]
+      entry_date, exit_date                                             [ordering]
+
+    Construct with :meth:`from_arrays` or :meth:`from_frame`. The frame is stored
+    as-is (extra columns are allowed and preserved).
+    """
+    frame: pd.DataFrame
+
+    def __post_init__(self) -> None:
+        missing = [c for c in REQUIRED if c not in self.frame.columns]
+        if missing:
+            raise ValueError(
+                f"TradeLog is missing required column(s) {missing}. "
+                f"Got columns: {list(self.frame.columns)}. "
+                f"Use TradeLog.from_frame(df, mapping={{'your_col': 'r'}}) to rename."
+            )
+
+    # ── constructors ─────────────────────────────────────────────────────────
+    @classmethod
+    def from_arrays(cls, r: Sequence[float], *, mfe=None, mae=None,
+                    bars_held=None, prob=None, entry_date=None,
+                    exit_date=None) -> "TradeLog":
+        data = {"r": np.asarray(r, dtype=float)}
+        for name, arr in (("mfe", mfe), ("mae", mae), ("bars_held", bars_held),
+                          ("prob", prob), ("entry_date", entry_date),
+                          ("exit_date", exit_date)):
+            if arr is not None:
+                data[name] = np.asarray(arr)
+        return cls(pd.DataFrame(data))
+
+    @classmethod
+    def from_frame(cls, df: pd.DataFrame, *, r_col: str = "r",
+                   mapping: Optional[Mapping[str, str]] = None) -> "TradeLog":
+        """Wrap an existing frame. `mapping` renames your columns to the schema
+        (e.g. ``{'pct_return': 'r'}``); `r_col` is a shorthand for the return
+        column if you'd rather not build a full mapping."""
+        rename = dict(mapping or {})
+        if r_col != "r" and r_col in df.columns and "r" not in rename.values():
+            rename[r_col] = "r"
+        out = df.rename(columns=rename).copy()
+        return cls(out)
+
+    # ── accessors ────────────────────────────────────────────────────────────
+    @property
+    def r(self) -> np.ndarray:
+        return self.frame["r"].to_numpy(dtype=float)
+
+    def col(self, name: str) -> Optional[np.ndarray]:
+        """Return a schema column as an array, or None if absent."""
+        return self.frame[name].to_numpy() if name in self.frame.columns else None
+
+    @property
+    def n(self) -> int:
+        return len(self.frame)
+
+    def __len__(self) -> int:
+        return len(self.frame)
+
+    def __repr__(self) -> str:
+        cols = ", ".join(self.frame.columns)
+        return f"TradeLog(n={self.n}, cols=[{cols}])"

crucible/report/__init__.py

@@ -0,0 +1,13 @@
+"""
+crucible.report — a self-contained HTML tearsheet for a TradeLog.
+
+Requires the [report] extra (plotly):  pip install "crucible-quant[report]"
+
+True to the rest of crucible, the tearsheet visualizes the EDGE, not an account:
+the R-multiple distribution, cumulative R, MFE/MAE excursion, and the bootstrap
+expectancy distribution behind the HELD/FRAGILE/FAIL verdict. No equity curve, no
+capital.
+"""
+from crucible.report.tearsheet import tearsheet, cumulative_r
+
+__all__ = ["tearsheet", "cumulative_r"]