report.hpp

Go to the documentation of this file.

#pragma once
 
#include "./engine.hpp"
 
#include <algotradelib/analytics>
#include <algotradelib/core>
 
#include <cstddef>
#include <chrono>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace algotradelib {
namespace backtest {


struct ReportCaveats {
  LimitFillPrice limit_fill_{LimitFillPrice::AT_LIMIT};
  std::vector<AppliedRate> applied_rates_;
  std::size_t inclusive_commission_executions_{0};
  std::optional<VenueKey> asserted_venue_;
  std::string commission_tariff_;
  bool cost_totals_incomplete_{false};
  Decimal64 slippage_basis_points_;
  int slippage_ticks_{0};

  bool multiple_instruments_{false};

  std::size_t gaps_{0};

  std::size_t unfilled_{0};

  std::size_t quotes_{0};

  std::size_t unchecked_fill_causality_{0};

  static constexpr bool volume_ignored = true;

  static constexpr bool bar_tape_unverified = true;

  static constexpr bool sellable_is_whole_holding = true;

  static constexpr bool buying_power_is_ledger_cash = true;

  std::size_t unvalued_bars_{0};
  std::optional<std::chrono::system_clock::time_point> first_unvalued_;
  std::size_t stop_releases_{0};
  std::size_t stop_fills_intrabar_{0};
  std::size_t limit_fills_bounded_{0};
  std::size_t overdrawn_bars_{0};
  std::optional<std::chrono::system_clock::time_point> first_overdrawn_;
  std::optional<Money> lowest_cash_;
  std::size_t other_currency_executions_{0};
  std::optional<std::chrono::system_clock::time_point> lowest_cash_at_;
  std::optional<SellTax> sell_tax_;
  std::size_t expired_day_orders_{0};
};

struct Report {
  std::size_t bars_{0};
  std::size_t executions_{0};

  Decimal64 opening_equity_;
  Decimal64 closing_equity_;
  math::Scalar total_return_{0};

  math::Scalar sharpe_{0};
  math::Scalar annualized_sharpe_{0};
  math::Scalar sortino_{0};
  math::Scalar max_drawdown_{0};
  math::Scalar total_turnover_{0};

  std::optional<Decimal64> commission_paid_;
  std::vector<Money> commission_by_currency_;
  std::optional<Decimal64> institution_fees_paid_;
  std::vector<Money> institution_by_currency_;
  std::optional<Decimal64> slippage_paid_;
  std::vector<Money> slippage_by_currency_;

  std::size_t rejected_{0};
  std::size_t refused_{0};

  std::optional<BrokerError> halted_;
  std::size_t aborted_{0};

  ReportCaveats caveats_;
  std::optional<Decimal64> tax_paid_;
  std::vector<Money> tax_by_currency_;
};

inline Report summarize(
  const ReplayResult& result,
  const NextBarFillModel& fills,
  std::optional<math::Scalar> periods_per_year = std::nullopt,
  math::Scalar risk_free = math::Scalar{0}
) {
  Report report;
  report.bars_ = result.bars_;
  report.executions_ = result.executions_.size();
  report.rejected_ = result.rejected_.size();
  report.refused_ = result.refused_.size();
 
  report.caveats_.limit_fill_ = fills.limit_price();
  report.halted_ = result.halted_;
  report.aborted_ = result.aborted_;
  if (fills.commission().is_scheduled()) {
    report.caveats_.asserted_venue_ = fills.commission().asserted_venue();
  }
  report.caveats_.commission_tariff_ = std::string(fills.commission().tariff());
  report.caveats_.slippage_basis_points_ = fills.slippage().basis_points_;
  report.caveats_.slippage_ticks_ = fills.slippage().ticks_;
  report.caveats_.gaps_ = result.gaps_;
  report.caveats_.unfilled_ = result.unfilled_;
  report.caveats_.stop_releases_ = result.stop_releases_;
  report.caveats_.stop_fills_intrabar_ = result.stop_fills_intrabar_;
  report.caveats_.limit_fills_bounded_ = result.limit_fills_bounded_;
  report.caveats_.quotes_ = result.quotes_;
  report.caveats_.unchecked_fill_causality_ = result.unchecked_fill_causality_;
  report.caveats_.unvalued_bars_ = result.unvalued_bars_;
  report.caveats_.first_unvalued_ = result.first_unvalued_;
  report.caveats_.overdrawn_bars_ = result.overdrawn_bars_;
  report.caveats_.first_overdrawn_ = result.first_overdrawn_;
  report.caveats_.lowest_cash_ = result.lowest_cash_;
  report.caveats_.lowest_cash_at_ = result.lowest_cash_at_;
  report.caveats_.expired_day_orders_ = result.expired_day_orders_;
 
  // Costs summed exactly, because they are money -- and **per currency**, because a replay whose
  // instruments span markets would otherwise have won added to dollars to make one scalar.
  // Checked, and a refusal is recorded rather than swallowed: leaving the previous total in place
  // and carrying on produced a plausible figure that was short by an unknown amount, which is the
  // one outcome every exact-decimal path here exists to prevent. Two individually representable
  // commissions whose sum does not fit is enough to reach it, and a probe did.
  bool costs_fit = true;
  const auto accumulate = [&costs_fit](std::vector<Money>& totals, const Money& amount) {
    for (auto& held : totals) {
      if (held.currency_ == amount.currency_) {
        const auto sum = decimal_add(held.amount_, amount.amount_);
        if (!sum) {
          costs_fit = false;
          return;
        }
        held.amount_ = *sum;
        return;
      }
    }
    totals.push_back(amount);
  };
 
  std::vector<InstrumentId> seen;
  for (const auto& execution : result.executions_) {
    accumulate(report.commission_by_currency_, Money{execution.commission_, execution.currency_});
    if (execution.institution_fee_) {
      accumulate(
        report.institution_by_currency_, Money{*execution.institution_fee_, execution.currency_}
      );
    } else {
      // The rate stated one figure, so this execution's commission is inclusive and the split total
      // below cannot be completed. Counted rather than approximated.
      ++report.caveats_.inclusive_commission_executions_;
    }
    // The rate that charged it, collapsed so an unchanged rate is one row with a count rather than
    // one row per fill. Accumulated here, from the executions the ledger accepted, rather than from
    // the schedule: a row the replay never used is not a rate this run applied.
    bool counted = false;
    for (auto& applied : report.caveats_.applied_rates_) {
      if (applied == execution.applied_) {
        ++applied.executions_;
        counted = true;
        break;
      }
    }
    if (!counted) {
      auto entry = execution.applied_;
      entry.executions_ = 1;
      report.caveats_.applied_rates_.push_back(std::move(entry));
    }
    // The tax, totalled per currency, over the executions in the market it was stated for: another
    // market's fills pay none by construction, and counting them would add a zero row in their
    // currency and cost a single-currency total its scalar.
    if (fills.sell_tax() && execution.fill_.instrument_.country_ == fills.sell_tax()->country_) {
      accumulate(report.tax_by_currency_, Money{execution.tax_, execution.currency_});
    }
    // Slippage is a per-share price difference, so its cost is that times the quantity -- and it
    // is totalled per currency like every other cost, because a replay can hold fills in more
    // than one and adding them would produce a figure denominated in nothing.
    if (const auto cost = decimal_multiply(execution.slippage_, execution.fill_.quantity_)) {
      accumulate(report.slippage_by_currency_, Money{*cost, execution.currency_});
    } else {
      costs_fit = false;
    }
    bool known = false;
    for (const auto& id : seen) {
      if (id == execution.fill_.instrument_) {
        known = true;
        break;
      }
    }
    if (!known) {
      seen.push_back(execution.fill_.instrument_);
    }
  }
  report.caveats_.cost_totals_incomplete_ = !costs_fit;
  // A scalar is stated only where one can be true: one currency, something executed, and every
  // addition representable. On a mixed-currency replay the per-currency vectors are the whole
  // answer, and on an arithmetic refusal nothing is stated at all rather than a figure short by an
  // amount nobody can name.
  if (costs_fit && report.commission_by_currency_.size() == 1) {
    report.commission_paid_ = report.commission_by_currency_.front().amount_;
  }
  // Present only when every charged rate split the two components, so the total is complete rather
  // than a sum over the subset that happened to state one.
  if (costs_fit && report.caveats_.inclusive_commission_executions_ == 0 &&
      report.institution_by_currency_.size() == 1) {
    report.institution_fees_paid_ = report.institution_by_currency_.front().amount_;
  }
  if (costs_fit && report.slippage_by_currency_.size() == 1) {
    report.slippage_paid_ = report.slippage_by_currency_.front().amount_;
  }
  report.caveats_.sell_tax_ = fills.sell_tax();
  if (fills.sell_tax() && costs_fit && report.tax_by_currency_.size() == 1) {
    report.tax_paid_ = report.tax_by_currency_.front().amount_;
  }
  report.caveats_.multiple_instruments_ = seen.size() > 1;
  for (const auto& execution : result.executions_) {
    if (!(execution.currency_ == result.currency_)) {
      ++report.caveats_.other_currency_executions_;
    }
  }
 
  if (result.equity_.empty()) {
    // Nothing to measure. Every figure stays unobserved rather than becoming zero, which would read as
    // a flat result rather than as an absent one.
    report.total_return_ = math::missing();
    report.sharpe_ = math::missing();
    report.annualized_sharpe_ = math::missing();
    report.sortino_ = math::missing();
    report.max_drawdown_ = math::missing();
    report.total_turnover_ = math::missing();
    return report;
  }
 
  report.opening_equity_ = result.equity_.front().equity_;
  report.closing_equity_ = result.equity_.back().equity_;
 
  // The returns and the equity curve, as the columns the metrics take.
  math::Vector returns(static_cast<math::Index>(result.equity_.size()));
  math::Vector levels(static_cast<math::Index>(result.equity_.size()));
  for (std::size_t at = 0; at < result.equity_.size(); ++at) {
    returns[static_cast<math::Index>(at)] = result.equity_[at].period_return_;
    levels[static_cast<math::Index>(at)] = analytics::to_scalar(result.equity_[at].equity_);
  }
 
  // From a negative opening the ratio's sign reverses (a replay may start with negative cash), so a
  // non-positive opening has no return and no turnover, as a zero one has none.
  const auto opening = analytics::to_scalar(report.opening_equity_);
  report.total_return_ = !(opening > math::Scalar{0}) ?
    math::undefined() :
    analytics::to_scalar(report.closing_equity_) / opening - math::Scalar{1};
 
  report.sharpe_ = analytics::sharpe(returns, risk_free);
  report.sortino_ = analytics::sortino(returns, risk_free);
  // Equity at or below zero before the end leaves the periods after it without a return
  // (`EquityPoint::period_return_`), so no ratio describes the run.
  for (std::size_t at = 0; at + 1 < result.equity_.size(); ++at) {
    if (result.equity_[at].equity_.coefficient() <= 0) {
      report.sharpe_ = math::undefined();
      report.sortino_ = math::undefined();
      break;
    }
  }
  report.max_drawdown_ = analytics::max_drawdown(levels).magnitude_;
 
  report.annualized_sharpe_ = periods_per_year ?
    analytics::annualize_ratio(report.sharpe_, *periods_per_year) :
    math::missing();
 
  // Every trade outside the curve: it holds only the opening cash, and its figures describe no trading.
  const auto outside = report.caveats_.other_currency_executions_;
  if (outside > 0 && outside == result.executions_.size()) {
    report.total_return_ = math::missing();
    report.sharpe_ = math::missing();
    report.annualized_sharpe_ = math::missing();
    report.sortino_ = math::missing();
    report.max_drawdown_ = math::missing();
  }
 
  // Turnover from the executions rather than from a weight matrix, because a replay knows what it
  // actually traded. One-way, matching `analytics::one_way_turnover`: the fraction of equity that
  // changed hands.
  // Same money on both sides, or no figure at all.
  report.total_turnover_ = !(opening > math::Scalar{0}) ? math::undefined() : math::Scalar{0};
  if (outside > 0) {
    report.total_turnover_ = math::missing();
  }
  if (math::observed(report.total_turnover_)) {
    for (const auto& execution : result.executions_) {
      const auto traded = decimal_multiply(execution.fill_.quantity_, execution.fill_.price_);
      if (traded) {
        report.total_turnover_ += analytics::to_scalar(*traded) / opening;
      }
    }
  }
 
  return report;
}
 
} // namespace backtest
} // namespace algotradelib