資料約束

資料約束

透過欄位值規則、欄位組合、欄位比例和空值處理策略來約束合成資料。目前的實作支援四種約束：欄位約束、欄位組合、欄位比例和空值群組。

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

---
Loader:
  data:
    filepath: 'benchmark/adult-income.csv'
Preprocessor:
  demo:
    method: 'default'
Synthesizer:
  demo:
    method: 'default'
Postprocessor:
  demo:
    method: 'default'
Constrainer:
  demo:
    nan_groups:
      # 當 workclass 是 NA 時刪除整列
      workclass: 'delete'
      # 當 occupation 是 NA 時，將 income 設為 NA
      occupation:
        'erase':
          - 'income'
      # 當 age 是 NA 且 educational-num 有值時，複製 educational-num 的值到 age
      age:
        'copy':
          'educational-num'
    field_constraints:
      - "age >= 18 & age <= 65"
      - "hours-per-week >= 20 & hours-per-week <= 60"
    field_combinations:
      -
        - education: income
        - Doctorate: ['>50K']
          Masters: ['>50K', '<=50K']
    field_proportions:
      field_proportions:
        # 維持教育程度分布，容忍度 10%
        - education:
            mode: 'all'
            tolerance: 0.1
        # 維持收入分布，容忍度 5%
        - income:
            mode: 'all'
            tolerance: 0.05
        # 維持工作類別缺失值比例，容忍度 3%
        - workclass:
            mode: 'missing'
            tolerance: 0.03
        # 維持教育程度-收入組合比例，容忍度 15%
        # 注意：YAML 格式中尚未支援複雜的元組鍵
        # 此功能將在未來版本中新增
Reporter:
  output:
    method: 'save_data'
    source: 'Constrainer'
...

資料約束方法

資料約束是一種精細控制合成資料品質和一致性的機制，允許使用者透過多層次的規則定義資料的可接受範圍。PETsARD 提供四種主要的約束類型：遺失值群組約束、欄位約束、欄位組合約束和欄位比例約束。這些約束共同確保生成的合成資料不僅在統計特性上忠實於原始資料，更能符合特定的領域邏輯和業務規範。

備註：
所有約束條件都以嚴格的「全部滿足」邏輯進行組合，這意味著一筆資料必須同時滿足所有已定義的約束條件，才會被最終保留。換言之，只有完全符合每一個約束規則的資料紀錄，才能通過篩選
欄位組合規則使用正面表列方式，僅影響指定的值，對於欄位中未被提及的值是不受影響的
在 YAML 使用 NA 值時，請始終使用字串 "pd.NA"
強烈建議使用者在定義約束條件前，先對原始資料進行徹底的邏輯檢查，確保所設計的約束規則準確反映資料的本質特性。

遺失值（NaN）群組約束 (`nan_groups`)

遺失值群組約束允許您以客製化的方式處理缺失資料
- delete：當特定欄位為 NA 時，刪除整列
- erase：當主要欄位為 NA 時，將其他欄位設為 NA
- copy：當主要欄位有值時，將值複製到其他欄位

資料約束與資料前處理的遺失值處理（missing）並不衝突，因為約束機制是在資料合成與資料還原後、進行篩選與驗證。這兩個步驟扮演互補角色：前處理階段處理資料的基礎缺失值問題以幫助合成，而約束機制則進一步確保合成資料符合特定的領域邏輯和統計規範。

Constrainer:
  demo:
    nan_groups:
      # 當 workclass 是 NA 時刪除整列
      workclass: 'delete'

      # 當 occupation 是 NA 時，將 income 設為 NA
      occupation:
        'erase':
          - 'income'

      # 當 age 是 NA 且 educational-num 有值時，複製 educational-num 的值到 age
      age:
        'copy':
          'educational-num'

欄位約束 (`field_constraints`)

欄位約束允許您對單一欄位設定特定的值域規則。
支援的運算子：
- 比較運算子：>, >=, ==, !=, <, <=
- 邏輯運算子：&（且）, |（或）
- 特殊檢查：IS, IS NOT
- 日期函數：DATE() 函數允許在約束中宣告特定日期，並與其他欄位和邏輯運算子靈活組合

目前 PETsARD 的欄位約束實作採用自定義的語法解析器，支援複雜的邏輯運算與欄位比較，能夠處理多層巢狀的布林表達式，但仍存在一些功能限制。若遇到無法滿足的特定約束需求或複雜篩選邏輯，建議從原始資料剔除極端情況，或是直接聯絡 CAPE 團隊，以獲得更客製化的解決方案。

Constrainer:
  demo:
    field_constraints:
      - "age >= 18 & age <= 65"  # 年齡限制在 18-65 歲
      - "hours-per-week >= 20 & hours-per-week <= 60"  # 每週工時限制在 20-60 小時
      - "income == '<=50K' | (age > 50 & hours-per-week < 40)"  # 低收入或年長且工時少
      - "native-country IS NOT 'United-States'"  # 非美國籍
      - "occupation IS pd.NA"  # 職業資訊遺失
      - "education == 'Doctorate' & income == '>50K'"  # 博士學位必須高收入
      - "(race != 'White') == (income == '>50K')"  # 非白人種與高收入的互斥檢查
      - "(marital-status == 'Married-civ-spouse' & hours-per-week > 40) | (marital-status == 'Never-married' & age < 30)" # 複雜的邏輯組合

欄位組合約束 (`field_combinations`)

欄位組合約束允許您定義不同欄位之間的值域關係。
支援的組合類型：
- 單一欄位映射：基於單一欄位的值進行約束
- 多欄位映射：同時考慮多個欄位的值進行更複雜的約束
對於下面的範例：
- 對於 income：只有博士和碩士的收入受到約束，學士的收入不受影響
- 對於 salary：只有美國、加拿大和英國的博士有特定的薪資範圍限制
- 非這三個國家的博士，或不是博士的這三個國家的人，都不會被過濾或影響

在當前的實作中，欄位組合約束採用正面表列方式，僅支援明確列出的值組合。數值欄位可以進行有效值的枚舉，但尚未支援像欄位約束中使用比較運算子進行數值的邏輯判斷。

Constrainer:
  demo:
    field_combinations:
      -
        - {'education': 'income'}
        - {
            'Doctorate': ['>50K'],           # 博士只允許高收入
            'Masters': ['>50K', '<=50K']      # 碩士允許高低收入
          }
      -
        - {('education', 'native-country'): 'salary'}
        - {
            ('Doctorate', 'United-States'): [90000, 100000],    # 美國的博士，薪資範圍
            ('Doctorate', 'Canada'): [85000, 95000],             # 加拿大的博士，薪資範圍
            ('Doctorate', 'United-Kingdom'): [80000, 90000]      # 英國的博士，薪資範圍
          }

欄位比例約束 (`field_proportions`)

欄位比例約束在約束過濾過程中維護原始資料的分布比例
支援的模式：
- all：維護欄位中所有值的分布
- missing：僅維護缺失值的比例
容忍度參數控制與原始比例的可接受偏差（0.0-1.0）
支援單一欄位和欄位組合

目標行數在重新採樣過程中自動決定

Constrainer:
  demo:
    field_proportions:
      field_proportions:
        # 維持教育程度分布，容忍度 10%
        - education:
            mode: 'all'
            tolerance: 0.1
        # 維持收入分布，容忍度 5%
        - income:
            mode: 'all'
            tolerance: 0.05
        # 維持工作類別缺失值比例，容忍度 3%
        - workclass:
            mode: 'missing'
            tolerance: 0.03
        # 維持教育程度-收入組合比例，容忍度 15%
        # 注意：YAML 格式中尚未支援複雜的元組鍵
        # 此功能將在未來版本中新增

欄位比例約束注意事項：
欄位比例約束使用迭代過濾來維護資料分布，同時移除過量資料
約束器保護代表性不足的資料群組，同時過濾掉過度代表的群組
容忍度值應根據可接受的原始比例偏差來設定
欄位組合會創建複雜的分布模式，在過濾過程中會被維護
目標行數由主要約束器在重新採樣期間自動提供

自定義合成機器學習效用

資料約束方法

遺失值（NaN）群組約束 (nan_groups)

欄位約束 (field_constraints)

欄位組合約束 (field_combinations)

欄位比例約束 (field_proportions)

遺失值（NaN）群組約束 (`nan_groups`)

欄位約束 (`field_constraints`)

欄位組合約束 (`field_combinations`)

欄位比例約束 (`field_proportions`)