pybroker.eval module

Contains implementation of evaluation metrics.

class BootConfIntervals(low_2p5: float, high_2p5: float, low_5: float, high_5: float, low_10: float, high_10: float)

Bases: NamedTuple

Holds confidence intervals of bootstrap tests.

low_2p5

Lower bound of 97.5% confidence interval.

Type:

float

high_2p5

Upper bound of 97.5% confidence interval.

Type:

float

low_5

Lower bound of 95% confidence interval.

Type:

float

high_5

Upper bound of 95% confidence interval.

Type:

float

low_10

Lower bound of 90% confidence interval.

Type:

float

high_10

Upper bound of 90% confidence interval.

Type:

float

class BootstrapResult(conf_intervals: DataFrame, drawdown_conf: DataFrame, profit_factor: BootConfIntervals, sharpe: BootConfIntervals, drawdown: DrawdownMetrics)

Bases: NamedTuple

Contains results of bootstrap tests.

conf_intervals

pandas.DataFrame containing confidence intervals for log_profit_factor() and sharpe_ratio().

Type:

pandas.core.frame.DataFrame

drawdown_conf

pandas.DataFrame containing upper bounds of confidence intervals for maximum drawdown.

Type:

pandas.core.frame.DataFrame

profit_factor

Contains profit factor confidence intervals.

Type:

pybroker.eval.BootConfIntervals

sharpe

Contains Sharpe Ratio confidence intervals.

Type:

pybroker.eval.BootConfIntervals

drawdown

Contains drawdown confidence intervals.

Type:

pybroker.eval.DrawdownMetrics

class ConfInterval(name: str, conf: str, lower: float, upper: float)

Bases: NamedTuple

Confidence interval upper and low bounds.

name

Parameter name.

Type:

str

conf

Confidence interval percentage represented as a str.

Type:

str

lower

Lower bound.

Type:

float

upper

Upper bound.

Type:

float

class DrawdownConfs(q_001: float, q_01: float, q_05: float, q_10: float)

Bases: NamedTuple

Contains upper bounds of confidence intervals for maximum drawdown.

q_001

99.9% confidence upper bound.

Type:

float

q_01

99% confidence upper bound.

Type:

float

q_05

95% confidence upper bound.

Type:

float

q_10

90% confidence upper bound.

Type:

float

class DrawdownMetrics(confs: DrawdownConfs, pct_confs: DrawdownConfs)

Bases: NamedTuple

Contains drawdown metrics.

confs

Upper bounds of confidence intervals for maximum drawdown, measured in cash.

Type:

pybroker.eval.DrawdownConfs

pct_confs

Upper bounds of confidence intervals for maximum drawdown, measured in percentage.

Type:

pybroker.eval.DrawdownConfs

class EvalMetrics(trade_count: int = 0, initial_market_value: float = 0, end_market_value: float = 0, total_pnl: float = 0, unrealized_pnl: float = 0, total_return_pct: float = 0, annual_return_pct: float | None = None, total_profit: float = 0, total_loss: float = 0, total_fees: float = 0, max_drawdown: float = 0, max_drawdown_pct: float = 0, win_rate: float = 0, loss_rate: float = 0, winning_trades: int = 0, losing_trades: int = 0, avg_pnl: float = 0, avg_return_pct: float = 0, avg_trade_bars: float = 0, avg_profit: float = 0, avg_profit_pct: float = 0, avg_winning_trade_bars: float = 0, avg_loss: float = 0, avg_loss_pct: float = 0, avg_losing_trade_bars: float = 0, largest_win: float = 0, largest_win_pct: float = 0, largest_win_bars: int = 0, largest_loss: float = 0, largest_loss_pct: float = 0, largest_loss_bars: int = 0, max_wins: int = 0, max_losses: int = 0, sharpe: float = 0, sortino: float = 0, calmar: float | None = None, profit_factor: float = 0, ulcer_index: float = 0, upi: float = 0, equity_r2: float = 0, std_error: float = 0, annual_std_error: float | None = None, annual_volatility_pct: float | None = None)

Bases: object

Contains metrics for evaluating a pybroker.strategy.Strategy.

trade_count

Number of trades that were filled.

Type:

int

initial_market_value

Initial market value of the pybroker.portfolio.Portfolio.

Type:

float

end_market_value

Ending market value of the pybroker.portfolio.Portfolio.

Type:

float

total_pnl

Total realized profit and loss (PnL).

Type:

float

unrealized_pnl

Total unrealized profit and loss (PnL).

Type:

float

total_return_pct

Total realized return measured in percentage.

Type:

float

annual_return_pct

Annualized total realized return measured in percentage.

Type:

float | None

total_profit

Total realized profit.

Type:

float

total_loss

Total realized loss.

Type:

float

total_fees

Total brokerage fees. See pybroker.config.StrategyConfig.fee_mode for more info.

Type:

float

max_drawdown

Maximum drawdown, measured in cash.

Type:

float

max_drawdown_pct

Maximum drawdown, measured in percentage.

Type:

float

win_rate

Win rate of trades.

Type:

float

loss_rate

Loss rate of trades.

Type:

float

winning_trades

Number of winning trades.

Type:

int

losing_trades

Number of losing trades.

Type:

int

avg_pnl

Average profit and loss (PnL) per trade, measured in cash.

Type:

float

avg_return_pct

Average return per trade, measured in percentage.

Type:

float

avg_trade_bars

Average number of bars per trade.

Type:

float

avg_profit

Average profit per trade, measured in cash.

Type:

float

avg_profit_pct

Average profit per trade, measured in percentage.

Type:

float

avg_winning_trade_bars

Average number of bars per winning trade.

Type:

float

avg_loss

Average loss per trade, measured in cash.

Type:

float

avg_loss_pct

Average loss per trade, measured in percentage.

Type:

float

avg_losing_trade_bars

Average number of bars per losing trade.

Type:

float

largest_win

Largest profit of a trade, measured in cash.

Type:

float

largest_win_pct

Largest profit of a trade, measured in percentage

Type:

float

largest_win_bars

Number of bars in the largest winning trade.

Type:

int

largest_loss

Largest loss of a trade, measured in cash.

Type:

float

largest_loss_pct

Largest loss of a trade, measured in percentage.

Type:

float

largest_loss_bars

Number of bars in the largest losing trade.

Type:

int

max_wins

Maximum number of consecutive winning trades.

Type:

int

max_losses

Maximum number of consecutive losing trades.

Type:

int

sharpe

Sharpe Ratio, computed per bar.

Type:

float

sortino

Sortino Ratio, computed per bar.

Type:

float

calmar

Calmar Ratio, computed per bar.

Type:

float | None

profit_factor

Ratio of gross profit to gross loss, computed per bar.

Type:

float

ulcer_index

Ulcer Index, computed per bar.

Type:

float

upi

Ulcer Performance Index, computed per bar.

Type:

float

equity_r2

R^2 of the equity curve, computed per bar on market values of portfolio.

Type:

float

std_error

Standard error, computed per bar on market values of portfolio.

Type:

float

annual_std_error

Annualized standard error, computed per bar on market values of portfolio.

Type:

float | None

annual_volatility_pct

Annualized volatility percentage, computed per bar on market values of portfolio.

Type:

float | None

class EvalResult(metrics: EvalMetrics, bootstrap: BootstrapResult | None)

Bases: NamedTuple

Contains evaluation result.

metrics

Evaluation metrics.

Type:

pybroker.eval.EvalMetrics

bootstrap

Randomized bootstrap metrics.

Type:

pybroker.eval.BootstrapResult | None

class EvaluateMixin

Bases: object

Mixin for computing evaluation metrics.

evaluate(portfolio_df: DataFrame, trades_df: DataFrame, calc_bootstrap: bool, bootstrap_sample_size: int, bootstrap_samples: int, bars_per_year: int | None) → EvalResult

Computes evaluation metrics.

Parameters:

• portfolio_df – pandas.DataFrame of portfolio market values per bar.

• trades_df – pandas.DataFrame of trades.

• calc_bootstrap – True to calculate randomized bootstrap metrics.

• bootstrap_sample_size – Size of each random bootstrap sample.

• bootstrap_samples – Number of random bootstrap samples to use.

• bars_per_year – Number of observations per years that will be used to annualize evaluation metrics. For example, a value of 252 would be used to annualize the Sharpe Ratio for daily returns.

Returns:

EvalResult containing evaluation metrics.

annual_total_return_percent(initial_value: float, pnl: float, bars_per_year: int, total_bars: int) → float

Computes annualized total return as percentage.

Parameters:

• initial_value – Initial value.

• pnl – Total profit and loss (PnL).

• bars_per_year – Number of bars per annum.

• total_bars – Total number of bars of the return.

avg_profit_loss(pnls: ndarray[Any, dtype[float64]]) → tuple[float, float]

Computes the average profit and average loss per trade.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[float, float] of average profit and average loss.

bca_boot_conf(x: ndarray[Any, dtype[float64]], n: int, n_boot: int, fn: Callable[[ndarray[Any, dtype[float64]]], float]) → BootConfIntervals

Computes confidence intervals for a user-defined parameter using the bias corrected and accelerated (BCa) bootstrap method.

Parameters:

• x – numpy.ndarray containing the data for the randomized bootstrap sampling.

• n – Number of elements in each random bootstrap sample.

• n_boot – Number of random bootstrap samples to use.

• fn – Callable for computing the parameter used for the confidence intervals.

Returns:

BootConfIntervals containing the computed confidence intervals.

calmar_ratio(changes: ndarray[Any, dtype[float64]], bars_per_year: int) → float

Computes the Calmar Ratio.

Parameters:

• changes – Array of differences between each bar and the previous bar.

• bars_per_year – Number of bars per annum.

conf_profit_factor(x: ndarray[Any, dtype[float64]], n: int, n_boot: int) → BootConfIntervals

Computes confidence intervals for profit_factor().

conf_sharpe_ratio(x: ndarray[Any, dtype[float64]], n: int, n_boot: int, obs: int | None = None) → BootConfIntervals

Computes confidence intervals for sharpe_ratio().

iqr(values: ndarray[Any, dtype[float64]]) → float

Computes the interquartile range (IQR) of values.

largest_win_loss(pnls: ndarray[Any, dtype[float64]]) → tuple[float, float]

Computes the largest profit and largest loss of all trades.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[float, float] of largest profit and largest loss.

log_profit_factor(changes: ndarray[Any, dtype[float64]]) → floating

Computes the log transformed profit factor, which is the ratio of gross profit to gross loss.

Parameters:

changes – Array of differences between each bar and the previous bar.

max_drawdown_percent(returns: ndarray[Any, dtype[float64]]) → float

Computes maximum drawdown, measured in percentage loss.

Parameters:

returns – Array of returns centered at 0.

max_wins_losses(pnls: ndarray[Any, dtype[float64]]) → tuple[int, int]

Computes the max consecutive wins and max consecutive losses.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[int, int] of max consecutive wins and max consecutive losses.

r_squared(values: ndarray[Any, dtype[float64]]) → float

Computes R-squared of values.

relative_entropy(values: ndarray[Any, dtype[float64]]) → float

Computes the relative entropy.

sharpe_ratio(changes: ndarray[Any, dtype[float64]], obs: int | None = None, downside_only: bool = False) → floating

Computes the Sharpe Ratio.

Parameters:

• changes – Array of differences between each bar and the previous bar.

• obs – Number of observations used to annualize the Sharpe Ratio. For example, a value of 252 would be used to annualize daily returns.

sortino_ratio(changes: ndarray[Any, dtype[float64]], obs: int | None = None) → float

Computes the Sortino Ratio.

Parameters:

• changes – Array of differences between each bar and the previous bar.

• obs – Number of observations used to annualize the Sortino Ratio. For example, a value of 252 would be used to annualize daily returns.

total_profit_loss(pnls: ndarray[Any, dtype[float64]]) → tuple[float, float]

Computes total profit and loss.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[float, float] of total profit and total loss.

total_return_percent(initial_value: float, pnl: float) → float

Computes total return as percentage.

Parameters:

• initial_value – Initial value.

• pnl – Total profit and loss (PnL).

win_loss_rate(pnls: ndarray[Any, dtype[float64]]) → tuple[float, float]

Computes the win rate and loss rate as percentages.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[float, float] of win rate and loss rate.

winning_losing_trades(pnls: ndarray[Any, dtype[float64]]) → tuple[int, int]

Returns the number of winning and losing trades.

Parameters:

pnls – Array of profits and losses (PnLs) per trade.

Returns:

tuple[int, int] containing numbers of winning and losing trades.