自由現金流多因子（2013 年起）

"""自由現金流多因子（2013 年起）：跑到最新資料的版本（/strategies/strategy-dog-free-cash-flow-stock-screen-backtest 的數字來源）。

條件與 /blog/strategy-dog-free-cash-flow-stock-screen-backtest 附的 strategy.py 相同，只是不截斷結束日：
- 自由現金報酬率（自由現金流 ÷ 股東權益加長短期借款）全市場前 30%
- 月營收年增率為正，股價高於 60 個交易日前
- 三個條件同時成立就持有，等權、每月換股，sim() 預設手續費 0.1425% 與證交稅 0.3%

統計口徑：日夏普 = 日報酬平均 / 標準差 × √252，不扣無風險利率；
0050 含息 = etl:adj_close 還原價買進持有，與策略同一段期間。
執行後會在目前目錄輸出 data.csv（淨值曲線）與 metrics.json（統計）。

    pip install finlab
    python strategy.py

finlab 需要資料時會自動引導登入，不需要在程式裡填 token。
"""

import json

import numpy as np
import pandas as pd

import finlab
from finlab import data
from finlab.backtest import sim

STRATEGY_NAME = "自由現金流多因子（2013 年起）"
FCF_TOP = 0.7         # 自由現金報酬率百分位門檻（前 30%）
MOMENTUM_DAYS = 60    # 動能回看交易日（約三個月）

def build_report():
    fcf = data.get("fundamental_features:自由現金流量")
    equity = data.get("financial_statement:股東權益總額")
    short_debt = data.get("financial_statement:短期借款")
    long_debt = data.get("financial_statement:長期借款")
    revenue_yoy = data.get("monthly_revenue:去年同月增減(%)")
    close = data.get("price:收盤價")

    invested_capital = equity.fillna(0) + short_debt.fillna(0) + long_debt.fillna(0)
    fcf_yield = (fcf / invested_capital).replace([np.inf, -np.inf], np.nan)
    momentum = close / close.shift(MOMENTUM_DAYS)
    position = (
        (fcf_yield.rank(axis=1, pct=True) > FCF_TOP)
        & (revenue_yoy > 0)
        & (momentum > 1)
    )
    return sim(position, resample="M", upload=False, name=STRATEGY_NAME)


def curve_stats(curve: pd.Series) -> dict:
    curve = curve / curve.iloc[0]
    daily = curve.pct_change().dropna()
    years = (curve.index[-1] - curve.index[0]).days / 365.25
    return {
        "cagr": curve.iloc[-1] ** (1 / years) - 1,
        "daily_sharpe": daily.mean() / daily.std() * 252 ** 0.5,
        "max_drawdown": (curve / curve.cummax() - 1).min(),
        "total_return": curve.iloc[-1] - 1,
    }


def main() -> None:
    finlab.login()
    # 0050 要在策略設定股票池之前取得
    bench_all = data.get("etl:adj_close")["0050"].dropna()
    report = build_report()

    # 從第一次有部位的那天起算，0050 含息用同一段期間
    creturn = report.creturn.dropna()
    first_move = (creturn != creturn.iloc[0]).argmax()
    creturn = creturn.iloc[max(first_move - 1, 0):]
    bench = bench_all.loc[creturn.index[0]:creturn.index[-1]]

    strategy_stats = curve_stats(creturn)
    bench_stats = curve_stats(bench)
    holdings = (report.position.fillna(0) != 0).sum(axis=1)
    strategy_stats["avg_holdings"] = holdings[holdings > 0].mean()

    start, end = creturn.index[0].date(), creturn.index[-1].date()
    print(f"期間 {start} 至 {end}")
    for label, s in [("策略", strategy_stats), ("0050 含息", bench_stats)]:
        print(f"{label}：年化 {s['cagr']:.2%}，日夏普 {s['daily_sharpe']:.2f}，最大回撤 {s['max_drawdown']:.2%}")

    curves = pd.DataFrame({STRATEGY_NAME: creturn / creturn.iloc[0], "0050含息": bench / bench.iloc[0]})
    curves.index.name = "date"
    curves.round(6).to_csv("data.csv")
    metrics = {
        "window": f"{start}/{end}",
        "star": STRATEGY_NAME,
        "variants": {STRATEGY_NAME: {k: round(float(v), 6) for k, v in strategy_stats.items()}},
        "benchmark_0050": {k: round(float(v), 6) for k, v in bench_stats.items()},
        "run_date": str(pd.Timestamp.today().date()),
        "finlab_version": finlab.__version__,
        "generated_by": "static/blog/strategy-dog-free-cash-flow-stock-screen-backtest/validation/strategy.py",
    }
    with open("metrics.json", "w", encoding="utf-8") as f:
        json.dump(metrics, f, ensure_ascii=False, indent=2)


if __name__ == "__main__":
    main()