openscript 0.4.0__py3-none-any.whl

openscript/accounting/report.py

@@ -0,0 +1,82 @@
+"""The report: what a run came to, folded from its fills and its bar closes.
+
+**The evaluation order is fixed here and nowhere else**, because a report that is
+right to eleven digits and different in the twelfth fails a conformance
+comparison months later on somebody else's engine, and the cause is always a line
+nobody thought was arithmetic. Fills in ``seq`` order, charge lines in declaration
+order, one rounding per fill total, no collection re-summed in another order, no
+dependence on a mapping's iteration order, no clock and no random number anywhere
+in this module.
+
+**What the report is not is read by a script.** The money entries of the ``pos``
+namespace stay planned and go on refusing at the call. The moment a script can
+read its own equity mid-run, the money layer joins the execution path and
+therefore joins the conformance surface, and every formula in this module has to
+be agreed by a second engine before a script may branch on it. This module
+computes the money after the fact from a record; whether a script may read it is a
+later decision, and that this module imports no interpreter is the structural half
+of keeping that decision open.
+
+**A charge belongs to the fill that incurred it.** One fill's total is rounded
+once, and nothing here rounds it again or re-sums the collection in another order,
+so the trades' charges and the summary's charges are the same money and a test
+asserts it rather than a page claiming it.
+
+A run carried out under no schedule at all is charged nothing, which is a study of
+the strategy before costs and is a thing worth being able to ask for. It is not a
+default: the caller states which it wants.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Tuple
+
+from .charges import ChargeSchedule, charge_for
+from .equity import EquityPoint, equity_over
+from .shapes import BarMark, Contract, RecordedFill
+from .analysis import TradeAnalysis, analysis_of
+from .statistics import Summary, summary_of
+from .trades import Trade, trades_of
+
+
+@dataclass(frozen=True)
+class Report:
+    """Everything a run is reported as, and nothing a chart has to compute."""
+
+    summary: Summary
+    #: The trades by direction, by extreme and by run.
+    analysis: TradeAnalysis
+    trades: Tuple[Trade, ...]
+    equity: Tuple[EquityPoint, ...]
+
+
+def report_of(
+    fills: Sequence[RecordedFill],
+    marks: Sequence[BarMark],
+    schedule: Optional[ChargeSchedule],
+    contract: Contract,
+    capital: float,
+) -> Report:
+    """The whole report, folded from the fills, the bar closes and the schedule.
+
+    **One pass, in one order, and the order is the result.** The fills are put in
+    ``seq`` order once, here, and every fold below reads that same list: the
+    charges are computed in it, the trades are built from it and the curve is
+    marked along it. A second ordering anywhere would be a report that is right to
+    eleven digits and different in the twelfth on somebody else's engine.
+    """
+    ordered = sorted(fills, key=lambda fill: fill.seq)
+    charges = [
+        0.0 if schedule is None else charge_for(schedule, fill, contract).total
+        for fill in ordered
+    ]
+
+    trades = trades_of(ordered, charges, marks, contract)
+    equity = equity_over(trades, marks, contract, capital)
+    summary = summary_of(trades, equity, contract, capital)
+
+    return Report(
+        summary=summary,
+        analysis=analysis_of(trades),
+        trades=trades,
+        equity=equity,
+    )

openscript/accounting/shapes.py

@@ -0,0 +1,74 @@
+"""The atoms the money is folded from: a fill, a contract and a bar's close.
+
+**Everything in this module is portable data.** A shape here is what a JSON
+reader gives back, so a report can be computed here, stored by a platform, sent
+to another process and recomputed there without this implementation being
+present. That is not a convenience. A run record is the conformance case a second
+engine is handed, and a case that can only be read by the engine that wrote it
+proves nothing about either.
+
+**A fill is the only thing money is folded from.** Not a position, not a ledger
+row, not a running total the engine happened to be holding: the fills the engine
+settled, in the order it settled them, each naming the position reference it
+moved and the size of that reference either side of the settlement. Every figure
+in a report is a function of that list and of the bars it is marked against,
+which is what makes a report reproducible from a record with no engine in the
+room.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Contract:
+    """The instrument facts a run was carried out under, as the host stated them.
+
+    A snapshot rather than a reference. An instrument's lot size and tick size
+    change, and a report recomputed months later under today's facts would be a
+    different study wearing the same name, so the facts travel with the run.
+    """
+
+    currency: str = "CUR"
+    symbol: Optional[str] = None
+    exchange: Optional[str] = None
+    tick_size: Optional[float] = None
+    lot_size: Optional[float] = None
+    #: Money per 1.0 of price per unit; 1 when the host states none.
+    point_value: float = 1.0
+    #: Money rounding digits, half to even, once per fill total.
+    digits: int = 2
+
+
+@dataclass(frozen=True)
+class RecordedFill:
+    """One settled fill. Every money figure is folded from these and nothing else."""
+
+    seq: int
+    intent_id: int
+    order_ref: str
+    tag: str
+    position_ref: int
+    side: str
+    #: Positive, this fill's own quantity.
+    units: float
+    price: float
+    bar_index: int
+    bar_time: Optional[float]
+    ref_size_before: float
+    ref_size_after: float
+
+
+@dataclass(frozen=True)
+class BarMark:
+    """One bar as the report marks against it.
+
+    Close only: ``stdlib.md`` 17.4 marks an open position to this bar's close, and
+    an intrabar extreme is a price the strategy could not have acted on.
+    """
+
+    bar_index: int
+    time: Optional[float]
+    close: Optional[float]
+    #: False for a warmup bar, which executes and is not reported.
+    in_report: bool = True

openscript/accounting/statistics.py

@@ -0,0 +1,300 @@
+"""The summary, and the two figures in it that decide whether a run means anything.
+
+**Win rate is over closed trades, on net profit after charges**, and a trade whose
+net is exactly zero is a scratch counted in neither half. It is absent where
+nothing closed rather than zero, because zero is a number a reader compares
+against and "nothing has closed yet" is not a losing run.
+
+**Expectancy is money per closed trade**, and it has two spellings that must
+agree: the win rate against the average win and the average loss, and the net
+profit over the trade count. Two spellings of one figure that disagree is how a
+report loses its reader, so one of them is the computation and the other is a
+test.
+
+**And its standard error is what answers the question a comparison asks.** The
+sample standard deviation of per-trade net over the square root of the trade count
+is what turns "this run made more" into "this run made more than the noise", and
+without it a difference of two percent over eleven trades reads like a result.
+
+Bar times rather than bar indices, wherever a figure addresses a bar: loading more
+history shifts every index, so a report that addresses a bar by index changes when
+the warmup changes.
+
+## Which trades a figure is counted over, which is three different answers
+
+Almost every defect this file can have is a figure counted over the wrong half of
+a list holding closed trades and open ones together.
+
+- **Net profit, and everything derived from it**, is over closed trades. An open
+  trade's net is its charges so far with no gross against them, so counting it
+  would report a run holding a winner as having lost money.
+- **Charges are over every trade**, open ones included, because the money left the
+  account whether or not the position came back. This is the figure the equity
+  curve's last point carries, and the two are asserted equal.
+- **The drawdown figures are over the curve** and not over the trades at all. A
+  drawdown is a thing equity did between two trades as often as during one.
+
+## The cases where a statistic is not a number
+
+Every one of them is a division, and every one is answered here rather than left
+to arrive as a value a document turns into nothing. Nothing closed: the win rate
+is absent, which is a different claim from zero, and expectancy and its error are
+zero because the type is money and money is not nullable. One closed trade: a
+sample of one has no spread, so the standard error is zero. Every closed trade a
+scratch: no denominator, so the win rate is absent again. Nothing lost: the profit
+factor is absent rather than an infinity. Everything lost: the profit factor is
+zero, expectancy is negative, the average win is zero, and none of the four is a
+division by zero.
+"""
+
+import math
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+from .equity import EquityPoint, bars_in_market_over, ratio_of
+from .shapes import Contract
+from .trades import Trade
+
+
+@dataclass(frozen=True)
+class Summary:
+    """What the whole run came to."""
+
+    capital: float
+    currency: str
+    net_profit: float
+    #: Sum of winning trades, before charges.
+    gross_profit: float
+    #: The losing trades' gross, as a magnitude, and it can come out at or below
+    #: zero: a trade whose gross was positive and whose charges took it under
+    #: lands in the losses carrying a positive gross. ``_tally_of`` says why that
+    #: is preferred to counting one trade as a loser in one figure and a winner in
+    #: another, and it is written here because a reader dividing by it was handed a
+    #: negative profit factor with nothing saying that could happen.
+    gross_loss: float
+    charges: float
+    #: net profit over capital, a fraction and not a figure times a hundred.
+    return_percent: float
+    #: Closed only.
+    trade_count: int
+    open_trade_count: int
+    wins: int
+    losses: int
+    #: Exactly zero net.
+    scratches: int
+    #: wins over wins plus losses, absent when none closed.
+    win_rate: Optional[float]
+    average_win: float
+    #: Positive magnitude.
+    average_loss: float
+    #: Money per closed trade.
+    expectancy: float
+    expectancy_standard_error: float
+    #: Gross profit over gross loss, absent where there is no ratio to take. A
+    #: profit factor is a non-negative ratio everywhere it is used, so a negative
+    #: one is not a surprising value, it is a number nobody can act on.
+    profit_factor: Optional[float]
+    #: Zero or negative, the same sign the curve states it with.
+    max_drawdown: float
+    #: The deepest point's own fraction, not the worst fraction of any point.
+    max_drawdown_percent: float
+    #: A bar time, never an index.
+    max_drawdown_at: Optional[float]
+    longest_drawdown_bars: int
+    #: Zero or positive, the mirror of ``max_drawdown`` and read against it. A
+    #: run that made ten and gave back nine is a different strategy from one
+    #: that made one and kept it, and the two report the same net.
+    max_run_up: float
+    #: The highest point's own fraction, not the best fraction of any point.
+    max_run_up_percent: float
+    #: A bar time, never an index, and not the bar ``max_drawdown_at`` names.
+    max_run_up_at: Optional[float]
+    average_bars_held: Optional[float]
+    bars_in_market: int
+    bar_count: int
+
+
+@dataclass
+class _Tally:
+    """The closed trades split three ways, and the sums each half contributes."""
+
+    net_profit: float = 0.0
+    gross_profit: float = 0.0
+    gross_loss: float = 0.0
+    charges: float = 0.0
+    trade_count: int = 0
+    open_trade_count: int = 0
+    wins: int = 0
+    losses: int = 0
+    scratches: int = 0
+    win_total: float = 0.0
+    loss_total: float = 0.0
+    held_total: float = 0.0
+    held_count: int = 0
+
+
+@dataclass
+class _Depth:
+    """The deepest point of the curve, and how long the run stayed under water."""
+
+    max_drawdown: float = 0.0
+    max_drawdown_percent: float = 0.0
+    max_drawdown_at: Optional[float] = None
+    longest_drawdown_bars: int = 0
+    max_run_up: float = 0.0
+    max_run_up_percent: float = 0.0
+    max_run_up_at: Optional[float] = None
+
+
+def _tally_of(trades: Sequence[Trade]) -> _Tally:
+    """One pass over the trades, in the order they are given.
+
+    A trade wins or loses on its net after charges, and its gross is what it
+    contributes to the gross figures: "the sum of the winning trades, before
+    charges" is two statements and this is where they meet. The one arrangement
+    that reads oddly is a trade whose gross was positive and whose charges took it
+    under, which lands in the losses and takes its positive gross with it. That is
+    on purpose: the alternative is a trade counted as a loser in one figure and a
+    winner in another, and a profit factor whose two halves are counted over
+    different sets is worse than one whose magnitude is odd on a trade that barely
+    moved.
+    """
+    tally = _Tally()
+    for trade in trades:
+        tally.charges += trade.charges
+        if trade.is_open:
+            tally.open_trade_count += 1
+            continue
+        tally.trade_count += 1
+        tally.net_profit += trade.net_profit
+        if trade.bars_held is not None:
+            tally.held_total += trade.bars_held
+            tally.held_count += 1
+        if trade.net_profit > 0:
+            tally.wins += 1
+            tally.win_total += trade.net_profit
+            tally.gross_profit += trade.gross_profit
+        elif trade.net_profit < 0:
+            tally.losses += 1
+            tally.loss_total += trade.net_profit
+            tally.gross_loss -= trade.gross_profit
+        else:
+            tally.scratches += 1
+    return tally
+
+
+def _depth_of(equity: Sequence[EquityPoint]) -> _Depth:
+    """The deepest the curve went, named as one point rather than as three figures.
+
+    The money, the fraction and the time all come from the same point, and the
+    point is the deepest in money with the earliest one winning a tie. Taking the
+    worst fraction from one bar and the worst money from another would describe a
+    moment the run never had.
+
+    The longest run is the longest stretch of consecutive bars under a peak, which
+    is often the figure that actually stops a trader, and it is not the total
+    number of bars spent under water.
+    """
+    depth = _Depth()
+    under = 0
+    for point in equity:
+        if point.drawdown < depth.max_drawdown:
+            depth.max_drawdown = point.drawdown
+            depth.max_drawdown_percent = point.drawdown_percent
+            depth.max_drawdown_at = point.time
+        if point.drawdown < 0:
+            under += 1
+            if under > depth.longest_drawdown_bars:
+                depth.longest_drawdown_bars = under
+        else:
+            under = 0
+        # Strictly greater, so the earliest bar reaching the height wins the
+        # tie, which is the rule the depth above is picked by. The two figures
+        # name different bars and each names the first that reached it.
+        if point.run_up > depth.max_run_up:
+            depth.max_run_up = point.run_up
+            depth.max_run_up_percent = point.run_up_percent
+            depth.max_run_up_at = point.time
+    return depth
+
+
+def _standard_error_of(
+    trades: Sequence[Trade], expectancy: float, trade_count: int
+) -> float:
+    """The sample deviation of per-trade net over the root of the count.
+
+    The sample deviation, with the count less one under it, and not the population
+    one. The trades a run took are a sample of the trades the strategy would take,
+    which is the whole reason this figure is here, and the population spelling
+    understates the spread by exactly the amount that matters on the short runs
+    where the question is asked. Fewer than two closed trades has no spread to
+    measure and gives zero.
+    """
+    if trade_count < 2:
+        return 0.0
+    squares = 0.0
+    for trade in trades:
+        if trade.is_open:
+            continue
+        away = trade.net_profit - expectancy
+        squares += away * away
+    return math.sqrt(squares / (trade_count - 1) / trade_count)
+
+
+def summary_of(
+    trades: Sequence[Trade],
+    equity: Sequence[EquityPoint],
+    contract: Contract,
+    capital: float,
+) -> Summary:
+    """The whole run in one shape, folded from its trades and its own curve.
+
+    The curve is passed in rather than recomputed, because a summary that folded
+    its own would be a second equity curve with a second set of rounding, and the
+    first disagreement between them would be a drawdown figure that no point in the
+    reported curve ever reached.
+    """
+    tally = _tally_of(trades)
+    depth = _depth_of(equity)
+    decided = tally.wins + tally.losses
+
+    # Net over the closed count, and nothing else, because this is the figure the
+    # other spelling is checked against. The win rate spelling divides by the
+    # decided trades instead, so the two are the same number exactly when no trade
+    # scratched.
+    expectancy = 0.0 if tally.trade_count == 0 else tally.net_profit / tally.trade_count
+
+    return Summary(
+        capital=capital,
+        currency=contract.currency,
+        net_profit=tally.net_profit,
+        gross_profit=tally.gross_profit,
+        gross_loss=tally.gross_loss,
+        charges=tally.charges,
+        return_percent=ratio_of(tally.net_profit, capital),
+        trade_count=tally.trade_count,
+        open_trade_count=tally.open_trade_count,
+        wins=tally.wins,
+        losses=tally.losses,
+        scratches=tally.scratches,
+        win_rate=None if decided == 0 else tally.wins / decided,
+        average_win=0.0 if tally.wins == 0 else tally.win_total / tally.wins,
+        average_loss=0.0 if tally.losses == 0 else -tally.loss_total / tally.losses,
+        expectancy=expectancy,
+        expectancy_standard_error=_standard_error_of(trades, expectancy, tally.trade_count),
+        profit_factor=(
+            tally.gross_profit / tally.gross_loss if tally.gross_loss > 0 else None
+        ),
+        max_drawdown=depth.max_drawdown,
+        max_drawdown_percent=depth.max_drawdown_percent,
+        max_drawdown_at=depth.max_drawdown_at,
+        longest_drawdown_bars=depth.longest_drawdown_bars,
+        max_run_up=depth.max_run_up,
+        max_run_up_percent=depth.max_run_up_percent,
+        max_run_up_at=depth.max_run_up_at,
+        average_bars_held=(
+            None if tally.held_count == 0 else tally.held_total / tally.held_count
+        ),
+        bars_in_market=bars_in_market_over(trades, equity),
+        bar_count=len(equity),
+    )