文件
開啟 Studio

資源

版本升級與結果重現

本頁內容13

這頁整理從 2.0.13、2.1.1 或 2.2.26 升到 2.3.2 的影響:先找出哪些變更碰得到你的策略,再用同一份資料比較升級前後的訊號、部位、交易與報表,確認後才切換正式環境。單純鎖住 finlab 版本,無法固定 pandas 的計算方式或之後更正的資料,所以後半頁說明怎麼把環境、資料與設定都保存下來。

先看你從哪一版升級

目前版本升到 2.3.2 要看什麼
2.0.13先看「跨 2.0 與 2.1 的累積修正」及既有影響表,再看 2.3 新變更。包含 fast_mode 移除、排名與財報日期、停損與報表公式、下單及登入寫法
2.1.12.1.0 修正已在原環境;重點是 2.2.x 的 hold_until 預設、技術指標長期缺價、停損、Sortino、Portfolio、缺日期警告與快取修正,再看 2.3 新變更
2.2.26已包含下列 2.2.x 累積修正,先看 2.3.0~2.3.2;沒有碰到其觸發條件時,不把舊版累積修正算成這次的新差異

升級的做法

找出受影響的地方

看下一節的表,逐條確認觸發條件是否符合你的策略。也可以用程式篩選版本 feed,列出區間內所有可能改變結果的項目。

用同一份資料比較升級前後

固定輸入資料與 end_date,在兩個環境各跑一次,依序比較資料、訊號、position、交易、報酬曲線,最後才看 Sharpe 等摘要數字。

保存環境、資料與設定

把套件版本、實際用到的輸入資料、sim() 參數都存下來,之後才能重現同一個結果。作法見讓結果可以重現。

先分清部位、回測公式與報表

同一份策略程式,不一定產生相同的 position。日期對齊、排名、where()、缺值與布林條件修正,會先改變訊號與持倉;即使回測公式沒改,交易與績效也會不同。

若 position、價格、交易日曆、市場、費稅與 sim() 設定都固定,仍可能遇到停損或成交計算修正;這類才是相同部位下的回測差異。Sortino、勝率等報表算法或口徑改變,則可能只改摘要,不改淨值。

2.3.0~2.3.2 新變更

版本觸發條件與影響升級時怎麼處理
2.3.0日頻 FinlabDataFrame 條件套到日期不同的財報資料,where()/mask() 改沿用當時已知的最後一筆條件;週末、休市日或帶時間的申報列不再因缺少同日條件而整列排除。可能改變混合日季頻排名、月換股持倉與績效(PR #669)檢查先遮罩再排名的訊號;不使用未來條件。一般 pandas、同日期及季度條件不變
2.3.0.lazy() 搭配換股日偏移或雙週頻率時,修正漏掉首次換股及週期相位;多來源接到其他日期軸時,rolling/average/shift 回到原來源的歷史視窗(PR #665)固定資料及排程,核對首次換股與持倉;一般未用 .lazy() 的路徑不受這項修正影響
2.3.1pandas 2 下,FinlabDataFrame 的 pct_change() 預設不再先填缺值,與 pandas 3 一致;有缺值的訊號與績效可能改變(PR #691)保留缺值用 df.pct_change();只有策略明定沿用前值時才明寫 df.ffill().pct_change(),並另限可交易股票,見技術指標缺價。一般 pandas DataFrame/Series 不變
2.3.1pandas 3 下,布林 fillna(False) 將只含布林值的欄位轉回 bool,修正 base & ~df.shift(1).fillna(False) 把條件靜默忽略的問題;訊號與歷史績效可能改變(PR #694)檢查取反的 dtype。~ 遇到仍為 object 的 FinlabDataFrame 改直接報錯;可用 shift(1, fill_value=False),或依語意轉為布林。一般 pandas Series 請用 shift(1, fill_value=False)
2.3.2scipy 改在 df.sector.rank()/bucket() 真正需要時才載入,避免 2.3.0 起一般運算在限制記憶體位址空間的環境失敗(PR #700)記憶體修正,計算公式與結果不變
2.3.2下載進度保留 us_price:adj_close 等海外資料的市場前綴(PR #699)只改顯示名稱,不改資料值或計算公式

2.3.0 新增的較快運算模式預設關閉,不需要為升級而開啟。該版 hold_until 等加速,以及 2.3.1 只準備實際持有股票價格的加速,都不改計算結果。2.3.0 移除了 FinlabDataFrame 的 id 屬性,程式若有讀取它需移除依賴。完整新增功能與修正見更新日誌;不能把「加速不改結果」套到上表的修正。

用固定輸入確認缺值與取反

這段不下載資料、不回測,只檢查 2.3.1 的兩個運算:

from finlab import FinlabDataFrame

price = FinlabDataFrame({'A': [100.0, None, 110.0, 121.0]})
print(price.pct_change().round(2)['A'].tolist())
print(price.ffill().pct_change().round(2)['A'].tolist())
flag = FinlabDataFrame({'A': [True, False, True]})
base = FinlabDataFrame({'A': [True, True, True]})
print((base & ~flag.shift(1).fillna(False))['A'].tolist())

2.3.2 的輸出依序是 [nan, nan, nan, 0.1]、[nan, 0.0, 0.1, 0.1]、[True, False, True]。升級前後請保持相同 pandas、numpy 等相依版本;換 pandas 會同時引入另一個比較條件。

跨 2.0 與 2.1 的累積修正

下表補上較舊起點與 2.2.6~2.2.26 的重點;2.2.26 用戶已包含這些變更。只在觸發條件符合時才會有差異。

生效版本觸發條件與影響升級時怎麼處理
2.0.15sim()/sim_batch() 移除 fast_mode,舊參數會報 TypeError初篩改用 metrics_only=True;不保留稀疏日報酬的舊算法
2.0.18、2.0.19同分橫斷面 rank() 改用平均名次;指標 adj=True 改真的使用還原價,過去被忽略;重複呼叫 Sharpe/Sortino 改依當次 riskfree_rate 計算從 2.0.13 升級時核對排名門檻、指標價格與無風險利率;adjust_price=True 原本已用還原價
2.2.16data.indicator() 的原始日線收盤連續缺價,從第 20 根起輸出 NaN;短缺口仍先補值計算,復牌後恢復輸出。EMA、RSI、MACD、ATR 等訊號與持股可能改變(PR #516)保留長期缺價為未知,檢查與 pct_change(240) 的交互影響,見說明與離線對照;週/月指標也依原始日線缺價狀態遮罩
2.2.16、2.2.20開盤新倉當天檢查停損停利、同根觸價優先停損、未設停損的空單不再因股價漲逾一倍而強制出場;收盤觸價移動停利只讀前一天以前的峰值;換股重設成本後依新成本判斷停損(PR #519、PR #523、PR #526、PR #606)即使部位與價格固定,符合條件的交易與淨值仍可能變;交易報酬也修正觸價成交與空單費用。retain_cost_when_rebalance=False 每次再平衡重設續抱股成本與峰值,True 只保留同向續抱股
2.0.19 說明、2.2.14 修正一般多單的 trail_stop 以進場成本為分母:成本 100、峰值 150、門檻 0.2 對應 130,這是說明釐清;hold_until(trail_stop_activation=None) 報錯於 2.2.14 修正分清出場訊號與實際成交;trail_stop_activation 省略、None、0 不額外等待獲利門檻
2.2.16、2.2.20Sortino 改用全期超額報酬的標準下方偏差,期間分析也同步;體檢門檻 1.8 改為 1.6。組合勝率等改用全部交易,非最後 500 筆;win_ratio 只含已出場,winRate 包含持有中交易(PR #515、PR #527、PR #605)指標變化不等於淨值改變;網站上傳仍保留最後 500 筆。舊報告可用已存淨值更新 Sortino,不必重跑策略
2.2.20Portfolio 先分策略計算日報酬再對齊,休市日記 0、補第一天報酬;動態權重下一交易日起生效;資金容量乘上策略權重(PR #603)核對組合淨值、權重生效日及容量;不是單一策略 sim() 一律換公式
2.2.20、2.2.23台股晚交季報依實際公告日;連續 20 根缺價且下季期限已過不再沿用舊季;季頻 industry_rank() 先整張轉揭露日。缺公告日/截止日會警告股票與季度,該季仍不採用(PR #613、PR #642)重新取得財報及日期輸入;警告不會自動補齊離線日期表,不把未知日期當成已公布
2.2.22hold_until 超過持股上限且候選同分時,依原資料欄位順序穩定選取(PR #638)核對同分持股;下方另列 2.2.1 的 exit_mode='state' 預設恢復
2.0.22、2.1.0、2.2.1calc_ic(rank=True) 改真正 Spearman,ic(method=...) 可選 Pearson/Spearman;ic()/calc_metric() 接受非 date 索引名稱;產業排名不再受 Python hash 順序影響重新計算因子結果,保留明確日期/股票索引;不是把所有 ic() 預設改成 Spearman
2.2.19OrderExecutor.create_orders() 不合法參數在撤單前報錯;progress<1 的差額不再進位成過大的整張單,ETF 追價使用正確跳動單位(PR #581、PR #584)核對實單目標與參數;這些不改歷史回測,不需為比較而送單
快取與登入2.0.13 已處理 pickle/Feather 舊副檔取較新者;2.0.17 起 Feather V2 改用 Arrow IPC 讀寫,格式與舊版互通;另有下方 pyarrow、5 分鐘更新及 2.2.20 雜湊修正。舊 FINLAB_API_TOKEN 已棄用不為升級一律刪快取;修改讀回的表先 .copy()(pandas 2 可能共用底層)。本機用 python -m finlab login,Colab 用 finlab.login();伺服器以 python -m finlab token --env 取得環境設定,見登入說明

哪些策略結果會改變

下方互動案例與表格保留較早版本的比較,用來定位累積差異;2.3 的變更請看上表。先拖拖看三個小案例在各版的輸出,再往下查觸發條件。

互動關卡

版本時光機:找出哪一版改了你的策略

任務 1 / 3 點「用 position[timing] 擇時」,往右拖到輸出改變,按「就是這一版改的!」

2.0.19柱高:這版會改變結果的項目數2.2.5
position = position[timing]
2.0.19 的輸出 [True, True]

2.0.19 會改變結果的項目 0 改變點找到 0 / 4

  • 起點:本頁從這一版開始比較。

變更取自本頁的表;三個案例的輸出取自本頁在 2.0.19、2.2.0、2.2.4 實跑的最小案例,其他版本依各項的生效版本推得。

財報與季度資料

生效版本觸發條件與影響升級時怎麼處理
2.0.21 起,2.2.16 仍保留bool/boolean 季度遮罩轉日期後保留未知值;先 shift() 等操作變成 object 的遮罩不適用(PR #160)見季報布林遮罩的 dtype 前提與填值順序;object 遮罩先 .astype('boolean') 再轉日期
2.0.22,保留於 2.1.0季度 reindex() 改按各公司公布日對齊,不再全為 NaN;股票 Series 改按股票欄位廣播(PR #166、PR #168)明確指定季度轉日期;Series 意義不明時用 mul(s, axis=0/1)
2.0.23,保留於 2.1.0同日公布多季、或舊季晚交,改用已公布且有值的最新季度(PR #169)重新取得輸入、計算訊號;沒有保留錯誤值的開關
2.1.0季度橫斷面先轉公布日,再做排名、cs、sector 與季度 neutralize();避免比較尚未公開的同季財報(PR #184、PR #188)重新排名;日頻結果不能再用季度 .loc 當作同季財報
2.2.0缺少公布日或截止日的季報數值不再提前填入(PR #208)重新計算;缺日期維持未知,不自行補出可交易日
2.2.0月營收截止日與因子日期遇補班交易週六,保留當天,不再延至週一(PR #210)重算包含這些日期的訊號、IC 與分組報酬
2.2.1季度 groupby_category() 改按公布日計算同業統計(PR #220)改成 industry_mean.loc[:'2025-05-15'].tail(1);.loc['2025-Q1'] 不再表示第一季財報

回測與部位

生效版本觸發條件與影響升級時怎麼處理
2.1.0position[timing] 保留 False 日期並空手,過去刪除日期後回測會沿用前期持股(PR #191)確認擇時目的;要空手可明寫 position & timing
2.1.0NaN 部位視為未持有;resample=None 不再漏掉 NaN 前後的進出場(PR #194)合併不同策略用 add(fill_value=0);新建日期補 fill_value=False,重算交易
2.1.0下市或價格尾端至少 20 個交易日缺價的持股出場,之後不再買回;缺價推定不等於確認下市(PR #183)檢查出場日期與交易;歷史績效可能改變
2.1.0布林或總絕對權重大於 1 的部位,先正規化再做 drawdown_control()/target_volatility()(PR #180)重算曝險;回測仍限制最高滿倉,不支援用這些方法加槓桿
2.1.0resample=None 的未來部位列不再延長歷史回測期間(PR #196)比較回測起訖日;需要固定結束日請傳 end_date
2.1.0無時區的部位改採市場時間;非交易日 15:00 前不再把台股訊號退回前一天,最新持股可能改變(PR #185)保存執行時刻、主機時區;歷史比較固定 end_date,最新一期另查換股狀態
2.1.0set_universe() 不帶條件取消篩選,保留市場目錄外的代號;篩選結果為空改報錯(PR #192、PR #181)想限制在市場目錄用 set_universe(exclude_sector=[]);檢查條件拼字
2.1.0 → 2.2.12.1.0~2.2.0 的稀疏出場訊號是單次事件;2.2.1 起預設 exit_mode='state',恢復 2.0.19 的持續條件(PR #177、Issue #224)月/季條件用 state;單次事件明寫 event,保留出場原日期。其他修正仍可能改結果

因子分析、指標與權重

生效版本觸發條件與影響升級時怎麼處理
2.0.22,保留於 2.1.0calc_ic(rank=True) 改為真正的 Spearman;create_factor_data() 的組別改為 1~5、分組較均勻(PR #166)重算 IC 與分組分析;不要沿用舊 0~4 組別標籤
2.2.1產業計算、產業權重、custom report、重複欄位去重不再受 Python hash 順序影響(Issue #225)重存比對結果;門檻附近的小數尾數仍可能影響選股
2.2.2TA-Lib 不支援的參數名稱改報錯,過去可能被忽略而用預設值計算(Issue #274)把 timperiod 改為 timeperiod;還原價用 adjust_price=True 或 adj=True
2.2.5pandas 3 下,價格中間有缺值的股票補回缺值後第一天的報酬;position.weight.inverse_volatility() 等權重方法、event_study() 與槓桿 Position.from_weight() 的結果可能改變(PR #331)使用 pandas 3 的策略重算權重與事件報酬;pandas 2 結果不變

實單下單目標

這兩項只改變下單的目標部位,回測損益與交易紀錄不變。

生效版本觸發條件與影響升級時怎麼處理
2.2.3停損後的 next_weights、Position.from_report() 與回測的換股分配一致;實單目標可能變大、或移除已排除股票(PR #319、PR #314)下單前確認目標;bool 與 float 都可能受影響
2.2.5持有空單的策略在換股之間有持股停損後,report.weights、Position.from_report() 不再放大其餘空單;實單放空部位會變小,與回測持有的部位一致(PR #338)下單前確認目標。只做多的策略不受影響

如果要完全重現舊套件的錯誤計算,需要舊 wheel、同一組相依版本與同一份資料。修正項目通常沒有「沿用舊錯誤」的選項。

技術指標長期缺價與 240 根變化率

2.2.16 起,data.indicator() 在原始日線收盤連續缺價的第 20 根起將輸出設為 NaN,恢復報價後恢復輸出。計算前仍會沿用缺值前的開高低收量,所以單根或連續不到 20 根的短缺口,有足夠暖機資料時仍可能有指標值;不是每一格缺價都變 NaN。週/月指標也依原始日線的缺價狀態,取該週/月最後一根日線的狀態遮罩,不是等 20 週或 20 個月。

這項遮罩避免長期無報價或下市股票持續輸出看似有效的 EMA、RSI、MACD、ATR 等訊號。復牌後不會因這項遮罩重新暖機或永久缺值;但缺價期間仍參與補值計算,復牌後的值不等於「刪掉停牌日再算」。

2.3.1 起,FinlabDataFrame 的 rsi.pct_change(240) 預設不補缺值,等同 rsi.pct_change(240, fill_method=None),也等同 rsi / rsi.shift(240) - 1。240 是資料列數,不是日曆天數。當日或 240 根前任一端為 NaN,當日變化率就為 NaN;即使當日 RSI 已恢復,240 根前仍可能落在缺價遮罩內。這是兩端缺值,不是視窗內有一格 NaN 就全部失效,也不是遞迴向後擴散。

升級時先保留未知值,核對指標條件及兩端缺值的位置。若策略明定使用最後已知值,才明寫 rsi.ffill().pct_change(240, fill_method=None),並另作明確的可交易性限制;填值不代表股票恢復交易。不要把全面 ffill() 當作通用升級解法,也沒有切回長期缺價仍輸出值的開關。

用離線案例比較 2.0.13 與 2.3.2

下載案例,在原始碼 checkout 以外的目錄執行。indicator_gaps 不需登入、不下載行情:固定 360 根合成日 K,第 51 根單獨缺價,第 81~105 根連續缺價,第 106 根恢復報價。它只替換市場讀價,實際呼叫安裝版本的 data.indicator() 與 pct_change()。

python3.12 -m venv before
python3.12 -m venv after
before/bin/python -m pip install "finlab==2.0.13" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
after/bin/python -m pip install "finlab==2.3.2" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
before/bin/python upgrade_results.py indicator_gaps
after/bin/python upgrade_results.py indicator_gaps

macOS、CPython 3.12.4、相同相依版本及正式 PyPI wheel 的實跑輸出如下;True/False 表示有值/NaN。四個指標及 MACD 的三個輸出都有相同的有值狀態。

檢查點2.0.132.3.2
單根缺價TrueTrue
連續第 19 根缺價TrueTrue
連續第 20 根、第 25 根缺價True、TrueFalse、False
第 26 根恢復報價TrueTrue
RSI 的 240 根變化率,第 339、340、346 根[-0.245784, -0.242502, -0.358665][-0.245784, nan, -0.358665]
matches_ratio、default_matches_no_fillTrue、TrueTrue、True

第 340 根當日有 RSI,但 240 根前是第 100 根,恰為連續第 20 根缺價;第 346 根兩端都有值,變化率恢復。上述變化率是 pct_change(240, fill_method=None) 的輸出;default_matches_no_fill 另核對預設呼叫。這組 2.0.13 輸入的舊指標沒有長缺價遮罩,兩者相同,不代表舊版預設已經不補值。

季報布林遮罩:dtype 與未知值

本節保留 2.2.16 的實測與改寫方式。2.3.1 起,布林 fillna(False) 會在欄位只含布林值時轉回 bool;仍為 object 的 FinlabDataFrame 取反則直接報錯,錯誤文字與舊版可能不同。

2.0.21 是季度布林遮罩修正開始生效的版本,2.2.16 仍保留此修正。季頻數值直接比較產生的 bool 遮罩,或原生 nullable boolean 遮罩,經 index_str_to_date() 轉為公布日後使用 nullable boolean:尚未公布的值保持 pd.NA,~ 取反也保持未知。與一般日頻 bool 遮罩以 & 合併時,結果為一般 bool,未知視為 False。

取反時出現 TypeError

這項修正不會自動把 object 遮罩轉回布林。若先 shift(1),首列 NaN 可能讓遮罩變成 object;轉日期後仍是 object,~ 仍可能拋出 TypeError: bad operand type for unary ~: 'float'。先確認 mask.dtypes;對只有布林值與缺值的遮罩,明確轉成 nullable boolean 後再轉日期:

mask = (q > 6).shift(1)  # q 是季頻數值表;此路徑的 mask 為 object
dated = mask.astype('boolean').index_str_to_date()
inverted = ~dated  # 未知值仍是 pd.NA

需要一般 bool 或 np.where 時

含 pd.NA 的遮罩直接 astype(bool) 會報 ValueError,直接 np.where 會報 TypeError。只有策略決定「未知視為 False」時才先填值,而且填值與取反的順序會改變選股語意:

import numpy as np

m = (q > 6).index_str_to_date()
selected = (~m).fillna(False)  # 先取反再填值:尚未公布仍不選
opposite = ~m.fillna(False)  # 先填值再取反:尚未公布會變 True
plain_bool = selected.astype(bool)
weights = np.where(selected, 1, 0)

下載完整案例,在原始碼目錄外執行 python upgrade_results.py quarter_bool_object 可重現 object 的取反錯誤;python upgrade_results.py quarter_bool_dtype 示範轉型與填值順序。以 PyPI finlab 2.2.16、pandas 3.0.6、numpy 2.5.4 實跑,轉型後 dtype 為 boolean,8/2 取反為 [True, False];5/1 尚未公布的 B 取反仍為 pd.NA,先取反再填值為 False,先填值再取反為 True。原本的 quarter_bool 案例仍為 [True, False],不表示所有 2.2.16 遮罩都會報錯。

預設值、輸出與例外

變更需要更新的寫法
Studio AI 與桌面版的 sim(upload=None) 自 2.1.0 不再自動上傳;雲端排程與在 Studio 網站手動執行的筆記本仍會上傳需要上傳時傳 upload=True;研究比較用 upload=False
report.trades['stock_id'] 自 2.0.22 改為純代號名稱用 name,代號加名稱用 symbol;舊欄位不再包含名稱
sim() 支援 end_date;未指定時仍會依訊號列距決定回測期間固定比較窗口用 sim(position, end_date='2025-12-31', upload=False)
get_stats() 增加 camelCase 別名,舊欄位保留;resample 原本無效(從未改變統計頻率),現在警告不依賴 resample 改統計頻率;win_ratio 與 get_metrics()['winRate'] 的交易口徑不同
因子 ic()/calc_metric() 自 2.1.0 不要求索引名稱 date仍建議使用明確的日期/股票 MultiIndex;全 NaN 因子保留 NaN
data.get() 找不到 key 改為 DatasetNotFoundError(RuntimeError 的子類別);下載失敗改為 DataErrorRuntimeError 舊捕捉仍支援找不到 key;Pyodide 用 except DataError,HTTP 狀態用 error.status
2.2.1 季報轉日期不再改寫原表欄位名稱若 stack().reset_index() 需要 symbol,先設 df.columns.name='symbol'
2.2.1 修正 pyarrow < 16 的過期快取錯誤升級後重啟 kernel;暫時不能升級可用 pyarrow>=16,不用刪快取
2.2.2 的 PortfolioSyncManager.update() 遇總資金被不換股策略占滿會整次停止確認 total_balance 與購股現金;成功後才儲存/同步
2.2.4 的 data.indicator(strict=True) 是選用功能預設仍檢查 TA-Lib 參數錯字;嚴格模式拒絕價格 selector,pandas_ta 尚不支援
2.2.3 增加快取修正檢查,2.2.4 撤回;2.2.5 起資料修正後最慢約 5 分鐘取得,不再每次呼叫都多一次查詢2.2.5 起重新呼叫即可;更舊版本請升級。已回傳的表格仍是當時快照

若停損後希望保留現金,請在回測前明確使用浮點權重;五檔各 0.2 不等同布林部位自動等權重重分配。先排除缺少價格的股票,再計算權重,並確認 position_limit。

用最小案例比對兩個版本

下載完整案例。每個案例只呼叫受影響的計算,使用固定價格、財報與公布日期。季度、交易日曆與時鐘以 fixture 提供,不依賴日後更正的線上資料;sim() 使用真正的回測引擎。執行回測案例需要正常 FinLab 登入,見登入說明。這些合成輸出用來定位版本差異,不能代表真實策略績效。

先將下載的檔案放到原始碼目錄以外,再建立兩個環境,用同一個案例名稱各跑一次:

python3.13 -m venv before
python3.13 -m venv after
before/bin/python -m pip install "finlab==2.0.19" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
after/bin/python -m pip install "finlab==2.2.4" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
before/bin/python upgrade_results.py rank_ic
after/bin/python upgrade_results.py rank_ic

把最後的 rank_ic 換成下表的案例名稱,即可用同一段程式比較兩版。

以下實跑環境為 macOS、CPython 3.13.3、pandas 2.2.3、numpy 2.2.6、PyPI 已發布的 FinLab wheel;TA-Lib 案例用 TA-Lib 0.8.1。日期案例採 UTC 主機、固定時鐘。重複欄位案例指定 PYTHONHASHSEED=0。小數在表內四捨五入,完整程式會印出原值。NaN 表示未知或缺值,舊版錯誤也是實跑結果。

27 個案例在 2.0.19 與 2.2.4 的輸出
案例2.0.19 輸出2.2.4 輸出比較的是什麼
quarter_boolTypeError: bad operand type for unary ~: 'float'[True, False]公布日展開後的遮罩反相
latest_quarter[5.0, 9.0][7.0, 3.0]同日公布兩季所採用的值
quarter_reindex[NaN, NaN][5.0, NaN]一家公司已公布、另一家尚未公布
quarter_rank0.51.0第一家公司公布時的橫斷面百分位
quarter_group['2023-Q1', 7.0]['2023-05-01 00:00:00', 5.0]產業平均的索引與第一筆值
missing_date5.0NaN缺少日期的財報不再提前填入
series[NaN, NaN][200.0, 300.0]股票權重 Series 的廣播方向
timing[True, True][True, False, True]保留空手日期
rank_ic0.78502642096301011.0Spearman IC
quantiles[0,1,1,2,2,2,3,4,4,4][1,1,2,2,3,3,4,4,5,5]十檔股票的分位組別
drawdown[2.0, 0.6536433173][1.0, 0.4806677708]第 0、5 列的總絕對權重
volatility[2.0, 0.0609895989][1.0, 0.0609895989]暖機列先正規化,並非每一列都不同
nan_position['2022-01-04']['2022-01-04','2022-01-07']NaN 前後實際進場的日期
short_positionIndexError'2022-04-22'兩列部位的回測結束日
future_position'2022-04-22''2022-01-17'未來訊號不再延長稀疏部位的回測
delistedNaN0.0價格尾端長期缺價後的 B 部位
monthly_saturday'2016-09-12''2016-09-10'月營收使用的交易日對齊路徑
factor_saturday'2016-09-12''2016-09-10'因子資料納入的補班交易日
duplicate_columns['c','a','b']['a','b','c']同一 seed 的欄位排列
universe_reset['2330','2317']['2330','2317','0050O']不帶條件是否仍排除目錄外代號
universe_empty['2330','2317','0050O']ValueError拼錯產業不再默默使用全市場
from_weightAssertionError: Unexpectedly insufficient funds.2330、2317 各 5 張、權重各 0.5權重總和 1.6 先縮為滿倉
clock{'2330': 1.0}{'2317': 1.0}台北週六 00:30 的最新訊號,主機為 UTC
indicator_typoNaN(仍用預設 30 日均線)ValueError,列出 timeperiodtimperiod=3 的錯字不再被忽略
stop_target2317、1301 各 0.22317、1301 各 0.5停損三檔後的下一次換股目標;回測計算不變
stop_reentry2330、2317、2454 各 1/32317、2454 各 0.5不再買回這次換股已排除的 2330;回測計算不變
pandas_leftDataFrame、2×2DataFrame、2×2端點版本的 pandas 左側運算結果相同
中間版本的結果

中間版本也會影響升級路徑。同一案例以相同 pandas/numpy 實跑:

案例修正前中間版本修正後
hold_default2.0.19:[True,False,False]2.2.0:[True,False,True]2.2.1/2.2.4:[True,False,False]
pandas_left2.0.21:DataFrame、2×22.0.23:FinlabDataFrame、1×02.1.0/2.2.4:DataFrame、2×2

2.0.23 是已撤回版本,只有追查歷史行為時才在隔離環境安裝。hold_until(exit_mode='event') 可在 2.2.1 起明確選擇事件模式;舊版不接受 exit_mode。

讓結果可以重現

要重現一次回測,需要同一份程式、同一組套件版本、同一份輸入資料與同一組 sim() 參數,四樣都要另外保存。

鎖住執行環境

正式策略與新版本的比較環境分開安裝。先保存現有環境:

python -VV > python-version.txt
python -m pip freeze > requirements.lock.txt
python -m pip download --only-binary=:all: -r requirements.lock.txt -d wheels

重建時使用相同的 Python 版本、作業系統與 CPU 架構:

python -m pip install --no-index --find-links=wheels -r requirements.lock.txt

不要把驗證環境的版本號直接套到既有正式環境;先鎖住正式策略實際使用的 finlab、pandas、numpy、pyarrow、scipy、TA-Lib/pandas_ta 等完整相依版本。ML 策略另保存模型、亂數 seed、特徵欄位順序與模型套件版本。升級後重啟 Python/Jupyter kernel,避免記憶體裡仍載入舊套件。

一般 pandas Series/DataFrame 的 pct_change() 預設隨版本不同:pandas 2.2 仍會先往前填缺值,pandas 3 改為 fill_method=None。策略應明確選擇缺值處理,參見 pandas 2.2 文件與 pandas 3 文件。

import pandas as pd

s = pd.Series([100.0, None, 110.0])
print(s.pct_change().tolist())
# pandas 2.2.3:[nan, 0.0, 0.10000000000000009]
# pandas 3.0.6:[nan, nan, nan]
print(s.pct_change(fill_method=None).tolist())  # 明確保留缺值
print(s.ffill().pct_change(fill_method=None).tolist())  # 明確先填值

2.2.5 起,FinLab 內建的 position.weight.inverse_volatility() 等權重方法、event_study() 與 Position.from_weight() 會先沿用缺值前的價格再計算報酬,pandas 2 與 3 結果相同;策略裡一般 pandas 的 pct_change() 仍需依上例明確選擇。FinlabDataFrame 自 2.3.1 起預設不填值;沿用前值的條件與可交易性限制見技術指標缺價。

自動保存整支策略的資料輸入

2.2.22 起,data.snapshot() 可將完整一次執行中,data.get()、data.gets() 實際回傳的表格保存到新的本機目錄,包含財報與 sim() 內部讀取的價格、基準、分類等資料,也支援帶日期範圍或指定版本的讀取。請從第一次取資料開始包住整支策略,並在區塊內完成回測及需要的報告計算:

from finlab import data
from finlab.backtest import sim

def research():
    close = data.get('price:收盤價')
    position = (close > close.average(20)).loc['2020-01-01':]
    report = sim(position, resample='M', end_date='2025-12-31', upload=False)
    stats = report.get_stats()
    return report, stats

# 目錄必須尚未存在;成功離開區塊後才寫入完整清單。
with data.snapshot('research-baseline'):
    baseline, baseline_stats = research()

# 保持相同程式、參數、日期區間、Python 與套件版本。
with data.snapshot('research-baseline', mode='replay'):
    restored, restored_stats = research()

# 離開區塊就恢復一般讀取,可另存新資料結果作比較。
with data.snapshot('research-new-data'):
    latest, latest_stats = research()

同一個 Python 程式的工作執行緒也會參與保存/還原;請等所有平行工作完成後才離開區塊。同時只允許一個保存/還原區塊。

還原只讀保存的輸入:缺表、檔案讀不到、讀取範圍/股票母體不同時直接報錯,不會混入本機一般快取或雲端最新值。lazy=True 仍可使用,保存的是運算前的實際資料表。

manifest.json 記錄資料與檔名對照,以及 Python、finlab、pandas、numpy、pyarrow 版本;還原要求這些版本相同。保存的是本次真正用到的輸入,並非所有表在同一時刻的資料版本;不會找回已過期且未備份的舊資料,也不會自動增加新日期。需要額外本機空間,請保留整個目錄;pickle 僅讀取自己保存、可信任的檔案。

這些不會自動保存,需要另外處理:

  • 程式碼、完整環境 lock、亂數種子、策略參數及固定的 end_date
  • 區塊外已讀入的變數、自訂價格/Market 外部資料、第三方 API 與其他自訂檔案:請將資料讀取移入區塊或另外備份

歷史還原不代表當下可交易;sim() 的登入授權仍照常檢查,結果上傳請設 upload=False。

保存失敗的情況

相同條件重複取同一份資料時,若值在保存途中變動,這次保存會失敗,請改用新目錄重新完整執行。即使策略自行捕捉讀表錯誤,未保存完整輸入的執行也不會產生完整清單。未完成或失敗的目錄不能還原,也不會被自動覆寫。

使用封存研究模式

以下設定將隨下一次 FinLab 套件更新提供。啟動新的 Python 程序後,在任何 finlab 匯入之前指定封存目錄與事先準備的共享快取:

import os
os.environ['FINLAB_ARCHIVE_DIR'] = '/absolute/path/to/archive'
os.environ['FINLAB_SHARED_CACHE_DIR'] = '/absolute/path/to/prepared-runtime-cache'

from finlab import data
close = data.get('price:收盤價')

封存研究模式涵蓋 get/gets、snapshot 還原與 sim(upload=False) 的資料依賴:預設只讀指定資料,不查套件新版、不下載資料;缺表直接報錯。FileStorage 不建立目錄、lock 或 decoded 旁檔,不刪舊檔、不重設檔案時間,data.clear() 也會拒絕刪除封存。它不會因為封存目錄不能寫入而改用另一份資料。

設定效果
FINLAB_ARCHIVE_DIR啟用上述模式並指定預設 FileStorage;FileStorage(path) 仍可選擇另一份唯讀來源。
FINLAB_SHARED_CACHE_DIR指定版本檢查、資料目錄、發布版本、交易日曆與回測授權的共享快取。封存模式只讀;未指定時不讀其他目錄的共享快取。一般線上執行也可用它準備快取。
FINLAB_SHARED_CACHE=0停用共享快取讀寫;離線回測便不能從磁碟取得授權。
FINLAB_DECODED_CACHE=0停用 decoded 解壓縮副本,仍可讀 Feather,但可能需要較多解壓縮時間。
FINLAB_DECODED_CACHE_DIR將自行建立的 decoded 副本改到另一個目錄;封存模式只讀既有副本,不建立新副本。

請先在線上以同一帳號準備資料與有效回測授權,並設定相同的 FINLAB_SHARED_CACHE_DIR 保存所需快取,再啟動封存程序。回測仍會驗證授權,不會略過;登入或授權失效、缺依賴時會失敗,不會自動更新登入或回到網路。資料目錄與日曆可沿用超過重新整理時間、但仍適用的本機內容;日曆原有的可用期間限制與授權期限都保留。

data.use_local_data_only = True 本身只限制資料下載,並不代表整個程序離線或唯讀。未設定封存模式時,一般線上行為照舊。這個模式管理研究資料與快取,不攔截自訂程式、第三方套件、券商 SDK 或另外呼叫的雲端服務。需要限制整個程序時,請使用 python -B 關閉 Python 位元組快取,並由執行環境限制所有網路與檔案寫入。

snapshot 的 record 沿用上述讀取設定,仍會寫入你明確指定的新目錄內的輸入檔與 manifest.json。資料 snapshot 不包含登入憑證、回測授權或交易日曆,完整 sim() 仍須另外備妥所需依賴。唯讀還原請用 mode='replay'、upload=False 與固定的 end_date。

手動記錄資料版本

2.2.0 起,付費資料會員可用 data.versions() 列出仍保留的 generation、公布/取代時間、大小與 hash,再下載指定 generation。先選 generation,再讀取;不要先抓最新值、再用另一個請求的最新 metadata 當作它的版本。

import json
from pathlib import Path
from finlab import data

datasets = ['price:收盤價', 'etl:adj_close']  # 列出策略的所有輸入
manifest = {}
for dataset in datasets:
    versions = data.versions(dataset)
    if versions.empty:
        raise RuntimeError(f'{dataset} 沒有可用版本')
    row = versions.iloc[-1]
    generation = str(row['generation'])
    snapshot = data.get(dataset, version=generation)
    # 保存實際輸入;檔名與資料集名稱對照也留在 manifest
    filename = f'input-{len(manifest)}.pkl'
    snapshot.to_pickle(filename)
    manifest[dataset] = {
        'generation': generation,
        'hash': str(row['hash']),
        'time_created': str(row['time_created']),
        'file': filename,
    }
Path('data-versions.json').write_text(
    json.dumps(manifest, ensure_ascii=False, indent=2)
)

generation 固定單張表,不代表跨資料表的原子快照。還原價、公布日期、交易日曆、股票母體與產業分類也是輸入,請一併保存。自行保存資料限於你的使用權限;pickle 只讀取自己保存、可信任的檔案。

版本保留期與 as_of 的限制

保留期以 data.versions() 當次列出的內容為準,不能把「約三週」當成長期保證。2.2.4 的版本介面說明為:版本被取代滿 30 天且已有 10 個較新版本後可刪除;這項規則自 2026-09-26 生效,不會補出先前未保留的版本。指定 generation 過期後,僅靠 generation/hash 無法重新下載,因此長期重現需自行保存實際輸入。hash 是伺服器資料物件的驗證值,不是回測結果的 hash。

as_of 未帶時區時採台北時間,只有日期代表當天 00:00,不代表當日收盤。version 與 as_of 只能擇一,不能搭配 start/end、逐筆/分鐘資料或 use_local_data_only。財報的永久歷史版本改查 financial_statement_versions。這個 API 仍屬實驗性。

保存策略與回測設定

保存策略原始碼、實際執行時刻與時區、環境 lock、資料 manifest、經處理的輸入價格及 position,並把所有 sim() 參數明寫,不依賴預設值:市場、成交價、換股頻率/偏移、費率、稅率、停損停利、移動停利、觸價模式、持股上限、retain_cost_when_rebalance、stop_trading_next_period、開始/結束範圍與 upload。自訂 Market、價格矩陣與 benchmark 也需保存程式及輸入,不能只保存名稱。

import json
from pathlib import Path
from finlab.backtest import sim

settings = dict(
    resample='M',
    trade_at_price='close',
    market='TW_STOCK',
    fee_ratio=0.001425,
    tax_ratio=0.003,
    position_limit=1,
    stop_loss=None,
    take_profit=None,
    trail_stop=None,
    touched_exit=False,
    retain_cost_when_rebalance=False,
    stop_trading_next_period=True,
    end_date='2025-12-31',
    upload=False,
)
position.to_pickle('position.pkl')  # 保存你實際傳入的 position
Path('sim-settings.json').write_text(json.dumps(settings, indent=2))
report = sim(position, **settings)
report.to_pickle('report.pkl')
report.to_html('report.html')

report.pkl、HTML 或雲端報告可保存結果,但不會自動封存全部來源資料、相依環境、原始碼與自訂市場。回測報告也不是實際成交紀錄。驗證重現時,依序比較資料值與日期、訊號、position、交易日期與數量、報酬曲線,再比較 Sharpe 等摘要;先固定 end_date,再另外驗證最新一期的換股與實單目標。

用程式追蹤版本影響

公開 feed:JSON、Atom。兩者在文件建置時,從同一份更新日誌與逐項審閱的影響分類產生,涵蓋 2.0.19 起的已發布版本;Unreleased 不會當作已發布。

每個項目包含三個布林標記(results_may_change、behavior_change、experimental)、functions、trigger、references 與完整說明。results_may_change 指計算/選股/回測數字;只改實單目標則用 behavior_change,仍應閱讀說明。false 不代表資料從此不會更正。

下面以 2.0.13 → 2.3.2 為例,列出 feed 內標記為可能改變結果或行為的項目;起點也可改成 2.1.1 或 2.2.26。feed 只涵蓋 2.0.19 起,2.0.14~2.0.18 請另查上表與更新日誌:

import requests

version = lambda text: tuple(map(int, text.split('.')))
start, end = version('2.0.13'), version('2.3.2')
feed = requests.get('https://finlab.finance/docs/releases.json', timeout=30)
feed.raise_for_status()
for release in feed.json()['releases']:
    if start < version(release['version']) <= end:
        for item in release['items']:
            if item['results_may_change'] or item['behavior_change']:
                print(release['version'], item['functions'], item['trigger'])

區間排除起始版、包含目標版;不要用字串比較版本。兩個 yanked 版本仍列在 feed,避免漏掉曾升級至該版的歷史。分類保留每版當時的變更,所以需注意後續的還原:例如 2.2.1 的 hold_until 與 2.2.4 的快取檢查。文件與 feed 會先上線並驗證,再上傳新版至 PyPI。

下一步

↑↓ 選擇 Enter 開啟 Esc 關閉