pybroker.eval 模块
包含评估指标的实现。
- class BootConfIntervals(low_2p5: float, high_2p5: float, low_5: float, high_5: float, low_10: float, high_10: float)[源代码]
基类：
NamedTuple保存自助法检验的置信区间。
- class BootstrapResult(conf_intervals: DataFrame, drawdown_conf: DataFrame, profit_factor: BootConfIntervals, sharpe: BootConfIntervals, drawdown: DrawdownMetrics)[源代码]
基类：
NamedTuple包含自助法检验的结果。
- conf_intervals
包含
log_profit_factor()和sharpe_ratio()置信区间的pandas.DataFrame。- 类型:
- drawdown_conf
包含最大回撤置信区间上界的
pandas.DataFrame。- 类型:
- profit_factor
包含盈利因子（profit factor）的置信区间。
- sharpe
包含夏普比率的置信区间。
- drawdown
包含回撤置信区间。
- class ConfInterval(name: str, conf: str, lower: float, upper: float)[源代码]
基类：
NamedTuple置信区间的上界和下界。
- class DrawdownConfs(q_001: float, q_01: float, q_05: float, q_10: float)[源代码]
基类：
NamedTuple包含最大回撤置信区间的上界。
- class DrawdownMetrics(confs: DrawdownConfs, pct_confs: DrawdownConfs)[源代码]
基类：
NamedTuple包含回撤指标。
- confs
以现金衡量的最大回撤置信区间上界。
- pct_confs
以百分比衡量的最大回撤置信区间上界。
- 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, max_drawdown_date: datetime | None = None, 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)[源代码]
基类：
object包含用于评估
pybroker.strategy.Strategy的指标。- initial_market_value
pybroker.portfolio.Portfolio的初始市值。- 类型:
- end_market_value
pybroker.portfolio.Portfolio的期末市值。- 类型:
- total_fees
经纪商手续费总额。更多信息参见
pybroker.config.StrategyConfig.fee_mode。- 类型:
- max_drawdown_date
最大回撤发生的日期。
- 类型:
datetime.datetime | None
- sharpe
按每根 K 线计算的 夏普比率（Sharpe Ratio）。
- 类型:
- sortino
按每根 K 线计算的 索提诺比率（Sortino Ratio）。当没有亏损 K 线且平均收益率为正时为
inf。- 类型:
- calmar
卡玛比率（Calmar Ratio）：权益曲线的复合年增长率（CAGR）除以其最大回撤百分比。由于该比率需要年化，未设置
pybroker.config.StrategyConfig.bars_per_year时为None；没有回撤且权益曲线上涨时为inf。- 类型:
float | None
- ulcer_index
溃疡指数（Ulcer Index）：权益曲线相对其滚动最高点的百分比回撤的均方根值。
- 类型:
- upi
溃疡表现指数（Ulcer Performance Index）：收益除以溃疡指数（Ulcer Index）。设置
pybroker.config.StrategyConfig.bars_per_year时，收益按复合年增长率（CAGR）计算；否则为每根 K 线的平均收益率。对于真正无回撤的收益为inf。- 类型:
- annual_std_error
std_error乘以pybroker.config.StrategyConfig.bars_per_year的平方根。- 类型:
float | None
- class EvalResult(metrics: EvalMetrics, bootstrap: BootstrapResult | None)[源代码]
基类：
NamedTuple包含评估结果。
- metrics
评估指标。
- bootstrap
随机自助法指标。
- 类型:
- class EvaluateMixin[源代码]
基类：
object用于计算评估指标的 Mixin。
- evaluate(portfolio_df: DataFrame, trades_df: DataFrame, calc_bootstrap: bool, bootstrap_samples: int, bars_per_year: int | None, seed: int | None = 42) EvalResult[源代码]
计算评估指标。
- 参数:
portfolio_df -- 每根 K 线投资组合市值的
pandas.DataFrame。trades_df -- 交易记录的
pandas.DataFrame。calc_bootstrap -- 为
True时计算随机自助法指标。bootstrap_samples -- 使用的随机自助法样本数量。
bars_per_year -- 用于将评估指标年化的每年观测数量。例如，日线收益率使用
252来年化夏普比率。seed -- 用于结果可复现的随机种子。默认为 42。
- 返回:
包含评估指标的
EvalResult。
- class TradeStats(trade_count: int, win_rate: float, loss_rate: float, winning_trades: int, losing_trades: int, total_profit: float, total_loss: float, avg_profit: float, avg_loss: float, avg_profit_pct: float, avg_loss_pct: float, largest_win: float, largest_loss: float, largest_win_pct: float, largest_loss_pct: float, largest_win_bars: int, largest_loss_bars: int, max_wins: int, max_losses: int, avg_pnl: float, avg_return_pct: float, avg_trade_bars: float, avg_winning_trade_bars: float, avg_losing_trade_bars: float, total_pnl: float)[源代码]
基类：
NamedTuple单次遍历中计算出的交易统计信息。
- annual_total_return_percent(initial_value: float, pnl: float, bars_per_year: int, total_bars: int) float[源代码]
计算以百分比表示的年化总收益率。
- 参数:
initial_value -- 初始值。
pnl -- 总盈亏（PnL）。
bars_per_year -- 每年的 K 线数量。
total_bars -- 该收益率对应的 K 线总数。
- avg_profit_loss(pnls: NDArray[float64]) tuple[float, float][源代码]
计算每笔交易的平均盈利和平均亏损。
- 参数:
pnls -- 每笔交易盈亏（PnL）组成的数组。
- 返回:
平均盈利和平均亏损组成的
tuple[float, float]。
- bca_boot_conf(x: NDArray[float64], n_boot: int, fn: Callable[[NDArray[float64]], float]) BootConfIntervals[源代码]
使用 偏差校正加速（BCa）自助法 计算用户定义参数的置信区间。
- 参数:
x -- 用于随机自助法抽样的数据
numpy.ndarray。n_boot -- 使用的随机自助法样本数量。
fn -- 用于计算置信区间所需参数的
Callable。
- 返回:
包含计算出的置信区间的
BootConfIntervals。
- bootstrap_eval_all(changes: NDArray[float64], returns: NDArray[float64], n_boot: int, bars_per_year: int) tuple[BootConfIntervals, BootConfIntervals, DrawdownMetrics][源代码]
在一次共享的重采样过程中计算所有自助法指标。
- calmar_ratio(returns: NDArray[float64], bars_per_year: int) float[源代码]
计算卡玛比率（Calmar Ratio），即
returns复利累积序列的复合年增长率（CAGR）除以该序列的最大回撤百分比。- 参数:
returns -- 以 0 为中心的收益率数组。
bars_per_year -- 每年的 K 线数量。
- conf_profit_factor(x: NDArray[float64], n_boot: int) BootConfIntervals[源代码]
计算
profit_factor的置信区间。
- conf_sharpe_ratio(x: NDArray[float64], n_boot: int, obs: int | None = None) BootConfIntervals[源代码]
计算
sharpe_ratio()的置信区间。
- downside_deviation(returns: NDArray[float64]) float[源代码]
计算下行标准差，即 索提诺比率（Sortino Ratio） 的分母。
负收益率相对于零取平方，并对 所有 观测值求平均，而不仅仅是负收益率的观测值。
- 参数:
returns -- 以 0 为中心的收益率数组。
- largest_win_loss(pnls: NDArray[float64]) tuple[float, float][源代码]
计算所有交易中的最大盈利和最大亏损。
- 参数:
pnls -- 每笔交易盈亏（PnL）组成的数组。
- 返回:
最大盈利和最大亏损组成的
tuple[float, float]。
- log_profit_factor(changes: NDArray[float64]) float[源代码]
计算对数变换后的盈利因子，即总盈利与总亏损之比。
- 参数:
changes -- 每根 K 线与前一根 K 线之差组成的数组。
- max_drawdown_percent(returns: NDArray[float64]) tuple[float, int | None][源代码]
计算以百分比亏损衡量的最大回撤。
- 参数:
returns -- 以 0 为中心的收益率数组。
- 返回:
以百分比亏损衡量的最大回撤。
最大回撤发生处的索引。
- max_wins_losses(pnls: NDArray[float64]) tuple[int, int][源代码]
计算最大连续盈利次数和最大连续亏损次数。
- 参数:
pnls -- 每笔交易盈亏（PnL）组成的数组。
- 返回:
最大连续盈利次数和最大连续亏损次数组成的
tuple[int, int]。
- sharpe_ratio(returns: NDArray[float64], obs: int | None = None) float[源代码]
计算 夏普比率（Sharpe Ratio），使用
returns的总体标准差。- 参数:
returns -- 以 0 为中心的收益率数组。
obs -- 用于年化夏普比率的观测数量。例如，日线收益率使用
252。
- sortino_ratio(returns: NDArray[float64], obs: int | None = None) float[源代码]
-
当没有下行波动可作除数时，该比率是无界的，因此平均收益率为正时返回
inf—— 这确实是最佳得分，Optuna 也能接受 —— 而平均收益率非正时返回0。NaN则保留给完全无法计算的情况，因为 NaN 得分会将一次 Optuna 试验标记为 失败，从而丢弃该次运行，而不是对其排名。- 参数:
returns -- 以 0 为中心的收益率数组。
obs -- 用于年化索提诺比率的观测数量。例如，日线收益率使用
252。
- total_profit_loss(pnls: NDArray[float64]) tuple[float, float][源代码]
计算总盈亏。
- 参数:
pnls -- 每笔交易盈亏（PnL）组成的数组。
- 返回:
总盈利和总亏损组成的
tuple[float, float]。
- total_return_percent(initial_value: float, pnl: float) float[源代码]
计算以百分比表示的总收益率。
- 参数:
initial_value -- 初始值。
pnl -- 总盈亏（PnL）。