---

name: polars-backtest description: Help users backtest trading strategies with polars-backtest library. Use when user asks about backtesting, portfolio simulation, trading strategy analysis, or working with polars-backtest.

Polars Backtest Usage Skill

Help users use polars-backtest to backtest their trading strategies efficiently.

Installation

Copypip install polars-backtest
# or
uv add polars-backtest

Data Format

Long format: one row per (date, symbol) pair.

Copyimport polars as pl
import polars_backtest as pl_bt

df = pl.DataFrame({
    "date": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
    "symbol": ["2330", "2317", "2330", "2317"],
    "close": [100.0, 50.0, 102.0, 51.0],
    "weight": [0.6, 0.4, 0.6, 0.4],
})

Basic Usage

Copy# DataFrame namespace
result = df.bt.backtest(trade_at_price="close", position="weight")

# Function API
result = pl_bt.backtest(df, trade_at_price="close", position="weight")

# With report (includes trades, stats)
report = df.bt.backtest_with_report(position="weight", resample="M")

Complete Parameter Reference

Column Mapping Parameters

Rebalancing Parameters

Cost Parameters

Risk Management Parameters

Calculation Mode Parameters

Benchmark Parameters (backtest_with_report only)

Liquidity Metrics Parameters (backtest_with_report only)

BacktestReport Object

Copyreport = df.bt.backtest_with_report(position="weight")

# Properties
report.creturn      # DataFrame with date, creturn columns
report.trades       # DataFrame with trade records (see Trades DataFrame section)
report.stats        # Statistics DataFrame (shortcut for get_stats())
report.fee_ratio    # Fee ratio used
report.tax_ratio    # Tax ratio used
report.stop_loss    # Stop loss threshold (None if disabled)
report.take_profit  # Take profit threshold (None if disabled)
report.trail_stop   # Trail stop threshold (None if disabled)
report.trade_at     # Trade timing (e.g., 'close')
report.resample     # Resample frequency
report.benchmark    # Benchmark DataFrame (can be set after creation)

# Set benchmark after creation
report.benchmark = benchmark_df

Trades DataFrame

The report.trades property returns a DataFrame with detailed trade records:

Pending Trades

Pending trades represent signals that exist but haven't been executed yet (T+1 execution model):

• Pending entry: entry_date = null, entry_sig_date = latest signal date
  • Stock has a buy signal but trade hasn't executed yet
• Pending exit: exit_date = null, exit_sig_date = latest signal date
  • Stock has a sell signal but trade hasn't closed yet

Copy# Get pending entry trades
pending_entries = report.trades.filter(pl.col("entry_date").is_null())

# Get pending exit trades (open positions with exit signal)
pending_exits = report.trades.filter(
    pl.col("entry_date").is_not_null() &
    pl.col("exit_date").is_null() &
    pl.col("exit_sig_date").is_not_null()
)

# Get open positions (no exit signal yet)
open_positions = report.trades.filter(
    pl.col("entry_date").is_not_null() &
    pl.col("exit_date").is_null() &
    pl.col("exit_sig_date").is_null()
)

BacktestReport Methods

get_stats(riskfree_rate=0.02)

Get basic statistics as single-row DataFrame.

Copyreport.get_stats()  # or report.stats

Columns: start, end, rf, total_return, cagr, max_drawdown, avg_drawdown, daily_mean, daily_vol, daily_sharpe, daily_sortino, best_day, worst_day, calmar, win_ratio

get_monthly_stats(riskfree_rate=0.02)

Get monthly statistics.

Copyreport.get_monthly_stats()

Columns: monthly_mean, monthly_vol, monthly_sharpe, monthly_sortino, best_month, worst_month

get_return_table()

Get monthly return table pivoted by year x month.

Copyreport.get_return_table()

Returns DataFrame with year as rows and months (1-12) as columns.

get_metrics(sections=None, riskfree_rate=0.02)

Get structured metrics as single-row DataFrame.

Copymetrics = report.get_metrics()  # All sections
metrics = report.get_metrics(sections=["profitability", "risk"])

current_trades()

Get active trades (positions without exit or exiting on last date).

Copyreport.current_trades()

actions()

Get trade actions for current positions with weights. Finlab-compatible logic.

Copyreport.actions()
# Returns DataFrame with columns: symbol, action, weight, next_weight, weight_date, next_weight_date

Output Columns

Action Types Summary

Weight Properties

• sum(weight) ≤ 1.0 — 當前投資組合的總權重
• sum(next_weight) ≤ 1.0 — 下期目標投資組合的總權重
• hold + enter 的權重不會超過 1，因為：
  • weight 只計算當前持有的股票（hold + exit）
  • next_weight 是下期目標權重（hold + enter，已正規化）

Usage Example

Copyreport = df.bt.backtest_with_report(position="weight", resample="M")

# Get actions with weights and dates
actions = report.actions()
print(actions)
# shape: (115, 6)
# ┌────────┬────────┬──────────┬─────────────┬─────────────┬──────────────────┐
# │ symbol ┆ action ┆ weight   ┆ weight_date ┆ next_weight ┆ next_weight_date │
# │ str    ┆ str    ┆ f64      ┆ date        ┆ f64         ┆ date             │
# ╞════════╪════════╪══════════╪═════════════╪═════════════╪══════════════════╡
# │ 2330   ┆ hold   ┆ 0.023809 ┆ 2026-01-15  ┆ 0.017543    ┆ 2026-02-15       │
# │ 2317   ┆ exit   ┆ 0.023809 ┆ 2026-01-15  ┆ 0.0         ┆ null             │
# │ 2454   ┆ enter  ┆ 0.0      ┆ null        ┆ 0.017543    ┆ 2026-02-15       │
# └────────┴────────┴──────────┴─────────────┴─────────────┴──────────────────┘

# Filter by action type
entering = actions.filter(pl.col("action") == "enter")
exiting = actions.filter(pl.col("action") == "exit")
holding = actions.filter(pl.col("action") == "hold")

# Verify weight sums
print(f"Current portfolio weight: {actions['weight'].sum():.4f}")      # ≤ 1.0
print(f"Next portfolio weight: {actions['next_weight'].sum():.4f}")    # ≤ 1.0

Note: Closed trades (both entry_date and exit_date set) are excluded from actions.

weights()

Get current position weights (normalized). Finlab-compatible.

Copyreport.weights()
# Returns DataFrame with columns: symbol, weight, date

Returns weights for currently held positions only (stocks with entry_date set, exit_date null).

next_weights()

Get next period target weights (normalized). Finlab-compatible.

Copyreport.next_weights()
# Returns DataFrame with columns: symbol, weight, date

Returns target weights for the next rebalancing period. Includes:

• Hold stocks: continuing positions
• Enter stocks: pending entry positions

Excludes stocks with pending exit signals.

is_stop_triggered()

Check if any trade was triggered by stop loss or take profit.

Copyif report.is_stop_triggered():
    print("Stop was triggered")

daily_creturn()

Get daily resampled cumulative return DataFrame.

Copyreport.daily_creturn()

get_metrics Sections

Note: alpha, beta, m12WinRate require benchmark to be set.

Statistics Expressions

Use these expressions for custom calculations:

Copyfrom polars_backtest import daily_returns, cumulative_returns, sharpe_ratio, max_drawdown

df.with_columns(
    ret=daily_returns("close"),
    creturn=cumulative_returns("ret"),
)

df.select(
    sharpe=sharpe_ratio("ret"),
    mdd=max_drawdown("creturn"),
)

Usage Examples

Momentum Strategy with Monthly Rebalancing

Copydf = df.with_columns(
    pl.when(pl.col("close") >= pl.col("close").rolling_max(60).over("symbol"))
    .then(1.0)
    .otherwise(0.0)
    .alias("weight")
)
report = df.bt.backtest_with_report(position="weight", resample="M")

With Risk Management

Copyreport = df.bt.backtest_with_report(
    position="weight",
    stop_loss=-0.1,        # -10% stop loss
    take_profit=0.2,       # +20% take profit
    trail_stop=0.05,       # 5% trailing stop
    touched_exit=True,     # Use intraday OHLC for detection
)

With Benchmark Comparison

Copy# Using a symbol in your data as benchmark
report = df.bt.backtest_with_report(
    position="weight",
    benchmark="0050",      # ETF ticker
)

# Or set after creation
report.benchmark = benchmark_df

# Get metrics with alpha, beta, m12WinRate
metrics = report.get_metrics(sections=["profitability", "winrate"])

With Factor Column (Adjusted Prices)

Copy# When using adjusted prices, factor converts back to raw price
# raw_price = adj_close / factor
df = df.with_columns(
    (pl.col("close_raw") / pl.col("close_adj")).alias("factor")
)
report = df.bt.backtest_with_report(
    trade_at_price="close_adj",
    factor="factor",
)

With Liquidity Metrics

Copydf = df.with_columns([
    pl.col("limit_up_price").alias("limit_up"),
    pl.col("limit_down_price").alias("limit_down"),
    (pl.col("close") * pl.col("volume")).alias("trading_value"),
])
report = df.bt.backtest_with_report(position="weight")
metrics = report.get_metrics(sections=["liquidity"])
# Returns: buyHigh, sellLow, capacity

Using Polars Expressions

Copy# Pass expressions directly instead of column names
result = df.bt.backtest(
    trade_at_price=pl.col("adj_close"),
    position=pl.col("signal").cast(pl.Float64),
    resample="M",
)

Delayed Rebalancing

Copy# Rebalance monthly, but execute 2 days after signal
report = df.bt.backtest_with_report(
    position="weight",
    resample="M",
    resample_offset="2d",
)

Analyzing Current Positions

Copyreport = df.bt.backtest_with_report(position="weight")

# Get current active trades
current = report.current_trades()

# Get recommended actions
actions = report.actions()  # enter/exit/hold per stock

# Get current and next weights (Finlab compatible)
weights = report.weights()        # Currently held positions (sum ≤ 1)
next_wts = report.next_weights()  # Target portfolio for next period (sum ≤ 1)

# Note: hold + enter positions are in next_weights
# This avoids double-counting weights when comparing current vs next portfolio

Resample Options

Tips

1. Weight normalization: Weights are automatically normalized to sum to 1.0 per date
2. T+1 execution: Trades execute at next day's price (realistic simulation)
3. Boolean signals: Pass boolean column as position, library converts True to equal weights
4. Null handling: Null values in position column are filled with 0.0
5. resample=None: Only rebalance when position changes (reduces turnover)
6. Position limit: Use position_limit=0.1 to cap each stock at 10%