`trading.optimizer.analysis.metrics`

trading.optimizer.analysis.metrics

DrawdownMetrics

Bases: NamedTuple

The drawdown metrics for a backtest. Holds the worst possible risk and volatility of a strategy.

Attributes:

Name	Type	Description
`max_drawdown`	`percent \| None`	The worst single historical loss of the strategy.
`average_drawdown`	`percent \| None`	The average of historical losses of the strategy.

Metrics

Bases: NamedTuple

The metrics of a single backtest, used to identify the effectiveness of a strategy.

Attributes:

Name	Type	Description
`returns`	`ReturnMetrics`	The return (cash, units) metrics for the strategy.
`risk`	`RiskMetrics`	The risk (reliability) metrics for the strategy.
`drawdowns`	`DrawdownMetrics`	The drawdown (losses) metrics for the strategy.
`trades`	`TradeMetrics`	The number of trades made, losses, wins, profits, etc.

repr

__repr__() -> str

Returns a string representation of the metrics.

Source code in src\contango\trading\optimizer\analysis\metrics.py

def __repr__(self) -> str:
    """
    Returns a string representation of the metrics.
    """
    def fmt_f(val: float | None) -> str:
        return f"{val:.2f}" if val is not None else "N/A"

    return (
        "Backtest Metrics:\n"
        f"  Total Return: {fmt_f(self.returns.total_return)}\n"
        f"  Annual Return: {fmt_f(self.risk.annual_return)}\n"
        f"  Volatility: {fmt_f(self.risk.monthly_volatility)}\n"
        f"  Sharpe Ratio: {fmt_f(self.risk.sharpe_ratio)}\n"
        f"  Calmar Ratio: {fmt_f(self.risk.calmar_ratio)}\n"
        f"  Max Drawdown: {fmt_f(self.drawdowns.max_drawdown)}\n"
        f"  Average Drawdown: {fmt_f(self.drawdowns.average_drawdown)}\n"
        f"  Trades: {self.trades.trade_count}\n"
        f"  Win Rate: {fmt_f(self.trades.win_rate)}\n"
        f"  Profit Factor: {fmt_f(self.trades.profit_factor)}\n"
        f"  Expectancy: {fmt_f(self.trades.expectancy)}\n"
        f"  Average Holding Period: {fmt_f(self.trades.average_holding_period)}"
    )

ReturnMetrics

Bases: NamedTuple

The resulting returns from the backtest. Holds the actual returned property and value from a strategy over time.

Attributes:

Name	Type	Description
`total_return`	`percent \| None`	The percent returned from the backtest at the end of execution.
`monthly_returns`	`tuple[tuple[time_unix_ms, percent], ...] \| None`	A sequence of the total returns per month of the strategy.
`equity_curve`	`tuple[tuple[time_unix_ms, USD], ...]`	The account value over time (total value of cash + units).

RiskMetrics

Bases: NamedTuple

The risk factor metrics from a backtest. Determines how reliable a strategy was over the backtest.

Attributes:

Name	Type	Description
`annual_return`	`percent \| None`	The CAGR (annualized compound return) for the backtest.
`monthly_volatility`	`percent \| None`	Measure of how intensely returns move per month.
`sharpe_ratio`	`float \| None`	Measure of how much excess return received per unit of risk taken (annaul).
`calmar_ratio`	`float \| None`	Measure of much return an investment has generated relative to its worst possible loss.

TradeMetrics

Bases: NamedTuple

The basic trading metrics for a backtest. Holds the actual number of trades made, wins, losses, and profits.

Attrubtes

trade_count: The total number of trades the strategy made during the backtest. win_rate: The percent of trades that the strategy was profitable. profit_factor: The gross profit from winning trades to gross losses from losing trades. expectancy: The expected profit per trade with the strategy. average_win: The average percent made per win. average_loss: The average percent lost per loss. average_holding_period: The average amount of time that the strategy holds a trade for.