Skip to content

FinLab Module Architecture & Relationship Diagram

This document provides visual diagrams illustrating the relationships, data flow, and workflows among FinLab's modules, helping you quickly understand the system architecture.

Overall Architecture Diagram

FinLab uses a layered architecture, from the Data Layer at the bottom to the Trading Layer at the top:

graph TB
    subgraph "交易層 Trading Layer"
        portfolio[finlab.portfolio<br/>組合管理]
        online[finlab.online<br/>實盤交易]
    end

    subgraph "分析層 Analysis Layer"
        analysis[finlab.analysis<br/>策略分析]
        optimize[finlab.optimize<br/>參數優化]
        plot[finlab.plot<br/>資料視覺化]
    end

    subgraph "回測層 Backtest Layer"
        backtest[finlab.backtest<br/>回測引擎]
        report[finlab.report<br/>報告生成]
        market[finlab.market<br/>市場物件]
    end

    subgraph "策略層 Strategy Layer"
        ml_feature[finlab.ml.feature<br/>特徵工程]
        ml_label[finlab.ml.label<br/>標籤生成]
        ml_model[finlab.ml.qlib<br/>模型訓練]
    end

    subgraph "資料層 Data Layer"
        data[finlab.data<br/>資料存取]
        dataframe[finlab.dataframe<br/>FinlabDataFrame]
    end

    %% 資料流向
    data --> dataframe
    dataframe --> ml_feature
    dataframe --> backtest
    ml_feature --> ml_label
    ml_label --> ml_model
    ml_model --> backtest
    backtest --> report
    report --> analysis
    report --> optimize
    analysis --> portfolio
    optimize --> backtest
    portfolio --> online
    market --> backtest
    dataframe --> plot

    style data fill:#e1f5ff
    style backtest fill:#fff4e1
    style analysis fill:#e8f5e9
    style online fill:#fce4ec

Core Workflows

Workflow 1: Basic Strategy Development

The basic flow from data loading to report generation:

sequenceDiagram
    participant User as 使用者
    participant Data as finlab.data
    participant DF as FinlabDataFrame
    participant Backtest as finlab.backtest
    participant Report as Report 物件

    User->>Data: data.get('price:收盤價')
    Data-->>User: DataFrame
    User->>DF: 計算指標 .average(20)
    DF-->>User: FinlabDataFrame
    User->>DF: 產生訊號 close > ma20
    DF-->>User: bool DataFrame
    User->>Backtest: sim(position, resample='M')
    Backtest->>Report: 建立 Report 物件
    Report-->>User: 回測結果
    User->>Report: report.display()
    Report-->>User: 顯示績效圖表

Workflow 2: Strategy Optimization

Use sim_conditions() to test multiple condition combinations:

flowchart TD
    A[定義多個候選條件] --> B[組合成 dict]
    B --> C{使用 sim_conditions}
    C --> D[生成所有組合<br/>2^n - 1 種]
    D --> E[對每個組合執行回測]
    E --> F[收集所有 Report]
    F --> G[建立 ReportCollection]
    G --> H{選擇視覺化方式}
    H -->|熱力圖| I[plot_stats heatmap]
    H -->|棒狀圖| J[plot_stats bar]
    H -->|折線圖| K[plot_creturns]
    I --> L[找出最佳組合]
    J --> L
    K --> L
    L --> M[使用最佳組合重新回測]

    style C fill:#fff4e1
    style G fill:#e8f5e9
    style L fill:#fce4ec

Workflow 3: Machine Learning Strategy

The complete ML strategy development workflow:

flowchart TD
    A[載入原始資料<br/>finlab.data] --> B[特徵工程<br/>finlab.ml.feature]
    B --> C[標籤生成<br/>finlab.ml.label]
    C --> D[模型訓練<br/>finlab.ml.qlib]
    D --> E[預測持倉權重]
    E --> F[回測<br/>finlab.backtest.sim]
    F --> G{績效是否滿意?}
    G -->|否| H[調整特徵或模型]
    H --> B
    G -->|是| I[執行深度分析]
    I --> J[樣本外測試]
    J --> K{通過驗證?}
    K -->|否| H
    K -->|是| L[部署實盤]

    style B fill:#e1f5ff
    style D fill:#fff4e1
    style I fill:#e8f5e9
    style L fill:#fce4ec

Workflow 4: Live Trading

The complete flow from backtesting to live trading:

sequenceDiagram
    participant User as 使用者
    participant Report as Report 物件
    participant Account as Account 物件
    participant Executor as OrderExecutor
    participant Broker as 券商 API

    User->>Report: report.upload(name)
    Report-->>User: 上傳成功
    User->>Report: report.position_info()
    Report-->>User: 持股清單
    User->>Account: 設定券商帳戶
    Account-->>User: 連線成功
    User->>Executor: OrderExecutor(report, account)
    Executor->>Executor: 計算買賣清單
    User->>Executor: executor.execute()
    Executor->>Broker: 發送買單
    Broker-->>Executor: 買單回報
    Executor->>Broker: 發送賣單
    Broker-->>Executor: 賣單回報
    Executor-->>User: 執行完成
    User->>Account: 查詢部位
    Account->>Broker: 取得部位資訊
    Broker-->>Account: 部位資料
    Account-->>User: 顯示實盤持股

Module Function Reference Table

Module Main Classes/Functions Purpose Dependencies
finlab.data get() Fetch financial data from the database (none)
finlab.dataframe FinlabDataFrame Enhanced DataFrame with financial computation support pandas
finlab.backtest sim() Backtest engine for simulating trades data, dataframe, market
finlab.report Report Backtest report and performance analysis backtest
finlab.optimize sim_conditions(), ReportCollection Test multiple condition combinations backtest
finlab.analysis LiquidityAnalysis, MaeMfeAnalysis, etc. In-depth strategy analysis report
finlab.market Market, TWMarket, USMarket Market data and characteristics data
finlab.ml.feature add_ta(), add_fundamental() ML feature engineering data
finlab.ml.label cls_label(), reg_label() ML label generation data
finlab.ml.qlib train() Model training ml.feature, ml.label
finlab.portfolio Portfolio, PortfolioSyncManager Multi-strategy portfolio management report
finlab.online OrderExecutor, SinopacAccount Live trading execution report, portfolio
finlab.plot plot_creturns(), plot_heatmap() Data visualization dataframe

Data Flow Diagram

The complete data flow from data sources to live trading:

flowchart LR
    A[資料來源<br/>GCS/BigQuery] --> B[finlab.data.get]
    B --> C[DataFrame]
    C --> D{用途?}

    D -->|技術指標| E[FinlabDataFrame<br/>運算方法]
    D -->|機器學習| F[ml.feature<br/>特徵工程]

    E --> G[產生訊號<br/>bool DataFrame]
    F --> H[ml.label<br/>標籤生成]
    H --> I[ml.qlib<br/>模型訓練]
    I --> J[預測權重<br/>float DataFrame]

    G --> K[finlab.backtest.sim]
    J --> K

    K --> L[Report 物件]
    L --> M{分析類型?}

    M -->|參數優化| N[optimize.sim_conditions]
    M -->|深度分析| O[analysis 模組]
    M -->|視覺化| P[plot 模組]
    M -->|實盤交易| Q[online.OrderExecutor]

    N --> L
    O --> R[分析報告]
    P --> S[互動式圖表]
    Q --> T[券商 API]
    T --> U[實盤部位]

    style B fill:#e1f5ff
    style K fill:#fff4e1
    style O fill:#e8f5e9
    style Q fill:#fce4ec

Class Inheritance Diagrams

Market Inheritance Tree

classDiagram
    class Market {
        <<abstract>>
        +get_name() str
        +get_freq() str
        +get_price() DataFrame
        +get_benchmark() Series
        +get_asset_id_to_name() dict
    }

    class TWMarket {
        +get_name() "tw_stock"
        +get_benchmark() 加權指數
        +get_industry() dict
        +market_close_at_timestamp()
    }

    class USMarket {
        +get_name() "us_stock"
        +get_benchmark() S&P 500
        +market_close_at_timestamp()
    }

    class ROTCMarket {
        +get_name() "rotc_stock"
    }

    class CustomMarket {
        +get_name() "custom"
        +自訂資料來源
    }

    Market <|-- TWMarket
    Market <|-- USMarket
    Market <|-- ROTCMarket
    Market <|-- CustomMarket

Analysis Inheritance Tree

classDiagram
    class Analysis {
        <<abstract>>
        +calculate_trade_info() list
        +analyze() dict
        +display() Figure
        +is_market_supported() bool
    }

    class LiquidityAnalysis {
        +流動性風險檢測
        +漲跌停、成交量
    }

    class MaeMfeAnalysis {
        +波動分析
        +MAE/MFE 12 子圖
    }

    class PeriodStatsAnalysis {
        +時期穩定性
        +年度、月度表現
    }

    class InequalityAnalysis {
        +不等式因子
        +基尼係數
    }

    class AlphaBetaAnalysis {
        +Alpha/Beta 分析
    }

    class DrawdownAnalysis {
        +回撤分析
    }

    class CustomAnalysis {
        +自訂分析邏輯
    }

    Analysis <|-- LiquidityAnalysis
    Analysis <|-- MaeMfeAnalysis
    Analysis <|-- PeriodStatsAnalysis
    Analysis <|-- InequalityAnalysis
    Analysis <|-- AlphaBetaAnalysis
    Analysis <|-- DrawdownAnalysis
    Analysis <|-- CustomAnalysis

FinlabDataFrame Inheritance

classDiagram
    class DataFrame {
        <<pandas>>
        +基本 DataFrame 功能
    }

    class FinlabDataFrame {
        +average() 移動平均
        +is_largest() 排名
        +is_smallest() 排名
        +quantile() 分位數
        +hold_until() 進出場語法糖
        +and_then() 組合邏輯
    }

    DataFrame <|-- FinlabDataFrame

Beginner Learning Path

flowchart TD
    A[開始] --> B[學習 finlab.data<br/>資料存取]
    B --> C[學習 FinlabDataFrame<br/>指標計算]
    C --> D[學習 finlab.backtest<br/>基礎回測]
    D --> E[學習 Report 物件<br/>績效分析]
    E --> F{想要深入?}
    F -->|是| G[學習 finlab.analysis<br/>深度分析]
    F -->|否| K[開始實盤交易<br/>finlab.online]
    G --> H[學習 finlab.optimize<br/>參數優化]
    H --> I[學習完整工作流程]
    I --> J{想用機器學習?}
    J -->|是| L[學習 finlab.ml<br/>機器學習模組]
    J -->|否| K
    L --> K
    K --> M[精通!]

    style A fill:#e1f5ff
    style D fill:#fff4e1
    style G fill:#e8f5e9
    style K fill:#fce4ec
    style M fill:#c8e6c9

Advanced Development Path

flowchart TD
    A[熟悉基礎回測] --> B{開發需求?}
    B -->|多策略組合| C[學習 finlab.portfolio<br/>組合管理]
    B -->|自訂市場| D[繼承 Market 類別<br/>開發自訂市場]
    B -->|自訂分析| E[繼承 Analysis 類別<br/>開發分析模組]
    B -->|機器學習| F[學習 finlab.ml<br/>特徵、標籤、模型]
    C --> G[多策略實盤]
    D --> H[回測海外市場/加密貨幣]
    E --> I[客製化分析報告]
    F --> J[機器學習策略]
    G --> K[進階應用]
    H --> K
    I --> K
    J --> K

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style K fill:#c8e6c9

Data Exchange Formats Between Modules

Primary Data Formats

Data Type Format Description Example
Price Data pd.DataFrame index: dates, columns: stock symbols data.get('price:收盤價')
Selection Signal pd.DataFrame(bool) True = buy, False = not holding close > ma20
Position Weight pd.DataFrame(float) Values between 0-1, representing position ratio ML model predictions
Trade Records pd.DataFrame Detailed per-trade information report.get_trades()
Performance Metrics dict Various statistical indicators of the strategy report.get_stats()
Benchmark Index pd.Series Time series of price data TWMarket.get_benchmark()

Signal Conversion Flow

flowchart LR
    A[條件判斷<br/>close > ma20] --> B[bool DataFrame<br/>True/False]
    B --> C{是否需要出場邏輯?}
    C -->|是| D[hold_until<br/>加入出場條件]
    C -->|否| E[直接作為 position]
    D --> E
    E --> F[finlab.backtest.sim<br/>執行回測]
    F --> G[Report 物件<br/>包含績效與交易]

    style B fill:#e1f5ff
    style D fill:#fff4e1
    style F fill:#e8f5e9

Common Usage Patterns

Pattern 1: Quick Strategy Validation

# Minimal flow
close = data.get('price:收盤價')
position = close > close.average(20)
report = sim(position, resample='M')
report.display()

Pattern 2: Complete Strategy Development

# Complete flow
data → 指標計算 → 產生訊號 → 參數優化 → 深度分析 → 樣本外測試 → 實盤交易

Pattern 3: Machine Learning Strategy

# ML flow
data → feature engineering → label generation → model training → 預測 → 回測 → 分析

Pattern 4: Multi-Strategy Portfolio

# Portfolio flow
策略 A report →
策略 B report →  Portfolio → PortfolioSyncManager → 實盤多策略
策略 C report →

Performance Optimization Tips

Data Access

flowchart TD
    A[需要使用資料] --> B{資料量大小?}
    B -->|小<br/>單一股票| C[直接使用 data.get]
    B -->|中<br/>數十個指標| D[一次載入<br/>避免重複呼叫]
    B -->|大<br/>大量回測| E[考慮使用<br/>本地快取]

    C --> F[執行策略邏輯]
    D --> F
    E --> F

    style C fill:#e8f5e9
    style E fill:#fff4e1

Backtest Optimization

Bottleneck Optimization Method
Too many condition combinations Pre-filter with individual conditions, remove poor ones
Data range too large Shorten backtest period or increase resample frequency
High computational complexity Use vectorized operations, avoid loops
Insufficient memory Process in batches or use longer resample periods

Reference Resources

Detailed Documentation

API Reference

Practical Examples