finlab.backtest

回測引擎模組，用於評估策略在歷史資料上的表現。

使用情境

驗證策略邏輯: 確認策略的進出場邏輯是否符合預期，檢視實際交易記錄
評估風險報酬: 計算年化報酬、夏普率、最大回撤等關鍵績效指標
優化策略參數: 結合 finlab.optimize 模組測試不同參數組合（調倉頻率、停損停利等）
對比多個策略: 比較不同策略的績效表現，找出最適合的交易方法

快速範例

from finlab import data
from finlab.backtest import sim

# 載入資料
close = data.get('price:收盤價')

# 策略邏輯：價格突破 20 日均線
ma20 = close.average(20)
position = close > ma20

# 回測（每月調倉，單股上限 10%）
report = sim(
    position,
    resample='M',  # 每月調倉
    position_limit=0.1,  # 單股權重上限 10%
)

# 顯示績效報告
report.display()

詳細教學

參考歷史回測完整指南，了解：

完整回測參數說明（resample, position_limit, stop_loss 等）
績效指標詳細解讀（年化報酬、夏普率、勝率等）
進階回測技巧（多市場、自訂手續費、滑價設定）
回測報告的深度分析方法

API Reference

sim()

finlab.backtest.sim

Backtest simulation orchestrator.

This is the main entry point for running backtests via sim(). Configuration, validation, report building, and notifications are delegated to focused package modules:

finlab.backtest.config -- SimConfig, input validation
finlab.backtest.report -- trades, MAE/MFE, report assembly
finlab.backtest.notify -- Line notification delivery

SimConfig `dataclass`

SimConfig(
    resample=None,
    data_readiness=None,
    planned_rebalance_date=None,
    resample_offset=None,
    trade_at_price='close',
    position_limit=1,
    fee_ratio=None,
    tax_ratio=None,
    name='未命名',
    stop_loss=None,
    take_profit=None,
    trail_stop=None,
    trail_stop_activation=None,
    touched_exit=False,
    retain_cost_when_rebalance=False,
    stop_trading_next_period=True,
    live_performance_start=None,
    end_date=None,
    mae_mfe_window=0,
    mae_mfe_window_step=1,
    market=None,
    upload=None,
    notification_enable=False,
    line_access_token='',
)

Configuration for backtest simulation parameters.

Groups the many sim() parameters into a single config object for cleaner internal passing between phases.

columns_to_numpy

columns_to_numpy(df)

Convert DataFrame columns to numpy array for pandas 3.0+ compatibility.

sim

sim(
    position: DataFrame | Series,
    resample: str | None = None,
    resample_offset: str | None = None,
    trade_at_price: str | DataFrame = 'close',
    position_limit: float = 1,
    fee_ratio: float | None = None,
    tax_ratio: float | None = None,
    name: str = '未命名',
    stop_loss: float | DataFrame | None = None,
    take_profit: float | DataFrame | None = None,
    trail_stop: float | None = None,
    trail_stop_activation: float | None = None,
    touched_exit: bool = False,
    retain_cost_when_rebalance: bool = False,
    stop_trading_next_period: bool = True,
    live_performance_start: str | None = None,
    mae_mfe_window: int = 0,
    mae_mfe_window_step: int = 1,
    market: Market | None = None,
    upload: bool | None = None,
    *,
    end_date: str | date | Timestamp | None = None,
    metrics_only: Literal[True],
    notification_enable: bool = False,
    line_access_token: str = '',
) -> Metrics

sim(
    position: DataFrame | Series,
    resample: str | None = None,
    resample_offset: str | None = None,
    trade_at_price: str | DataFrame = 'close',
    position_limit: float = 1,
    fee_ratio: float | None = None,
    tax_ratio: float | None = None,
    name: str = '未命名',
    stop_loss: float | DataFrame | None = None,
    take_profit: float | DataFrame | None = None,
    trail_stop: float | None = None,
    trail_stop_activation: float | None = None,
    touched_exit: bool = False,
    retain_cost_when_rebalance: bool = False,
    stop_trading_next_period: bool = True,
    live_performance_start: str | None = None,
    mae_mfe_window: int = 0,
    mae_mfe_window_step: int = 1,
    market: Market | None = None,
    upload: bool | None = None,
    *,
    end_date: str | date | Timestamp | None = None,
    metrics_only: Literal[False] = False,
    notification_enable: bool = False,
    line_access_token: str = '',
) -> report.Report

sim(
    position,
    resample=None,
    resample_offset=None,
    trade_at_price='close',
    position_limit=1,
    fee_ratio=None,
    tax_ratio=None,
    name='未命名',
    stop_loss=None,
    take_profit=None,
    trail_stop=None,
    trail_stop_activation=None,
    touched_exit=False,
    retain_cost_when_rebalance=False,
    stop_trading_next_period=True,
    live_performance_start=None,
    mae_mfe_window=0,
    mae_mfe_window_step=1,
    market=None,
    upload=None,
    *,
    end_date=None,
    metrics_only=False,
    notification_enable=False,
    line_access_token='',
)

Simulate the equity given the stock position history.

See the module-level docstring and the parameter docs below for full details.

PARAMETER	DESCRIPTION
`position`	Buy/sell signal history. True = hold, False = flat. Can also be a `LazyWide` — it will be auto-collected at the rebalance dates determined by resample. TYPE: `DataFrame \| Series`
`resample`	Trading period frequency (e.g. 'W', 'M', 'Q'), or a DataFrame/Series, DatetimeIndex or datetime list supplying rebalance dates. FinlabDataFrame period labels are converted to disclosure dates. `None` (default) rebalances the whole portfolio whenever any stock's row differs from the previous row, not on a fixed daily schedule. TYPE: `str \| None` DEFAULT: `None`
`resample_offset`	Pandas offset string (e.g. '7D') added to each rebalance date, for both frequency strings and supplied dates. Applied after disclosure-date conversion and before filtering the backtest period. TYPE: `str \| None` DEFAULT: `None`
`trade_at_price`	Execution price type ('close', 'open', etc.), or a DataFrame of execution prices indexed by date with stock-ID columns. For stocks/ETFs, this changes fills only: daily valuation and close-based stops still use `market.get_price('close', adj=True)`. Custom prices must use the same adjustment scale as those closes. Taiwan's default adjusted close is `etl:adj_close`, including ex-dividend adjustments. To change the price system, supply a custom `market` with consistent execution, valuation and stop prices. TYPE: `str \| DataFrame` DEFAULT: `'close'`
`position_limit`	Maximum single-stock weight (0-1). TYPE: `float` DEFAULT: `1`
`fee_ratio`	Trading fee ratio. TYPE: `float \| None` DEFAULT: `None`
`tax_ratio`	Trading tax ratio. TYPE: `float \| None` DEFAULT: `None`
`name`	Strategy name. TYPE: `str` DEFAULT: `'未命名'`
`stop_loss`	Stop-loss threshold, or a DataFrame of per-date, per-stock thresholds indexed by the date each value becomes available. Each bar uses the latest value dated on or before it (strictly before it with touched_exit=True, since intraday touches happen before that day's value exists). NaN, 0 and dates before the first value mean no stop. With a DataFrame, `report.stop_loss` is None. TYPE: `float \| DataFrame \| None` DEFAULT: `None`
`take_profit`	Take-profit threshold, or a DataFrame with the same rules as `stop_loss`. TYPE: `float \| DataFrame \| None` DEFAULT: `None`
`trail_stop`	Drop from peak return, measured relative to entry cost. For a long position with close-price execution and touched_exit=False, signal an exit when (peak_price - close) / entry_cost > trail_stop. Entry 100, peak 150 and trail_stop=0.2 give a 130 threshold. The signal is executed on the next bar, not at a guaranteed threshold price. With touched_exit=True the peak only includes trade prices up to the previous bar, plus today's open with trade_at_price='open', since intraday touches happen before that day's close exists. TYPE: `float \| None` DEFAULT: `None`
`trail_stop_activation`	Profit threshold before trailing stop activates. TYPE: `float \| None` DEFAULT: `None`
`touched_exit`	Use intraday touched stop-loss/take-profit. TYPE: `bool` DEFAULT: `False`
`retain_cost_when_rebalance`	`False` (default) resets the stop-loss/take-profit cost basis, trailing peak and `trail_stop_activation` state of every holding on each executed rebalance, including stocks that stay held. `True` keeps the original cost basis and peak of stocks held in the same direction; only new or reversed positions reset. TYPE: `bool` DEFAULT: `False`
`stop_trading_next_period`	After a stop-loss/take-profit exit, do not buy the stock back at the next rebalance. It does not affect whether stocks that stay held reset their cost basis. When an execution quote is available, pending non-touched stops execute before a same-day rebalance. `False` allows buying back at that rebalance, with separate exit/entry fees and a fresh cost basis. TYPE: `bool` DEFAULT: `True`
`live_performance_start`	ISO date string marking live trading start. TYPE: `str \| None` DEFAULT: `None`
`mae_mfe_window`	Window size for MAE/MFE calculation. TYPE: `int` DEFAULT: `0`
`mae_mfe_window_step`	Step size for MAE/MFE window. TYPE: `int` DEFAULT: `1`
`market`	Market instance or name string ('TW_STOCK', 'US_STOCK'). TYPE: `Market \| None` DEFAULT: `None`
`upload`	Whether to upload the strategy report to FinLab cloud. Defaults to `None`: upload only in cloud-scheduled runs (the `FINLAB_FORCED_STRATEGY_NAME` environment variable is set). FinLab Studio, local, Jupyter and Colab runs upload only when `upload=True` is passed. TYPE: `bool \| None` DEFAULT: `None`
`end_date`	Last date of the backtest (inclusive; a bare date covers the whole day). Position, prices and the report (creturn, trades, stats) stop there, as if the backtest ran on that day. Positions still open on `end_date` stay open in `report.trades`. `None` (default) keeps the current behavior: the end is inferred from the position's signal spacing. TYPE: `str \| date \| Timestamp \| None` DEFAULT: `None`
`metrics_only`	Return the same `Metrics` type as `Report.metrics` without constructing a Report. Return-series metrics such as CAGR, Sharpe ratio and maximum drawdown remain available. TYPE: `bool` DEFAULT: `False`
`notification_enable`	Discontinued: LINE Notify shut down on 2025-03-31. Leave it False. TYPE: `bool` DEFAULT: `False`
`line_access_token`	Discontinued LINE Notify access token, used only with `notification_enable`. TYPE: `str` DEFAULT: `''`

RETURNS	DESCRIPTION
`Report \| Metrics`	A Report, or a Metrics object when `metrics_only=True`.

再平衡時機與停損基準

resample=None（預設）不是固定每日調倉：position 任何一檔股票和前一列不同時，整本持股依新的一列重新配置，所以只有 position 每天都有變動時，才會每天調倉。

retain_cost_when_rebalance 決定實際執行再平衡的那一天，繼續持有的股票停損停利怎麼算：

False（預設）：所有持股的停損停利基準都重設為當天價格，包括繼續持有的股票；trail_stop 的最高價與 trail_stop_activation 的啟動狀態也重新計算。
True：同方向繼續持有的股票保留原進場成本與最高價，只有新進場或反向的股票重設。

所以 resample=None 搭配預設 False 時，別檔股票進出也會重設一直持有的股票的停損線。以 stop_loss=0.15、position 每天都持有 A 為例（收盤價成交）：

日期	A 收盤價	發生的事	`False`（預設）	`True`
01/03	100	A 進場	停損線 85	停損線 85
01/08	90	B 在 01/05 轉為持有，這天整本再平衡	停損線重設為 90 × 0.85 = 76.5	停損線維持 85
01/11	84		未跌破 76.5	跌破 85，產生停損訊號
01/12	81		未跌破 76.5，繼續持有	訊號日的下一個交易日，以 81 出場

兩種設定下 A 在 report.trades 的報酬都是 -19%：重設的是停損基準，不是交易報酬。設定 resample='M' 等週期時，每個再平衡日也照這個規則。

stop_trading_next_period 只決定停損停利出場後，下一次再平衡是否買回該股票，和繼續持有的股票是否重設基準無關。

touched_exit=False 時，若成交日有成交價，前一交易日已排定的停損停利會先成交，即使當天剛好再平衡或價格已回到門檻內。接著再平衡：True 排除已退出的股票；False 允許依新目標在同日買回，退出與買回各計一次手續費，退出另計稅。買回是新部位，成本與停損停利基準重新計算，即使 retain_cost_when_rebalance=True 也一樣。交易紀錄分成兩筆持有期間；成交前的 tp_enter／sl_enter 表示先退出再買回，weights 是目前部位、next_weights 是再平衡目標。

自訂成交價與持倉估值

股票／ETF 回測的 trade_at_price 可傳入價格名稱（例如 'close'、'open'），或以日期為 index、股票代號為 columns 的自訂成交價 DataFrame。它決定交易的成交價格；逐日持倉估值與一般收盤價停損判斷（touched_exit=False）仍使用 market.get_price('close', adj=True)。

預設台股市場的 'close' 使用 etl:adj_close，已包含除息調整。00948B 等配息 ETF 可直接用預設 sim(position) 回測，無須另外傳入價格來納入除息調整。這是還原價格的報酬口徑，不是逐筆現金股利精確再投入的現金帳本模擬。

自訂成交價須與估值價使用一致的還原尺度；沿用前面的台股 position，可傳入同一份還原收盤價：

adj_close = data.get('etl:adj_close')
report = sim(position, trade_at_price=adj_close, upload=False)

若只把成交價改成 adj_close * 2，買入數量會按兩倍價格計算，持倉卻仍按原尺度估值，淨值就會失真。若需採用自訂價格體系，請透過自訂 Market，同步提供一致的成交、估值及停損價格；使用 touched_exit=True 時，開盤、最高、最低價也須維持同一尺度。

upload 預設值（2.0.24 起）

upload 預設為 None：只有雲端排程執行（設定了 FINLAB_FORCED_STRATEGY_NAME 環境變數）時才會上傳報告。FinLab Studio、本機、Jupyter、Colab 預設不上傳，需要上傳請明確傳入 upload=True，或回測後呼叫 report.upload()。

常用參數組合

月線策略（適合上班族）:

report = sim(
    position,
    resample='M',  # 每月調倉
    position_limit=0.1,  # 單股上限 10%
    upload=True,  # 上傳至雲端（本機預設不上傳，需明確指定）
)

週線策略（適合積極型）:

report = sim(
    position,
    resample='W',  # 每週調倉
    position_limit=0.05,  # 單股上限 5%（分散風險）
    trade_at_price='open',  # 以開盤價交易（更保守）
)

停損停利策略:

# 方法 1: 在 sim() 中設定
report = sim(
    position,
    resample='M',
    stop_loss=0.1,  # 虧損 10% 停損
    take_profit=0.2,  # 獲利 20% 停利
)

# 方法 2: 使用 hold_until() 更靈活
exit_condition = close < ma20  # 跌破均線出場
position_with_exit = position.hold_until(
    exit=exit_condition,
    stop_loss=0.1,  # 虧損 10% 停損
    take_profit=0.2,  # 獲利 20% 停利
)
report = sim(position_with_exit, resample='M')

常見錯誤與解決方法

1. 策略無任何交易記錄

# 問題：進場條件過嚴，position 全為 False
report = sim(position, resample='M')
trades = report.get_trades()
if len(trades) == 0:
    print("⚠️ 警告：策略無任何交易記錄！")
    # 檢查進場次數
    print(f"平均每日進場股票數：{position.sum(axis=1).mean():.1f}")
    print(f"最大進場股票數：{position.sum(axis=1).max()}")

# 解決：放寬條件或檢查資料範圍

2. KeyError: 日期不存在

# 問題：資料日期範圍不匹配
# 解決：使用 truncate_start 對齊起始日期
from finlab import data

data.truncate_start = '2020-01-01'  # 只回測 2020 年後的資料
report = sim(position, resample='M')

3. 忘記設定 resample 導致頻繁調倉

# 錯誤：交易成本過高
report = sim(position)  # ❌ 預設 resample=None：任何一檔變動就整本再平衡

# 正確：設定合理的調倉頻率
report = sim(position, resample='M')  # ✅ 每月調倉

metrics_from_nav()

finlab.backtest.metrics_from_nav

metrics_from_nav(nav)

Measure any engine's daily NAV with FinLab's curve-only Metrics.

Supply costs-adjusted NAV neutralized for deposits/withdrawals. Dates must increase with one observation per day; invalid rows are never dropped or sorted. This computes caller-provided performance, not audited returns. Measurement uses local calendar dates without a timezone, so midnight DST transitions do not invalidate otherwise valid daily observations. No report, holdings, upload or orders are inferred from the curve.

metrics_from_nav() 接受任意框架或自訂帳本的日頻淨值，提供與 sim() 相同口徑的淨值績效，供研究／策略管理工具登錄結果。不需要改寫成 FinLab 回測：

import pandas as pd
from finlab.backtest import metrics_from_nav
from finlab.backtest.metrics import metrics_to_dict

nav = pd.Series([100, 102, 101], index=pd.date_range("2026-01-01", periods=3))
metrics = metrics_from_nav(nav)
print(metrics.annual_return(), metrics.sharpe_ratio(), metrics.max_drawdown())
print(metrics_to_dict(metrics))  # 無法計算的非有限指標轉為 None
print(metrics.provenance)  # 量測方式、期間與有效觀測筆數

輸入為數值 Series 與 DatetimeIndex，至少兩筆、日期遞增且每天最多一筆，值有限且為正。依輸入的當地日曆日期量測，首筆正規化為 1，不排序或刪除錯值。淨值必須已扣成本，並排除入金／出金造成的假報酬；結果不是券商查核收益。回傳獨立 Metrics，僅提供淨值可量測的指標，不產生 Report、交易明細、持倉或委託。

任意框架的程式與必要檔案仍可透過現有 ZIP 部署，第三方相依放在根目錄 requirements.txt；入口程式執行框架後呼叫 metrics_from_nav。雲端的 Python、相依套件與資源限制仍適用：

python -m finlab cloud deploy external_nav --zip strategy.zip --entry-script main.py --time 09:30 --no-contest

量測函式不建立或上傳雲端 Report，也不宣告競賽資格。

常見問題

Q: 回測結果與實盤有落差怎麼辦？

常見原因與解決方法：

回測未考慮滑價：

# 使用開盤價交易（更保守）
report = sim(position, trade_at_price='open', resample='M')

成交量不足：

# 使用 LiquidityAnalysis 檢測流動性
report.run_analysis('LiquidityAnalysis')  # 查看成交量風險

交易價格與實際執行價差： sim() 的訊號永遠是「今天產生、隔天執行」，trade_at_price 決定的是隔天用哪個價格成交：

# trade_at_price='close'（預設）→ 隔日收盤價成交
# 實務上難以精確在收盤價成交，容易產生滑價
report = sim(position, trade_at_price='close')  # ⚠️ 隔日收盤價，實務不易精確成交

# trade_at_price='open' → 隔日開盤價成交（推薦）
# 更貼近實際下單情境：盤後看訊號，隔日開盤掛單
report = sim(position, trade_at_price='open')  # ✅ 隔日開盤價，較貼近實盤

Q: 如何設定自訂手續費？

report = sim(
    position,
    resample='M',
    fee_ratio=0.001425,  # 買賣各 0.1425%（券商手續費）
    tax_ratio=0.003,  # 賣出證交稅 0.3%
)

Q: 如何限制最大持股數量？

# 方法 1: 使用 is_largest() 限制進場股票數
position = (close > ma20).is_largest(30)  # 最多持有 30 檔

# 方法 2: 在 sim() 中限制
report = sim(
    position,
    resample='M',
    position_limit=0.1,  # 單股上限 10%
    # 如果 position 中有 50 檔，實際最多持有 10 檔（100% / 10% = 10）
)

Q: 回測速度太慢怎麼辦？

# 1. 使用更長的調倉週期
report = sim(position, resample='Q')  # 季度調倉（比月線快 3 倍）

# 2. 縮短回測期間
from finlab import data

data.truncate_start = '2018-01-01'  # 只測試近 5 年

# 3. 減少股票數量
position = (close > ma20).is_largest(50)  # 只測試 50 檔

參考資源

歷史回測完整教學 - 深入理解回測引擎
完整策略開發流程 - 從研究到實盤
策略優化指南 - 找出最佳參數
風險管理完整指南 - 停損停利實戰
GitHub 原始碼
範例策略集 - 學習實戰範例