quantred 2.4.0__py3-none-any.whl

quantred/analytics/execution_quality.py

@@ -0,0 +1,180 @@
+"""Roll up what the live path actually did, from the ledger.
+
+Research-clock code: it reads the trade clock's append-only record and summarises it.
+Nothing here is a gate, and nothing here changes a run. What "bad" slippage looks like
+for a given strategy is not knowable from one session, so this reports the numbers and
+declines to grade them.
+
+The reporting rules that matter here:
+
+* **Absent is not zero.** A fill with no recorded price contributes no slippage, and
+  is counted as unmeasured rather than averaged in as zero.
+* **Say what was not measured.** Every summary carries how many rows it could not
+  evaluate, because a clean-looking average over two of twenty fills is worse than no
+  average at all.
+* **A modelled cost is not an observed one.** The cost model's estimate and the
+  venue's fee are reported separately and never summed.
+"""
+
+from statistics import median
+from typing import Any, Dict, List, Optional
+
+
+def _measured(rows: List[Dict[str, Any]], key: str) -> List[float]:
+    return [row[key] for row in rows if row.get(key) is not None]
+
+
+def slippage_summary(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Slippage across filled orders, in basis points, positive meaning worse."""
+    values = _measured(rows, "slippage_bps")
+    filled = [row for row in rows if row.get("filled_qty")]
+    summary = {
+        "n_filled": len(filled),
+        "n_measured": len(values),
+        "n_unmeasured": len(filled) - len(values),
+        "mean_bps": None,
+        "median_bps": None,
+        "worst_bps": None,
+        "worst_symbol": None,
+        "best_bps": None,
+    }
+    if not values:
+        return summary
+    worst = max(rows, key=lambda r: r.get("slippage_bps") if r.get("slippage_bps") is not None else -1e9)
+    summary.update(
+        mean_bps=sum(values) / len(values),
+        median_bps=median(values),
+        worst_bps=max(values),
+        worst_symbol=worst.get("symbol"),
+        best_bps=min(values),
+    )
+    return summary
+
+
+def latency_summary(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """How long the venue took, from the decision to the fill it produced.
+
+    Negative elapsed times are counted apart and never averaged in. They mean our
+    clock and the venue's disagree, not that a fill arrived before it was requested —
+    and a mean quietly dragged negative by skew is worse than an admission that some
+    rows could not be timed.
+    """
+    values = _measured(rows, "decision_to_fill_ms")
+    forward = [value for value in values if value >= 0]
+    summary = {
+        "n_measured": len(forward),
+        "n_clock_skew": len(values) - len(forward),
+        "median_ms": None,
+        "worst_ms": None,
+    }
+    if forward:
+        summary.update(median_ms=median(forward), worst_ms=max(forward))
+    return summary
+
+
+def fill_summary(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Submitted versus filled, in shares and in notional."""
+    submitted_notional = sum(
+        abs(row["submitted_qty"]) * row["reference_price"]
+        for row in rows
+        if row.get("submitted_qty") and row.get("reference_price")
+    )
+    filled_notional = sum(
+        abs(row["filled_qty"]) * row["fill_price"]
+        for row in rows
+        if row.get("filled_qty") and row.get("fill_price")
+    )
+    unfilled = [row for row in rows if not row.get("filled_qty")]
+    # Two different things, and conflating them reported "0 partial" about a session
+    # where both orders filled in several prints. One is an outcome (the order ended
+    # short of what was asked), the other is a route (it took more than one print to
+    # get there) - and only the first is a problem.
+    short = [
+        row
+        for row in rows
+        if row.get("filled_qty")
+        and row.get("submitted_qty")
+        and abs(row["filled_qty"]) < abs(row["submitted_qty"]) - 1e-9
+    ]
+    multi_print = [row for row in rows if (row.get("n_fill_events") or 0) > 1]
+    return {
+        "n_orders": len(rows),
+        "n_unfilled": len(unfilled),
+        "n_short": len(short),
+        "n_multi_print": len(multi_print),
+        "submitted_notional": submitted_notional,
+        "filled_notional": filled_notional,
+        # None rather than 0.0: with nothing submitted there is no ratio to report,
+        # and 0.0 would read as "nothing filled".
+        "fill_ratio": (filled_notional / submitted_notional) if submitted_notional else None,
+    }
+
+
+def cost_summary(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Modelled cost and observed fees, kept apart on purpose."""
+    estimates = [row["cost_estimate"] for row in rows if isinstance(row.get("cost_estimate"), dict)]
+    fees = _measured(rows, "broker_fee")
+    excluded = sorted({part for estimate in estimates for part in estimate.get("excludes", [])})
+    return {
+        "n_estimated": len(estimates),
+        "model_cost_estimate": sum(e.get("total") or 0.0 for e in estimates) if estimates else None,
+        "model_commission": sum(e.get("commission") or 0.0 for e in estimates) if estimates else None,
+        "model_spread": sum(e.get("spread") or 0.0 for e in estimates) if estimates else None,
+        # Named, so a modelled number that omits a component is not read as the whole
+        # cost. Impact needs the day's volume, which the trade clock does not have.
+        "model_excludes": excluded,
+        "n_fees_reported": len(fees),
+        "broker_fees": sum(fees) if fees else None,
+        # The distinction the operator has to see: a paper venue reports no fees, so
+        # "no fees" must never be presented as "fees were zero".
+        "fees_reported": bool(fees),
+    }
+
+
+def decline_summary(declines: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    """How often each *kind* of refusal stopped a signal, worst first.
+
+    Grouped by the decision's reason family, not its message. Rows written before
+    decisions carried a code are recognised by their message and folded into the same
+    family, because an append-only ledger keeps its history and a report that groups
+    only new rows shows one throttle as two. The message embeds the
+    numbers that caused it - "gross exposure capped: $7,617.12 of $7,200.00" - so
+    counting messages turned sixteen refusals of one kind into sixteen rows of one,
+    which is the shape that hides a throttle rather than showing it.
+
+    One example message is kept per family, because the code alone does not say what
+    the limit was or how far over it the book had got.
+    """
+    from quantred.execution.decision import reason_family
+
+    families: Dict[str, Dict[str, Any]] = {}
+    for record in declines:
+        code = reason_family(record)
+        family = families.setdefault(code, {"count": 0, "example": None})
+        family["count"] += 1
+        if family["example"] is None:
+            family["example"] = record.get("reason")
+    return dict(sorted(families.items(), key=lambda kv: -kv[1]["count"]))
+
+
+def execution_report(
+    rows: List[Dict[str, Any]],
+    declines: Optional[List[Dict[str, Any]]] = None,
+    flattens: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Everything the ledger can say about how well this book was executed.
+
+    ``flattens`` are carried beside the orders rather than folded into them: a position
+    an operator closed at the broker never produced a fill this file saw, so it has no
+    price, no latency and no slippage. Counting it among the fills would put a hole in
+    every average; leaving it out entirely would lose the reason a position vanished.
+    """
+    return {
+        "flattens": list(flattens or []),
+        "slippage": slippage_summary(rows),
+        "latency": latency_summary(rows),
+        "fills": fill_summary(rows),
+        "costs": cost_summary(rows),
+        "declines": decline_summary(declines or []),
+        "orders": rows,
+    }

quantred/analytics/exposure.py

@@ -0,0 +1,167 @@
+"""Choosing a directional cap from what a strategy actually ran at.
+
+`max_net_exposure` is a fraction, and picking one from anything but the strategy's own
+history is a guess dressed as a limit. This turns the exposure the backtest carried into
+the only thing that can honestly inform that choice: a distribution, and — for any cap
+you are considering — how often it would have bound.
+
+The framing matters more than the arithmetic. **Any cap below the observed maximum would
+have changed the book that was validated.** A cap is not free just because it is loose:
+it either never binds, in which case it documents an intent rather than enforcing one, or
+it binds, in which case the thing running is no longer the thing that was tested. This
+reports both halves and picks nothing.
+
+Research clock: reads a completed backtest, decides nothing about a live run.
+"""
+
+from typing import Any, Dict, List, Optional
+
+#: Caps worth showing, as multiples of the observed p95. Below 1.0 bites into normal
+#: operation; above ~1.5 is loose enough that it only catches an excursion.
+_HEADROOMS = (1.0, 1.25, 1.5)
+
+#: A little above the observed maximum, so there is always one candidate that provably
+#: never binds. Without it a fat-tailed book offers only caps that would have changed it.
+_MAX_HEADROOM = 1.1
+
+#: Below this many samples a percentile is an anecdote. The derivation still runs — the
+#: numbers are real — but the caveat leads, because a p95 from a handful of steps is the
+#: kind of number that gets quoted as though it were evidence.
+MIN_SAMPLES = 30
+
+
+def candidate_caps(stats: Dict[str, float]) -> List[float]:
+    """The caps worth evaluating, derived from the observed distribution alone.
+
+    The max-based anchor guarantees at least one cap that provably never bound. A
+    percentile-only ladder can sit entirely below a fat tail, and then reports that no
+    cap leaves the book intact when one obviously does.
+    """
+    if not stats or stats.get("max", 0.0) <= 0:
+        # A book that never carried a measurable tilt. Every positive cap is unbinding,
+        # so offering candidates would invent a choice that does not exist.
+        return []
+    caps = {round(stats["p95"] * headroom, 4) for headroom in _HEADROOMS}
+    caps.add(round(stats["max"] * _MAX_HEADROOM, 4))
+    return sorted(cap for cap in caps if cap > 0)
+
+
+def net_cap_candidates(exposure: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Caps worth considering, each with what it would have done historically.
+
+    Binding rates are computed where the samples live — during the backtest — and
+    carried here as scalars. Keeping the full series on the result would put one row per
+    step into anything that serializes it, for a number only ever read at a handful of
+    caps.
+    """
+    return list((exposure or {}).get("candidates") or [])
+
+
+def derive_net_cap(exposure: Dict[str, Any], gross_cap: Optional[float] = None) -> Dict[str, Any]:
+    """What the history says about a directional cap, and what it does not.
+
+    ``recommended`` is the smallest candidate that would never have bound — the only
+    choice that leaves the validated book intact. It is a starting point, not a verdict:
+    a cap that never binds is documentation, and tightening it is a deliberate decision
+    to trade something different from what was tested.
+    """
+    stats = (exposure or {}).get("net_abs")
+    if not stats:
+        return {"available": False, "reason": "no exposure was sampled"}
+
+    candidates = net_cap_candidates(exposure)
+    never_binds = [c for c in candidates if c["binding_rate"] == 0.0]
+    # The cap itself, not the candidate that carries it. Holding the dict here and
+    # unwrapping it only at the return meant the same name was a dict on one line and a
+    # float three lines later, which is how the comparison below came to be a TypeError.
+    recommended = min(never_binds, key=lambda candidate: candidate["cap"])["cap"] if never_binds else None
+    samples = exposure.get("samples", 0)
+    # |long - short| <= long + short identically, so a net cap at or above the gross cap
+    # can never bind. Worth saying out loud: a recommendation the gross cap already
+    # subsumes is documentation, and reads as a second limit when it is not one.
+    subsumed = gross_cap is not None and recommended is not None and recommended >= gross_cap
+    return {
+        "available": True,
+        "samples": samples,
+        "thin": samples < MIN_SAMPLES,
+        "no_tilt_carried": stats["max"] <= 0,
+        "observed": stats,
+        "signed_mean": exposure.get("net_signed_mean"),
+        "gross_max": exposure.get("gross_max"),
+        "candidates": candidates,
+        "gross_cap": gross_cap,
+        "subsumed_by_gross": subsumed,
+        # None when every candidate would have bound: the honest answer is then "no cap
+        # derived from this history leaves it unchanged", not the least-bad number.
+        "recommended": recommended,
+    }
+
+
+def format_net_cap(derivation: Dict[str, Any]) -> List[str]:
+    """Render the derivation, leading with what it cannot tell you."""
+    if not derivation.get("available"):
+        return [f"  Net exposure: not derivable — {derivation.get('reason', 'no data')}."]
+
+    observed, lines = derivation["observed"], []
+    lines.append(f"\n=== Directional tilt actually carried ({derivation['samples']} steps) ===")
+    if derivation.get("thin"):
+        # Leads, because a percentile from a handful of steps is exactly the kind of
+        # number that gets quoted as evidence once it is written down.
+        lines.append(
+            f"  NOT ENOUGH HISTORY — {derivation['samples']} steps is too few for a "
+            f"percentile to mean anything. Read the max; ignore the rest."
+        )
+    lines.append(
+        f"  |net| / equity        median {observed['median']:.1%}  p90 {observed['p90']:.1%}  "
+        f"p95 {observed['p95']:.1%}  p99 {observed['p99']:.1%}  max {observed['max']:.1%}"
+    )
+    signed = derivation.get("signed_mean")
+    if signed is not None:
+        lean = "long" if signed > 0 else "short"
+        lines.append(
+            f"  signed mean           {signed:+.1%} — the book leans {lean} by construction"
+            if abs(signed) > 0.01
+            else f"  signed mean           {signed:+.1%} — no systematic lean"
+        )
+    if derivation.get("gross_max") is not None:
+        lines.append(f"  gross max             {derivation['gross_max']:.1%} of equity")
+
+    if derivation.get("no_tilt_carried"):
+        lines.append(
+            "\n  This book never carried a measurable tilt, so every positive cap is "
+            "unbinding.\n  A cap here documents an intent; it does not constrain "
+            "anything this history shows."
+        )
+        return lines
+
+    lines.append("\n  A cap and what it would have done:")
+    for candidate in derivation["candidates"]:
+        rate = candidate["binding_rate"]
+        effect = (
+            "never binds — documents the intent, enforces nothing new"
+            if rate == 0.0
+            else f"would have bound on {rate:.1%} of steps — a different book from the validated one"
+        )
+        lines.append(f"    --max-net-exposure {candidate['cap']:.2f}   {effect}")
+
+    if derivation["recommended"] is not None:
+        lines.append(
+            f"\n  Smallest cap that leaves the validated book intact: {derivation['recommended']:.2f}"
+        )
+        if derivation.get("subsumed_by_gross"):
+            lines.append(
+                f"  But |net| never exceeds gross, so a gross cap of "
+                f"{derivation['gross_cap']:.2f} already holds net below that. This value\n"
+                f"  documents an intent; it cannot bind while that gross cap stands."
+            )
+    else:
+        lines.append(
+            "\n  No candidate leaves the validated book intact. Any cap from this "
+            "history would have changed what was tested — decide deliberately."
+        )
+    lines.append(
+        "  This is a starting point, not a verdict. A cap that never binds is "
+        "documentation;\n  tightening it is a decision to trade something other than "
+        "what was validated."
+    )
+    return lines