SplitterAdapter

SplitterAdapter 處理訓練/驗證集的資料分割，具備重疊控制功能。

類別架構

classDiagram

    class SplitterAdapter {
        +config: dict
        +splitter: Splitter
        +is_custom_data: bool
        +ori_loader_adapter: LoaderAdapter
        +ctrl_loader_adapter: LoaderAdapter
        +__init__(config)
        +run() tuple~dict, dict, list~
        -_create_loader_config(config, key) dict
    }

    class Splitter {
        +config: dict
        +num_samples: int
        +train_split_ratio: float
        +split(data, metadata) tuple
        -_bootstrap_with_overlap_control()
    }

    class LoaderAdapter {
        +load() tuple~DataFrame, Schema~
    }

    SplitterAdapter ..> Splitter : 用於資料分割
    SplitterAdapter ..> LoaderAdapter : 用於 custom_data 方法

    %% 樣式定義
    class SplitterAdapter {
        <<主要類別>>
    }
    style SplitterAdapter fill:#E6E6FA

    class Splitter {
        <<核心模組>>
    }
    style Splitter fill:#4169E1,color:#fff

    class LoaderAdapter {
        <<選用：自訂資料>>
    }
    style LoaderAdapter fill:#FFE4E1

    note for SplitterAdapter "1. 正常模式：使用 Splitter 進行自助採樣\n2. 自訂資料模式：使用 LoaderAdapter 載入 ori/control 資料\n3. 提供重疊控制以進行多次採樣"

圖例：

• 淺紫色框：SplitterAdapter 主類別
• 藍色框：核心分割模組
• 淺粉色框：自訂資料模式使用的 LoaderAdapter
• ..>：依賴關係

主要功能

• 統一的資料分割介面
• 具備重疊控制的拔靴法抽樣
• 支援多重樣本產生
• 回傳分割資料、詮釋資料和訓練索引
• 與管線系統整合

方法參考

__init__(config: dict)

初始化 SplitterAdapter 實例，設定分割配置。

參數：

• config：dict，必要
  • 配置參數字典
  • 鍵值：num_samples、train_split_ratio、random_state、max_overlap_ratio、max_attempts

run(input: dict)

執行資料分割操作。

參數：

• input：dict，必要
  • 必須包含：
    • data：pd.DataFrame - 要分割的資料集
    • metadata：Schema - 資料詮釋資料
    • exist_train_indices：list[set]（選擇性）- 要避免重疊的現有訓練索引

回傳： 無直接回傳值。使用 get_result() 取得分割結果。

get_result()

取得分割結果。

回傳：

• tuple[dict, dict, list[set]]：分割資料、詮釋資料和訓練索引

set_input(data, metadata, exist_train_indices=None)

設定分割器的輸入資料。

參數：

• data：pd.DataFrame - 要分割的資料集
• metadata：Schema - 資料詮釋資料
• exist_train_indices：list[set]（選擇性）- 現有訓練索引

使用範例

from petsard.adapter import SplitterAdapter

# 設定分割器
adapter = SplitterAdapter({
    "num_samples": 3,
    "train_split_ratio": 0.8,
    "random_state": 42
})

# 設定輸入
adapter.set_input(data=df, metadata=schema)

# 執行分割
adapter.run({
    "data": df,
    "metadata": schema
})

# 取得結果
split_data, metadata_dict, train_indices = adapter.get_result()

注意事項

• 這是內部 API，不建議直接使用
• 建議使用 YAML 配置檔和 Executor
• 樣本編號從 1 開始，而非 0
• 結果會快取直到下次 run() 呼叫