Config API

Config 是 PETsARD 的內部配置管理類別，負責解析配置字典並建立模組執行序列。

ℹ️

僅供內部使用：Config 主要由 Executor 內部使用。使用者應透過 Executor 與 PETsARD 互動，而非直接使用 Config。

類別架構

classDiagram
    class Config {
        Queue config
        Queue module_flow
        Queue expt_flow
        list sequence
        dict yaml
        __init__(config)
    }

    class BaseAdapter {
        <<abstract>>
        dict config
        run()
        set_input(status)
        get_result()
    }

    class LoaderAdapter {
        run()
    }

    class SynthesizerAdapter {
        run()
    }

    class EvaluatorAdapter {
        run()
    }

    Config ..> BaseAdapter : creates
    BaseAdapter <|-- LoaderAdapter
    BaseAdapter <|-- SynthesizerAdapter
    BaseAdapter <|-- EvaluatorAdapter

    %% 樣式標示
    style Config fill:#e6f3ff,stroke:#4a90e2,stroke-width:3px
    style BaseAdapter fill:#fff2e6,stroke:#ff9800,stroke-width:2px
    style LoaderAdapter fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style SynthesizerAdapter fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style EvaluatorAdapter fill:#f3e6ff,stroke:#9966cc,stroke-width:2px

圖例說明：
藍色框：主要類別
橘色框：抽象基類
淺紫框：具體 Adapter 實作
..>：依賴關係 (dependency)
<|--：繼承關係 (inheritance)

基本使用

from petsard.config import Config

# 從配置字典建立 Config
config_dict = {
    "Loader": {
        "load_data": {
            "filepath": "data.csv"
        }
    },
    "Synthesizer": {
        "generate": {
            "method": "sdv",
            "model": "GaussianCopula"
        }
    }
}

config = Config(config_dict)

# Config 通常由 Executor 內部使用
from petsard import Executor
exec = Executor('config.yaml')  # Executor 內部會建立 Config

建構函式

語法

Config(config: dict)

參數

參數	類型	必要性	說明
`config`	`dict`	必要	包含所有模組配置的配置字典

返回值

返回已解析配置的 Config 實例。

配置結構

Config 期望的字典結構：

{
    "ModuleName": {
        "experiment_name": {
            "parameter1": "value1",
            "parameter2": "value2"
        }
    }
}

範例

config_dict = {
    "Loader": {
        "load_data": {"filepath": "data.csv"}
    },
    "Synthesizer": {
        "method_a": {"method": "sdv", "model": "GaussianCopula"},
        "method_b": {"method": "sdv", "model": "CTGAN"}
    }
}

核心屬性

屬性	類型	說明
`config`	`queue.Queue`	實例化的 Adapter 佇列
`module_flow`	`queue.Queue`	模組名稱佇列
`expt_flow`	`queue.Queue`	實驗名稱佇列
`sequence`	`list`	模組執行順序
`yaml`	`dict`	處理後的配置字典

自動處理機制

1. 模組排序

Config 會自動按照正確順序安排模組：

Loader → Preprocessor → Splitter → Synthesizer →
Postprocessor → Constrainer → Evaluator → Reporter

2. Splitter 展開

當 Splitter 配置包含 num_samples > 1 時，Config 會自動展開：

# 輸入
"Splitter": {
    "split_data": {
        "train_split_ratio": 0.8,
        "num_samples": 3
    }
}

# 自動展開為
"Splitter": {
    "split_data_[3-1]": {"train_split_ratio": 0.8, "num_samples": 1},
    "split_data_[3-2]": {"train_split_ratio": 0.8, "num_samples": 1},
    "split_data_[3-3]": {"train_split_ratio": 0.8, "num_samples": 1}
}

3. 笛卡爾積生成

多實驗配置會產生所有組合：

config_dict = {
    "Loader": {
        "load_v1": {...},
        "load_v2": {...}
    },
    "Synthesizer": {
        "method_a": {...},
        "method_b": {...}
    }
}

# 產生 4 個執行路徑：
# load_v1 → method_a
# load_v1 → method_b
# load_v2 → method_a
# load_v2 → method_b

配置驗證

Config 會驗證實驗名稱，確保不使用保留模式：

# ✓ 有效的實驗名稱
"experiment_name"
"load_data"
"method_v2"

# ✗ 無效的實驗名稱（保留模式）
"experiment_[1]"    # 會拋出 ConfigError
"load_data_[test]"  # 會拋出 ConfigError

與 Executor 整合

Config 通常透過 Executor 使用：

from petsard import Executor

# Executor 內部會：
# 1. 載入 YAML 檔案
# 2. 建立 Config 實例
# 3. 使用 Config 建立執行佇列
exec = Executor('config.yaml')
exec.run()

注意事項

內部使用：Config 主要供 Executor 內部使用
建議作法：使用 YAML 配置檔與 Executor，而非直接使用 Config
命名限制：實驗名稱不能使用 _[xxx] 模式（保留給系統使用）
自動處理：Splitter 多樣本配置會自動展開
執行順序：模組順序由 Config 自動決定
記憶體使用：大量實驗組合會佔用較多記憶體