Data Preparation

Skill: data-preparation

原始數據清洗與整理，輸出 tidy CSV + 清洗報告 (.docx)，並為下游統計分析 skill 提供適配指引。

Metadata

• Description: 對 CSV / Excel / SQL / Hive 導出的原始數據做全流程清洗：列名規範化、類型智能推斷、缺失值填充、寬長表重塑、時間衍生列、數值變換、類別編碼。前後 profile 對比記錄丟棄行數與變更；末尾自動推斷下游統計 skill 並輸出可直接執行的 CLI。
• Version: 1.0.0
• Entrypoint: 兩種模式並列 —— orchestrator.py（一鍵版）或 Claude 逐個調 tools/ 內函數
• Related（下游 skill）:
  • 假設檢驗：advanced-data-analytics
  • 迴歸建模：regression-analytics
  • 因素分析：factor-analysis
  • 多因子 ANOVA：factorial-anova
  • 多變量分析：multivariate-analysis
  • 生存分析：survival-analysis
  • 時間序列：time-series-analysis
  • 文獻檢索：literature-review

觸發時機

• 「這份 CSV 太亂了，幫我整理成能跑 t-test 的格式」
• 「有一堆缺失值，幫我先處理再做迴歸」
• 「數據是寬表，我需要轉成長表跑 ANOVA」
• 「幫我把日期欄拆成年/月/週」
• 「準備一份能餵給 XX skill 的資料」
• 「數據清洗」/「數據整理」/「數據預處理」/「tidy data」

使用模式

模式 A：一鍵 orchestrator（快速走完全流程）

python orchestrator.py --source local --file raw.csv --ops all \
    --output-dir ./outcome-temp/prep \
    --target-schema regression-linear   # 可選，會校驗輸出是否適配下游

--ops 可用值（逗號分隔或關鍵字）：

• all — profile → clean → impute → 最終 profile（默認且最常用）
• minimal — 僅 clean + listwise dropna
• 自定義：profile,clean,impute,reshape,time,transform,encode 任意組合

模式 B：Claude 逐步驟細粒度控制

當用戶需求特殊（如僅想做某一步、或參數需依 profile 結果動態決定），Claude 依 SOP 逐個調 tools：

from tools.data_fetcher import DataFetcher
from tools.profiler import summarize, diff_two
from tools.cleaner import clean_all           # 或分別調 strip / normalize / drop_duplicate ...
from tools.imputer import impute
from tools.word_generator import generate_prep_docx

df = DataFetcher().load(source="local", file_path="raw.csv")
profile_before = summarize(df)

df, clean_log = clean_all(df)
df, impute_log = impute(df, strategy="median")

profile_after = summarize(df)
df.to_csv("cleaned.csv", index=False)

generate_prep_docx(
    output_path="Prep_Report.docx",
    profile_before=profile_before,
    profile_after=profile_after,
    step_logs=[*clean_log, *impute_log],
    source_info={"path": "raw.csv", "backend": "local"},
    downstream_hint={"skill": "regression-analytics", "cli": "python .../orchestrator.py --analysis linear ..."},
)

SOP（Claude 自我遵循）

1. fetch + 初次 profile

   df = DataFetcher().load(source, file_path=...)
   profile_before = summarize(df)   # 展示給用戶：dtype / missing% / n_unique / stats
   

2. 決定操作

   • 若用戶只說「幫我清洗一下」→ 走 orchestrator --ops all
   • 若用戶明確要求某些步驟（「只填缺失值、不做編碼」）→ 逐步驟調
   • 若 profile 顯示極端情況（如某列 100% 缺失、全為常數）→ 主動建議刪除

3. 執行：按順序調 tools。每步都要記錄 log（做了什麼、影響了多少行/列）

4. 二次 profile + 對比

   profile_after = summarize(df)
   diff = diff_two(profile_before, profile_after)
   

5. 推斷下游並提示

   • 從對話中識別下游意圖：
     • 「t-test」/「配對檢驗」/「相關性」 → advanced-data-analytics
     • 「線性/logistic 迴歸」 → regression-analytics
     • 「因素分析」/「量表」 → factor-analysis
     • 「兩因子 ANOVA」/「多因子」 → factorial-anova
     • 「PCA」/「聚類」/「MANOVA」 → multivariate-analysis
     • 「生存分析」/「Kaplan-Meier」/「Cox」 → survival-analysis
     • 「時序」/「ARIMA」/「預測」 → time-series-analysis
   • 寫入 downstream_hint 傳給 word_generator，docx 末尾顯示可直接執行的 CLI

Output Location

預設輸出目錄：./outcome-temp/

• cleaned.csv：清洗後的 tidy data
• Prep_Report.docx：清洗報告（章節：源信息、清洗前 profile、步驟日誌、清洗後 profile、前後對比、下游 CLI 建議）

Tool Reference

Constraints

• Tidy data 定義：每行一個觀測、每列一個變量、每個 cell 一個值
• 列名 normalize 為 snake_case："Age Group" → "age_group"
• 類型推斷順序：datetime → numeric（含 "1,234" / "50%" / "$100"）→ bool（true/false/是/否）→ category（低基數 object）
• 缺失值默認策略：數值列 median，object 列 mode
• one-hot 編碼上限：15 個 unique 值；超過拒絕並建議 label encoding 或分箱
• 數值變換 log 自動處理零負值（log(x + 1)）
• CSV 輸出會丟失部分 dtype（datetime / bool 序列化為字串）—— 這是 CSV 格式固有限制。清洗過程 pandas 內部正確 coerce，下游 skill 從 CSV 讀回時會依 read_csv 重新推斷；若下游 skill 需要嚴格類型，可傳 parse_dates=[...] 或在 Claude 端手動做 pd.to_datetime

Dependencies

• Python 3.10+: pandas>=2.0 numpy python-docx openpyxl sqlalchemy pyhive
• 無 R 依賴

Failure Modes（Claude 遇到時的應對）

• 全列缺失 → 建議直接 drop，不要嘗試 impute
• 類型推斷失敗（如日期格式極不規則）→ 保留為 object 並在報告中警告；用戶可手動指定 dtype
• 寬長表重塑後仍不是 tidy（如某個 cell 含 list）→ 建議用戶檢查原始數據，該 skill 不做嵌套結構展開
• --target-schema 校驗失敗 → docx 中列出缺少的欄位契約，並給出補救建議（如「請重塑為長表」）