openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/portfolio/helpers.py

@@ -0,0 +1,92 @@
+"""Existing implementation moved from lib: compute_stats."""
+
+from __future__ import annotations
+
+from typing import cast
+
+import numpy as np
+import pandas as pd
+
+from openbacktesting.broker.models import finite
+from openbacktesting.portfolio.rates import validate_risk_free_rate
+from openbacktesting.portfolio.snapshot import refresh_snapshot
+from openbacktesting.portfolio.stats import compute_stats as _compute_stats
+
+
+def compute_stats(
+    *,
+    stats: pd.Series,
+    data: pd.DataFrame,
+    trades: pd.DataFrame = None,
+    risk_free_rate: float = cast(float, ...),
+) -> pd.Series:
+    """Recompute performance statistics from existing results, data, and an optional trade subset.
+
+
+    (Re-)compute strategy performance metrics.
+
+    `stats` is the statistics series as returned by `openbacktesting.engine.Backtest.run()`.
+    `data` is OHLC data as passed to the `openbacktesting.engine.Backtest`
+    the `stats` were obtained in.
+    `trades` can be a dataframe subset of `stats._trades` (e.g. only long trades).
+    risk_free_rate is an annualized fraction used for Sharpe, Sortino, and Alpha; omission inherits the latest statistics value,
+    missing records fall back to zero, explicit zero overrides, and None is invalid. Recalculation does not rewrite the original run snapshot or actual fees.
+    Initial capital inherits statistics_initial_equity; historical records lacking it fall back to the first equity value.
+    Initial capital must be positive and finite; approximate equity for trade subsets starts from the same principal.
+
+        >>> stats = Backtest(GOOG, MyStrategy).run()
+        >>> only_long_trades = stats._trades[stats._trades.Size > 0]
+        >>> long_stats = compute_stats(stats=stats, trades=only_long_trades,
+        ...                            data=GOOG, risk_free_rate=.02)
+    """
+    if risk_free_rate is Ellipsis:
+        risk_free_rate = stats.attrs.get("statistics_risk_free_rate", 0.0)
+    risk_free_rate = validate_risk_free_rate(risk_free_rate)
+    equity = stats._equity_curve.Equity
+    initial_equity = finite(
+        stats.attrs.get("statistics_initial_equity", equity.iloc[0]),
+        "initial_equity",
+        positive=True,
+    )
+    exposure = None
+    full_account = trades is None
+    if full_account:
+        trades = stats._trades
+        if "_positions" in stats:
+            positions = stats["_positions"]
+            exposure = np.zeros(len(data), dtype=bool)
+            bars = positions[positions.phase == "bar"]
+            exposure[bars.bar_index] = bars.gross_qty > 0
+    else:
+        # XXX: Is this buggy?
+        equity = equity.copy()
+        equity[:] = initial_equity
+        for t in trades.itertuples(index=False):
+            equity.iloc[t.EntryBar :] += t.PnL
+    result = _compute_stats(
+        trades=trades,
+        equity=equity.values,
+        ohlc_data=data,
+        risk_free_rate=risk_free_rate,
+        strategy_instance=stats.get("_strategy"),
+        exposure=exposure,
+        initial_equity=initial_equity,
+    )
+    if full_account:
+        preserved = {
+            key: value
+            for key, value in stats.items()
+            if key.startswith("_")
+            and key not in ("_strategy", "_trades", "_equity_curve")
+            or key in ("Commissions [$]", "# Closed Lots")
+        }
+        result = type(result)(dict(result) | preserved, dtype=object)
+    result.attrs.update(stats.attrs)
+    result.attrs["statistics_risk_free_rate"] = risk_free_rate
+    result.attrs["statistics_initial_equity"] = initial_equity
+    if full_account:
+        refresh_snapshot(result)
+    else:
+        result.attrs.pop("portfolio_snapshot", None)
+        result.attrs["portfolio_diagnostic"] = "portfolio_unavailable_for_legacy_subset"
+    return result

openbacktesting/portfolio/metrics.py

@@ -0,0 +1,186 @@
+"""Versioned monetary, trade, and path metrics; legacy statistics are retained independently."""
+
+import math
+from itertools import groupby
+
+import numpy as np
+
+from openbacktesting.portfolio.models import metric, ratio
+
+
+def mean(values):
+    return sum(values) / len(values) if values else None
+
+
+def trade_metrics(trades, opened):
+    pnl = [t["pnlNet"] for t in trades]
+    wins = [t for t in trades if t["pnlNet"] > 0]
+    losses = [t for t in trades if t["pnlNet"] < 0]
+    gp, gl = sum(t["pnlNet"] for t in wins), -sum(t["pnlNet"] for t in losses)
+    result = {}
+
+    def put(name, value, unit="ratio", **kwargs):
+        result[name] = metric(value, unit, sample=len(trades), **kwargs)
+
+    for name, value in (
+        ("closedFragmentCount", len(trades)),
+        ("openLotCount", len(opened)),
+        ("closedLotCount", len({t["lotId"] for t in trades} - {t["lotId"] for t in opened})),
+        ("openedLotCount", len({t["lotId"] for t in trades + opened})),
+        ("winningCount", len(wins)),
+        ("losingCount", len(losses)),
+        ("evenCount", len(trades) - len(wins) - len(losses)),
+    ):
+        put(name, value, "count")
+    for name, value in (
+        ("closedNetPnl", sum(pnl)),
+        ("grossProfit", gp),
+        ("grossLoss", gl),
+        ("expectedPayoff", mean(pnl)),
+        ("averageProfit", mean([t["pnlNet"] for t in wins])),
+        ("averageLoss", mean([-t["pnlNet"] for t in losses])),
+        ("closedFees", sum(t["feeTotal"] for t in trades)),
+    ):
+        put(name, value, "money", reason="no_closed_trades")
+    put(
+        "profitFactorMoney",
+        ratio(gp, gl),
+        reason="unbounded" if gp and not gl else "zero_denominator",
+    )
+    put("winRate", ratio(len(wins), len(trades)), reason="no_closed_trades")
+    put("meanTradeReturn", mean([t["returnFraction"] for t in trades]), reason="no_closed_trades")
+    for label, group in (("Trade", trades), ("Winning", wins), ("Losing", losses)):
+        put(
+            "average" + label + "Bars",
+            mean([t["barsHeld"] for t in group]),
+            "bars",
+            reason="no_samples",
+        )
+    for label, group, sign in (("Profit", wins, 1), ("Loss", losses, -1)):
+        put(
+            "average" + label + "Return",
+            mean([sign * t["returnFraction"] for t in group]),
+            reason="no_samples",
+        )
+        for suffix, key, unit in (("", "pnlNet", "money"), ("Return", "returnFraction", "ratio")):
+            item = max(group, key=lambda t: sign * t[key]) if group else None
+            put(
+                "largest" + label + suffix,
+                sign * item[key] if item else None,
+                unit,
+                reference=item["fragmentId"] if item else None,
+                reason="no_samples",
+            )
+        largest = max([sign * t["pnlNet"] for t in group], default=0.0)
+        put(
+            "largest" + label + "Share",
+            ratio(largest, gp if sign > 0 else gl),
+            reason="zero_denominator",
+        )
+    ap, al = mean([t["pnlNet"] for t in wins]), mean([-t["pnlNet"] for t in losses])
+    put("averageProfitLossRatio", ratio(ap, al) if ap is not None else None, reason="no_samples")
+    durations = [int(t["durationNs"]) for t in trades if t["durationNs"] is not None]
+    put(
+        "maxTradeDurationNs",
+        str(max(durations)) if durations else None,
+        "nanoseconds",
+        reason="no_duration",
+    )
+    put(
+        "averageTradeDurationNs",
+        str(sum(durations) // len(durations)) if durations else None,
+        "nanoseconds",
+        reason="no_duration",
+    )
+    return result
+
+
+def path_metrics(rows, initial, *, prefix="", approximate=False):
+    high = low = initial
+    max_dd = max_ru = dd_fraction = ru_fraction = 0.0
+    dd_ref = ru_ref = ddf_ref = ruf_ref = None
+    invalid_runup_base = False
+
+    # Treat same-bar highs and lows with unknown ordering as a group; compare only with earlier peaks/troughs without inventing within-group order.
+    def group_key(row):
+        return row["barIndex"] if not row.get("ordered", True) else row["observationId"]
+
+    for _, group in groupby(rows, group_key):
+        points = list(group)
+        bottom = min(points, key=lambda r: r["equity"])
+        top = max(points, key=lambda r: r["equity"])
+        dd, ru = max(0.0, high - bottom["equity"]), max(0.0, top["equity"] - low)
+        if dd > max_dd:
+            max_dd, dd_ref = dd, bottom["observationId"]
+        if ru > max_ru:
+            max_ru, ru_ref = ru, top["observationId"]
+        if high > 0 and dd / high > dd_fraction:
+            dd_fraction, ddf_ref = dd / high, bottom["observationId"]
+        if ru > 0 and low <= 0:
+            invalid_runup_base = True
+        if low > 0 and ru / low > ru_fraction:
+            ru_fraction, ruf_ref = ru / low, top["observationId"]
+        high, low = max(high, top["equity"]), min(low, bottom["equity"])
+    result = {}
+    for key, value, unit, ref in (
+        ("maxDrawdown", max_dd, "money", dd_ref),
+        ("maxRunup", max_ru, "money", ru_ref),
+        ("maxDrawdownFraction", dd_fraction, "ratio", ddf_ref),
+        ("maxRunupFraction", None if invalid_runup_base else ru_fraction, "ratio", ruf_ref),
+        ("maxDrawdownInitialFraction", max_dd / initial, "ratio", dd_ref),
+        ("maxRunupInitialFraction", max_ru / initial, "ratio", ru_ref),
+    ):
+        result[prefix + key] = metric(
+            value,
+            unit,
+            reference=ref,
+            method="sampled_bounds_v1" if approximate else "close_path_v1",
+            status="undefined" if value is None else ("approximate" if approximate else "ok"),
+            reason="nonpositive_runup_base"
+            if value is None
+            else ("unknown_intrabar_order" if approximate else None),
+        )
+    return result
+
+
+def monthly_risk(periods, rf):
+    returns = [p["equityReturn"] for p in periods]
+    if len(returns) < 2 or any(r is None for r in returns):
+        return {
+            k: metric(
+                None,
+                method="monthly_compounded_rf_v1",
+                status="insufficient_data",
+                reason="invalid_or_insufficient_periods",
+                sample=len(returns),
+            )
+            for k in ("sharpe", "sortino")
+        }
+    excess = np.asarray(returns) - ((1 + rf) ** (1 / 12) - 1)
+    denominators = (float(np.std(returns)), float(np.sqrt(np.mean(np.minimum(excess, 0) ** 2))))
+    return {
+        k: metric(
+            ratio(float(np.mean(excess)) * math.sqrt(12), d),
+            method="monthly_compounded_rf_v1",
+            reason="zero_denominator",
+            sample=len(returns),
+        )
+        for k, d in zip(("sharpe", "sortino"), denominators)
+    }
+
+
+def correlation(x, y):
+    pairs = [(a, b) for a, b in zip(x, y) if a is not None and b is not None]
+    if len(pairs) < 2:
+        return metric(
+            None,
+            status="insufficient_data",
+            reason="insufficient_pairs",
+            sample=len(pairs),
+            method="paired_period_returns_v1",
+        )
+    a, b = np.array(pairs).T
+    value = float(np.corrcoef(a, b)[0, 1]) if np.std(a) and np.std(b) else None
+    return metric(
+        value, reason="zero_variance", sample=len(pairs), method="paired_period_returns_v1"
+    )

openbacktesting/portfolio/models.py

@@ -0,0 +1,63 @@
+"""Strict plain-value encoding, metrics, and immutable snapshots without runtime objects."""
+
+import math
+
+import numpy as np
+import pandas as pd
+
+
+def time_ref(value):
+    if isinstance(value, pd.Timestamp):
+        return {
+            "kind": "aware" if value.tzinfo else "naive",
+            "value": str(value.as_unit("ns").value),
+        }
+    return {"kind": "ordinal", "value": str(value)}
+
+
+def plain(value):
+    if value is None or value is pd.NA or value is pd.NaT:
+        return None
+    if isinstance(value, dict):
+        return {str(k): plain(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [plain(v) for v in value]
+    if isinstance(value, pd.Timestamp):
+        return time_ref(value)
+    if isinstance(value, pd.Timedelta):
+        return str(value.value)
+    if isinstance(value, np.generic):
+        return plain(value.item())
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    if isinstance(value, int) and not isinstance(value, bool) and abs(value) > 2**53 - 1:
+        return str(value)
+    if isinstance(value, (str, bool, int, float)):
+        return value
+    raise TypeError(f"Portfolio does not support plain-value encoding: {type(value).__name__}")
+
+
+def metric(
+    value,
+    unit="ratio",
+    *,
+    method="openbacktesting_portfolio_v1",
+    reason=None,
+    status=None,
+    sample=None,
+    reference=None,
+):
+    value = plain(value)
+    return {
+        "value": value,
+        "unit": unit,
+        "methodId": method,
+        "status": status or ("ok" if value is not None else "undefined"),
+        "reason": (reason or "undefined_value") if value is None else (reason if status else None),
+        "sampleCount": sample,
+        "reference": reference,
+    }
+
+
+def ratio(numerator, denominator):
+    return numerator / denominator if denominator else None

openbacktesting/portfolio/periods.py

@@ -0,0 +1,164 @@
+"""Chart-calendar buckets, benchmarks, and period correlations."""
+
+from decimal import ROUND_FLOOR, Decimal
+
+import pandas as pd
+
+from openbacktesting.portfolio.metrics import correlation
+from openbacktesting.portfolio.models import time_ref
+
+
+def benchmarks(data, rows, fills, allocations, instrument, initial):
+    close_prices = data.Close.to_numpy()
+    first = next((a for a in allocations if a["kind"] == "open"), None)
+    by_id = {f["fill_id"]: f for f in fills}
+    configs = [("input_start_close", 0, float(data.Close.iloc[0]), initial)]
+    if first:
+        fill = by_id[first["fill_id"]]
+        before = next(
+            r
+            for r in rows
+            if r["phase"].startswith("before_")
+            and r["fillSequence"] < fill["sequence"]
+            and r["barIndex"] == fill["bar_index"]
+        )
+        configs.append(("first_entry_price", fill["bar_index"], fill["price"], before["equity"]))
+    result = {}
+    for name, start, price, base in configs:
+        step = Decimal(str(instrument["quantity_step"]))
+        qty = float(
+            (Decimal(str(initial)) / Decimal(str(price)) / step).to_integral_value(
+                rounding=ROUND_FLOOR
+            )
+            * step
+        )
+        if qty < instrument["min_quantity"] or qty * price < instrument["min_notional"]:
+            qty = 0.0
+        cash = initial - qty * price
+        points = []
+        for r in rows:
+            if r["phase"] not in ("bar", "terminal") or r["barIndex"] < start:
+                continue
+            equity = cash + qty * float(close_prices[r["barIndex"]])
+            strategy = initial + r["equity"] - base
+            points.append(
+                {
+                    "observationId": r["observationId"],
+                    "barIndex": r["barIndex"],
+                    "equity": equity,
+                    "pnlMoney": equity - initial,
+                    "returnFraction": (equity - initial) / initial,
+                    "strategyReturn": (strategy - initial) / initial,
+                    "outperformance": (strategy - equity) / initial,
+                    "outperformanceMoney": strategy - equity,
+                }
+            )
+        result[name] = {
+            "status": "ok",
+            "quantity": qty,
+            "cash": cash,
+            "entryPrice": price,
+            "startBar": start,
+            "costPolicy": "none",
+            "points": points,
+            "summary": {
+                key: {
+                    "minimum": min(p[key] for p in points),
+                    "maximum": max(p[key] for p in points),
+                    "current": points[-1][key],
+                }
+                for key in (
+                    "returnFraction",
+                    "strategyReturn",
+                    "outperformance",
+                    "outperformanceMoney",
+                )
+            },
+        }
+    if not first:
+        result["first_entry_price"] = {
+            "status": "not_applicable",
+            "reason": "no_entry",
+            "points": [],
+        }
+    return result
+
+
+def periodical(rows, trades, fills, benchmark, initial, index):
+    if not isinstance(index, pd.DatetimeIndex):
+        return {
+            "status": "not_applicable",
+            "reason": "ordinal_index",
+            "buckets": {},
+            "correlations": {},
+        }
+    result, correlations = {}, {}
+    start, end = index[0], index[max(r["barIndex"] for r in rows)]
+    timezone = index.tz
+    naive = index.tz_localize(None) if timezone else index
+    for label, freq in (
+        ("daily", "D"),
+        ("weekly", "W-SUN"),
+        ("monthly", "M"),
+        ("quarterly", "Q"),
+        ("yearly", "Y"),
+    ):
+        keys = list(naive.to_period(freq))
+        covered = pd.period_range(keys[0], keys[max(r["barIndex"] for r in rows)], freq=freq)
+        groups = {key: [] for key in covered}
+        closed = {key: [] for key in covered}
+        paid = {key: 0.0 for key in covered}
+        for row in rows:
+            groups[keys[row["barIndex"]]].append(row)
+        for t in trades:
+            closed[keys[t["exit"]["barIndex"]]].append(t)
+        for f in fills:
+            paid[keys[f["bar_index"]]] += f["fee"]
+        previous, previous_bench = initial, initial
+        bench_by_bar = {p["barIndex"]: p["equity"] for p in benchmark["points"]}
+        buckets = []
+        for key, group in groups.items():
+            last = group[-1]["equity"] if group else previous
+            # Carry forward only unobserved buckets within the calendar range; never extend the execution range.
+            bvalue = bench_by_bar[group[-1]["barIndex"]] if group else previous_bench
+            left, right = key.start_time, (key + 1).start_time
+            if timezone:
+                left = left.tz_localize(timezone, ambiguous=True, nonexistent="shift_forward")
+                right = right.tz_localize(timezone, ambiguous=True, nonexistent="shift_forward")
+            ts = closed[key]
+            values = [r["equity"] for r in group]
+            buckets.append(
+                {
+                    "start": time_ref(left),
+                    "endExclusive": time_ref(right),
+                    "partial": left < start or right > end,
+                    "carriedForward": not group,
+                    "count": len(group),
+                    "firstBar": group[0]["barIndex"] if group else None,
+                    "lastBar": group[-1]["barIndex"] if group else None,
+                    "closedNetPnl": sum(t["pnlNet"] for t in ts),
+                    "grossProfit": sum(max(0, t["pnlNet"]) for t in ts),
+                    "grossLoss": sum(max(0, -t["pnlNet"]) for t in ts),
+                    "closedFees": sum(t["feeTotal"] for t in ts),
+                    "fees": paid[key],
+                    "equityReturn": last / previous - 1 if previous > 0 else None,
+                    "benchmarkReturn": bvalue / previous_bench - 1 if previous_bench > 0 else None,
+                    "favorableExcursion": max([0.0] + [v - previous for v in values]),
+                    "adverseExcursion": max([0.0] + [previous - v for v in values]),
+                    "coverage": "partial"
+                    if any(r["coverage"] == "partial" for r in group)
+                    else "complete_under_bar_model",
+                }
+            )
+            previous, previous_bench = last, bvalue
+        for b in buckets:
+            b["outperformance"] = (
+                b["equityReturn"] - b["benchmarkReturn"]
+                if b["equityReturn"] is not None and b["benchmarkReturn"] is not None
+                else None
+            )
+        result[label] = buckets
+        correlations[label] = correlation(
+            [b["equityReturn"] for b in buckets], [b["benchmarkReturn"] for b in buckets]
+        )
+    return {"status": "ok", "reason": None, "buckets": result, "correlations": correlations}

openbacktesting/portfolio/rates.py

@@ -0,0 +1,14 @@
+"""Pure numeric validation of statistical rates without runtime or account dependencies."""
+
+from math import isfinite
+from numbers import Real
+
+
+def validate_risk_free_rate(value: float) -> float:
+    """Accept annualized fractions; reject booleans, nonfinite values, and out-of-range values."""
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise TypeError("risk_free_rate must be a finite number")
+    value = float(value)
+    if not isfinite(value) or not -1 < value < 1:
+        raise ValueError("risk_free_rate must be in (-1, 1)")
+    return value

openbacktesting/portfolio/snapshot.py

@@ -0,0 +1,111 @@
+"""Freeze complete facts at runtime; derive reports on reads without executing user code."""
+
+import json
+
+import pandas as pd
+
+from openbacktesting.portfolio.builder import build_report, legacy
+from openbacktesting.portfolio.models import plain, time_ref
+from openbacktesting.portfolio.trades import project_trades
+
+
+class PortfolioSnapshot(str):
+    """Immutable versioned fact text; read complete reports through to_dict.
+
+    Snapshots hold no strategy, pandas objects, or mutable inputs. Derived analyses read only frozen facts;
+    the text itself is an internal storage format; cross-language consumers use export_result reports.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, payload: str):
+        return super().__new__(cls, payload)
+
+    def to_dict(self) -> dict:
+        """Compute and return an independent strict JSON report without modifying the snapshot or executing strategies."""
+        return build_report(json.loads(self))
+
+
+def freeze(payload):
+    return PortfolioSnapshot(
+        json.dumps(
+            payload, default=plain, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+        )
+    )
+
+
+def capture_snapshot(stats, data, observations, reason, context=None):
+    facts, closed, opened = project_trades(stats, observations)
+    columns = list(observations.rows[0])
+    keys = (
+        "statistics_initial_equity",
+        "statistics_risk_free_rate",
+        "instrument",
+        "execution_policy_version",
+        "trading_schema_version",
+        "engine_version",
+        "commission",
+        "spread",
+        "slippage",
+        "margin",
+        "end_policy",
+        "execution_timing",
+        "hedging",
+        "allow_short",
+        "max_gross_exposure",
+        "diagnostics",
+    )
+    attrs = {k: plain(stats.attrs[k]) for k in keys}
+    attrs.update({k: plain(stats.attrs.get(k)) for k in ("input_snapshot", "backtest_snapshot")})
+    return freeze(
+        {
+            "format": "openbacktesting_portfolio_facts_v1",
+            "facts": facts,
+            "closed": closed,
+            "opened": opened,
+            "columns": columns,
+            "rows": [list(r.values()) for r in observations.rows],
+            "index": data.index.as_unit("ns").asi8.astype(str).tolist()
+            if isinstance(data.index, pd.DatetimeIndex)
+            else data.index.tolist(),
+            "close": data.Close.tolist(),
+            "high": data.High.tolist(),
+            "low": data.Low.tolist(),
+            "timeKind": time_ref(data.index[0])["kind"],
+            "timezone": str(data.index.tz)
+            if isinstance(data.index, pd.DatetimeIndex) and data.index.tz
+            else None,
+            "reason": reason,
+            "context": plain(context),
+            "attrs": attrs,
+            "legacy": legacy(stats),
+        }
+    )
+
+
+def refresh_snapshot(result):
+    snapshot = result.attrs.get("portfolio_snapshot")
+    if snapshot is None:
+        return
+    source = json.loads(snapshot)
+    source["attrs"]["statistics_risk_free_rate"] = result.attrs["statistics_risk_free_rate"]
+    source["attrs"]["backtest_snapshot"] = plain(result.attrs.get("backtest_snapshot"))
+    source["legacy"] = legacy(result)
+    result.attrs["portfolio_snapshot"] = freeze(source)
+
+
+def get_snapshot(result: pd.Series) -> PortfolioSnapshot:
+    """Read the frozen fact snapshot; explicitly reject old results or trade subsets lacking complete facts.
+
+    Raises:
+        ValueError: The result did not collect Portfolio data.
+    """
+    snapshot = result.attrs.get("portfolio_snapshot")
+    if not isinstance(snapshot, PortfolioSnapshot):
+        raise ValueError("portfolio_snapshot_missing")  # noqa: TRY004 — missing snapshot rather than incorrect argument type
+    return snapshot
+
+
+def export_result(result: pd.Series) -> dict:
+    """Return an independent plain-value copy of the complete report without file, network, or plotting side effects."""
+    return get_snapshot(result).to_dict()