回测命名空间 / future.py

bt.drawdown

计算累计收益序列相对历史峰值的回撤。

可执行示例returns: Exprbt

输入 / 输出

输入

pnl

输入项	类型	示例
`pnl`	`Float64`	-1.05

输出

项目	说明
返回类型	`Expr`
输出对象	Expr；执行后得到 Polars DataFrame
输出语义	输出列由算子、alias 或底层实现决定；需要稳定列名时显式使用 alias。
执行方式	用 col(...).runtime() 或 col.with_cols(...).runtime() 创建执行计划后 calc_data。
核心调用	`col("pnl").bt.drawdown()`

打印输入 / 打印输出

下面内容来自本页示例代码真实执行后的 stdout，不是手写占位。

打印输入

print(data)

shape: (20, 1)
┌───────┐
│ pnl   │
│ ---   │
│ f64   │
╞═══════╡
│ -1.05 │
│ -0.7  │
│ -0.35 │
│ 0.0   │
│ 0.35  │
│ …     │
│ -0.7  │
│ -0.35 │
│ 0.0   │
│ 0.35  │
│ 0.7   │
└───────┘

打印输出

print(out)

shape: (20, 1)
┌───────────┐
│ drawdown  │
│ ---       │
│ f64       │
╞═══════════╡
│ 0.0       │
│ 0.0       │
│ 0.0       │
│ 0.0       │
│ 0.0       │
│ …         │
│ -1.666667 │
│ -1.333333 │
│ -1.0      │
│ -0.666667 │
│ -0.333333 │
└───────────┘

调用

Python

col("pnl").bt.drawdown()

无显式参数；输入来自当前表达式、绑定对象或命名空间。

完整代码

本页完整例子会执行真实的 calc_data 或对象调用。

展开可复制完整代码

Python

import datetime as dt
import polars as pl
import qust as qs
from qust import col, pms

data = pl.DataFrame(
    {
        "pnl": [-1.05, -0.7, -0.35, 0.0, 0.35, 0.7, 1.05, -1.05, -0.7, -0.35, 0.0, 0.35, 0.7, 1.05, -1.05, -0.7, -0.35, 0.0, 0.35, 0.7],
    }
)

print("算子:")
print('bt.drawdown')
print("场景:")
print('回测：从信号、持仓和价格生成成交或收益输出。')
print("模式:")
print('可执行示例：构造表达式并运行 calc_data。')
print("输入列:")
print('pnl')
print("调用:")
print('col("pnl").bt.drawdown()')
print("输入数据:")
print(data)
expr = col("pnl").bt.drawdown()
df = col(expr).runtime()
out = df.calc_data(data)
print("输出:")
print(out)

改成业务代码

改哪里	怎么改
列名	把示例 DataFrame 里的列名换成你的真实列名，列顺序保持和用法一致。
参数	只改函数括号里的参数；不要随意改变 `rolling/over/batch/select` 的链式层级。
输出名	需要稳定输出列名时，在表达式尾部加 `.alias("name")`。
调试	先打印输入数据和调用字符串，再执行 `calc_data`；报 schema 错时先检查列数和 dtype。

注意事项

先确认输入列名、顺序、类型和本页一致。
输出列名不符合业务语义时，显式追加 .alias(...)。
窗口和分组类算子要确认 rolling/expanding/over/batch 的链式层级。

来源

项目	位置
源码文件	`future.py`
类/对象	`Bt`