文件
PETsARD YAML
Describer YAML

Describer YAML

Describer 模組的 YAML 設定檔案格式。提供資料集的統計描述與比較功能。

使用範例

請點擊下方按鈕在 Colab 中執行範例：

Open In Colab

單一資料集描述 (describe 模式) 

---
Synthesizer:
  external_data:
    method: custom_data
    filepath: benchmark://adult-income_syn
    schema: benchmark://adult-income_schema
Describer:
  describer-describe:
    method: default    # 自動判斷為 describe（因為只有一個 source）
    source: Synthesizer
...

資料集比較 (compare 模式) 

---
Splitter:
  external_split:
    method: custom_data
    filepath:
      ori: benchmark://adult-income_ori
      control: benchmark://adult-income_control
    schema:
      ori: benchmark://adult-income_schema
      control: benchmark://adult-income_schema
Synthesizer:
  external_data:
    method: custom_data
    filepath: benchmark://adult-income_syn
    schema: benchmark://adult-income_schema
Describer:
  describer-compare:
    method: default         # 自動判斷為 compare（因為有兩個 source）
    source:
      base: Splitter.train  # 使用 Splitter 的 train 輸出作為基準
      target: Synthesizer   # 比較 Synthesizer 的輸出
...

自訂比較方法 

---
Loader:
  load_original:
    filepath: benchmark://adult-income_ori
    schema: benchmark://adult-income_schema
Synthesizer:
  generate_synthetic:
    method: custom_data
    filepath: benchmark://adult-income
    schema: benchmark://adult-income_schema
Describer:
  custom_comparison:
    method: compare           # 明確指定 compare 方法
    source:
      base: Loader
      target: Synthesizer
    stats_method:             # 自訂統計方法
      - mean
      - std
      - nunique
      - jsdivergence
    compare_method: diff      # 使用差值而非百分比變化
    aggregated_method: mean
    summary_method: mean
...

主要參數

  • method (string, 選用)

    • 評估方法
    • default：根據 source 數量自動決定（1個→describe，2個→compare）
    • describe：單一資料集統計描述
    • compare：資料集比較（整合 Stats 功能）
    • 預設值：default

  • source (string | dict, 必要)

    • 指定資料來源
    • 單一來源：適用於 describe 方法
    • 兩個來源：適用於 compare 方法（必須使用字典格式）
    • 可用值：Loader, Splitter, Preprocessor, Synthesizer, Postprocessor, Constrainer

支援的方法

方法說明資料需求輸出內容
default自動判斷模式根據 source 數量決定根據判斷結果
describe單一資料集統計描述一個資料來源global、columnwise、pairwise
compare資料集比較分析兩個資料來源global（含 Score）、columnwise

參數詳細說明

通用參數

參數類型必要/選用預設值說明範例
methodstring選用default評估方法describe, compare
sourcestring|dict必要無資料來源模組見下方說明

Source 參數格式

1. 單一來源（describe 方法） 

source: Loader

2. 字典格式（compare 方法 - 必須使用） 

source:
  base: Splitter.train    # 明確指定基準資料
  target: Synthesizer     # 明確指定比較目標

註：向後相容支援 ori/syn 鍵名，但建議使用 base/target。

Compare 方法專用參數

參數類型預設值說明可選值
stats_methodlist全部方法統計方法列表mean, std, median, min, max, nunique, jsdivergence
compare_methodstringpct_change比較方法pct_change, diff
aggregated_methodstringmean聚合方法mean
summary_methodstringmean總結方法mean

統計方法說明

方法適用資料類型說明執行粒度
mean數值型平均值columnwise
std數值型標準差columnwise
median數值型中位數columnwise
min數值型最小值columnwise
max數值型最大值columnwise
nunique分類型唯一值數量columnwise
jsdivergence分類型JS 散度percolumn

比較方法說明

方法計算公式適用場景
pct_change(target - base) / abs(base)檢視相對變化幅度
difftarget - base檢視絕對變化量

執行說明

  • source 參數為必要參數，必須明確指定資料來源
  • method 參數可省略，預設為 default（自動判斷）
  • 統計方法會根據資料類型自動篩選適用的計算

注意事項

  • source 為必要參數：必須明確指定要分析的資料來源
  • compare 模式必須使用字典格式：需明確指定 base 和 target 鍵
  • 向後相容性：仍支援 ori/syn 參數名稱，但建議使用 base/target
  • compare 方法整合了原 Stats 評估器功能
  • 不適用的統計方法會返回 NaN
  • 建議數值資料使用 mean, std, median, min, max
  • 建議分類資料使用 nunique, jsdivergence

相關說明

  • 資料來源：可使用任何產生資料的模組作為來源，如 Loader、Splitter、Synthesizer 等
  • Module.key 格式：當模組有多個輸出時，使用點號語法精確指定，如 Splitter.train
  • 統計方法：根據資料類型自動判斷適用的統計方法