Merge pull request #5 from cyc00518/feature/delta-analysis

README.md

@@ -14,6 +14,7 @@
   <em>圖：gpt-oss-120b 在 MMLU 部分子集上的表現成績預覽</em>
 </p>
 
+### 📈 原始成績圖表
 - 支援上傳多個 **Twinkle Eval 檔案**（`json` / `jsonl`）。
 - 自動解析評估結果，抽取：
   - `dataset`
@@ -29,6 +30,21 @@
   - 指標可切換為原始值或 0–100 比例。
 - 支援 **CSV 匯出**（下載分頁結果）。
 
+### ⚖️ 差距分析（Baseline Δ）圖表
+- **基準模型比較**：選擇一個基準模型（Baseline）與多個候選模型（Candidates）進行差距分析。
+- **差距計算**：自動計算 Δ = Candidate 分數 − Baseline 分數。
+- **多種排序模式**：
+  - `|Δ| 由大到小`：依絕對差距排序，找出差異最大的項目。
+  - `Δ 由大到小（提升最多）`：找出候選模型相對基準提升最多的類別。
+  - `Δ 由小到大（下降最多）`：找出候選模型相對基準下降最多的類別。
+  - `依類別名稱`：依字母順序排列。
+- **差距門檻過濾**：可設定最小差距門檻，只顯示 |Δ| ≥ 門檻的類別。
+- **視覺化呈現**：
+  - **per-category 排行圖**：每個候選模型獨立分面，以水平長條圖顯示各類別的差距。
+  - **per-candidate 總結**：統計各候選模型的 Mean Δ、Median Δ、Win/Lose/Tie 次數及覆蓋率。
+  - **Top/Bottom-N 清單**：顯示每個候選模型提升最多與下降最多的 N 個類別。
+- **CSV 匯出**：支援下載差距排行、總覽表、Top/Bottom-N 清單。
+
 ## 🚀 使用方式
 
 ### 1. 安裝環境
@@ -43,11 +59,20 @@ streamlit run app.py
 ```
 
 ### 3. 操作流程
+
+#### 原始成績
 1. 在左側 Sidebar 上傳一個或多個 **Twinkle Eval 檔案**。
 2. 選擇要查看的資料集。
 3. 設定排序方式、分頁大小、顯示比例（0–1 或 0–100）。
 4. 查看圖表與資料表，並可下載 CSV。
 
+#### 差距分析（Baseline Δ）
+1. 在「差距分析設定」中選擇排序方式與差距門檻。
+2. 在差距分析區塊選擇基準模型（Baseline）。
+3. 選擇一個或多個候選模型（Candidates）進行比較。
+4. 查看差距排行圖表與統計總結。
+5. 下載差距分析結果（CSV 格式）。
+
 ## 📂 檔案格式要求
 每份 json / jsonl 檔案需符合 Twinkle Eval 格式，至少包含以下欄位：
 
@@ -97,9 +122,16 @@ streamlit run app.py
 
 ## 📊 輸出範例
 
+### 原始成績圖表
 - **圖表**：顯示各模型在不同類別的 accuracy_mean 比較。
 - **表格**：Pivot Table，行為類別，列為模型，值為 accuracy。
 - **下載**：每頁結果可匯出成 CSV。
 
+### 差距分析圖表
+- **差距排行圖**：水平長條圖顯示各類別相對於基準的差距（Δ），每個候選模型獨立分面。
+- **總覽表**：顯示各候選模型的平均差距、中位數差距、勝敗次數與覆蓋率。
+- **Top/Bottom-N 清單**：展開式面板顯示每個候選模型提升與下降最多的類別詳細資訊。
+- **下載**：支援匯出差距排行、總覽表、Top/Bottom-N 清單（CSV 格式）。
+
 ## 📄 License
 MIT

app.py

@@ -106,12 +106,23 @@ with st.sidebar:
     df_all, meta_all = load_all(files)
     normalize_0_100 = st.checkbox("以 0–100 顯示", value=False)
     page_size = st.selectbox("每張圖顯示幾個類別", [10, 20, 30, 50, 100], index=1)
-    sort_mode = st.selectbox("排序方式", ["依整體平均由高到低", "依整體平均由低到高", "依字母排序"])
+    sort_mode = st.selectbox("排序方式（原始成績）", ["依整體平均由高到低", "依整體平均由低到高", "依字母排序"])
+
+    # === Baseline Δ 圖表的控制 ===
+    st.markdown("---")
+    st.subheader("差距分析設定（Baseline Δ）")
+    options = ["|Δ| 由大到小", "Δ 由大到小（提升最多）", "Δ 由小到大（下降最多）", "依類別名稱"]
+    default = "Δ 由大到小（提升最多）"
+    delta_sort_mode = st.selectbox("差距排序方式（per-category）", options, index=options.index(default), key="delta_sort_mode")
+
+    abs_threshold = st.number_input("只顯示 |Δ| ≥ 門檻（可選）", min_value=0.0, value=0.0, step=0.1)
+    st.caption("Δ = Candidate 分數 − Baseline 分數；建議以 0–100 模式計算更直觀。")
 
 if df_all.empty:
     st.info("請上傳 Twinkle Eval 檔案")
     st.stop()
 
+# ----------------- 原始成績-----------------
 all_datasets = sorted(df_all["dataset"].unique().tolist())
 selected_dataset = st.selectbox("選擇資料集", options=all_datasets)
 work = df_all[df_all["dataset"] == selected_dataset].copy()
@@ -132,6 +143,7 @@ work["category"] = pd.Categorical(work["category"], categories=cat_order, ordere
 n = len(cat_order)
 pages = int(np.ceil(n / page_size))
 
+st.markdown("## 📈 原始成績（各模型 × 類別）")
 for p in range(pages):
     start, end = p * page_size, min((p + 1) * page_size, n)
     subset_cats = cat_order[start:end]
@@ -153,3 +165,253 @@ for p in range(pages):
         file_name=f"twinkle_{selected_dataset}_{start+1}_{end}.csv",
         mime="text/csv"
     )
+
+# ----------------- 差距（Baseline Δ）分析 -----------------
+
+st.markdown("---")
+st.markdown("## ⚖️ 差距分析：Baseline vs. Candidates（Δ = Candidate − Baseline）")
+
+# 使用與上方相同的資料集
+dataset_for_delta = selected_dataset
+
+df_delta_scope = df_all[df_all["dataset"] == dataset_for_delta].copy()
+if df_delta_scope.empty:
+    st.warning(f"在資料集 **{dataset_for_delta}** 找不到資料，請確認上傳的 JSON 含此資料集名稱。")
+    try:
+        st.stop()
+    except Exception:
+        raise SystemExit
+
+# 統一與上方尺度（建議用 0–100 再做差）
+score_col = "score_0100"
+df_delta_scope[score_col] = df_delta_scope["accuracy_mean"] * (100.0 if normalize_0_100 else 1.0)
+
+# 手動指定 Baseline 與 Candidates
+all_sources_in_scope = sorted(df_delta_scope["source_label"].unique().tolist())
+col1, col2 = st.columns([1, 2])
+with col1:
+    baseline = st.selectbox("選擇基準模型（Baseline）", options=all_sources_in_scope)
+with col2:
+    default_candidates = [s for s in all_sources_in_scope if s != baseline]
+    candidates = st.multiselect("選擇要比較的候選模型（Candidates）", options=all_sources_in_scope, default=default_candidates)
+
+if not candidates:
+    st.info("請至少選擇一個 Candidate。")
+    try:
+        st.stop()
+    except Exception:
+        raise SystemExit
+
+# 建立寬表（index=category；已固定 dataset_for_delta）
+wide = df_delta_scope.pivot_table(index="category", columns="source_label", values=score_col, aggfunc="mean")
+
+# 只比較 baseline 與 candidates 的交集列
+valid_candidates = [c for c in candidates if c in wide.columns]
+if baseline not in wide.columns:
+    st.error("Baseline 在此資料集沒有任何分數可比。請換一個 Baseline 或資料集。")
+    try:
+        st.stop()
+    except Exception:
+        raise SystemExit
+if not valid_candidates:
+    st.error("選取的 Candidates 在此資料集沒有任何分數可比。請換一組 Candidates 或資料集。")
+    try:
+        st.stop()
+    except Exception:
+        raise SystemExit
+
+# 計算 Δ 長表（保留 baseline/candidate 原始分數）
+delta_rows = []
+for c in valid_candidates:
+    pair = wide[[baseline, c]].dropna()  # 僅兩者皆有分數的類別
+    if pair.empty:
+        continue
+    for cat, row in pair.iterrows():
+        b = float(row[baseline])
+        s = float(row[c])
+        delta = s - b
+        if abs(delta) < abs_threshold:  # 門檻過濾
+            continue
+        delta_rows.append({
+            "dataset": dataset_for_delta,
+            "category": cat,
+            "baseline": baseline,
+            "candidate": c,
+            "baseline_score": b,
+            "candidate_score": s,
+            "delta": delta
+        })
+
+delta_df = pd.DataFrame(delta_rows)
+if delta_df.empty:
+    st.warning("沒有符合條件的可比較類別（可能因缺漏或門檻過高）。")
+    try:
+        st.stop()
+    except Exception:
+        raise SystemExit
+
+# 差距排序
+if delta_sort_mode == "|��| 由大到小":
+    delta_df = delta_df.sort_values("delta", key=lambda s: s.abs(), ascending=False)
+elif delta_sort_mode == "Δ 由大到小（提升最多）":
+    delta_df = delta_df.sort_values("delta", ascending=False)
+elif delta_sort_mode == "Δ 由小到大（下降最多）":
+    delta_df = delta_df.sort_values("delta", ascending=True)
+else:
+    delta_df = delta_df.sort_values("category", ascending=True)
+
+# 圖表（Δ 不分頁，一次顯示全部類別）
+tab1, tab2 = st.tabs(["📊 差距排行（per-category）", "📜 模型總結（per-candidate）"])
+
+with tab1:
+    sub = delta_df.copy()
+
+    # === 先在 Pandas 內算出每個 candidate 的排序名次 ===
+    if delta_sort_mode == "Δ 由大到小（提升最多）":
+        sub["rank_in_candidate"] = sub.groupby("candidate")["delta"].rank(ascending=False, method="first")
+        table_sort = lambda df: df.sort_values(["candidate", "rank_in_candidate"], ascending=[True, True])
+        y_sort = alt.SortField("rank_in_candidate", order="ascending")
+        resolve_y = "independent"
+
+    elif delta_sort_mode == "Δ 由小到大（下降最多）":
+        sub["rank_in_candidate"] = sub.groupby("candidate")["delta"].rank(ascending=True, method="first")
+        table_sort = lambda df: df.sort_values(["candidate", "rank_in_candidate"], ascending=[True, True])
+        y_sort = alt.SortField("rank_in_candidate", order="ascending")
+        resolve_y = "independent"
+
+    elif delta_sort_mode == "|Δ| 由大到小":
+        sub["abs_delta"] = sub["delta"].abs()
+        sub["rank_in_candidate"] = sub.groupby("candidate")["abs_delta"].rank(ascending=False, method="first")
+        table_sort = lambda df: df.sort_values(["candidate", "rank_in_candidate"], ascending=[True, True])
+        y_sort = alt.SortField("rank_in_candidate", order="ascending")
+        resolve_y = "independent"
+
+    else:  # 依類別名稱（字母序），共用排序
+        # 不用 rank，直接字母序
+        table_sort = lambda df: df.sort_values(["category", "candidate"], ascending=[True, True])
+        y_sort = alt.SortField("category", order="ascending")
+        resolve_y = "shared"
+
+    st.subheader(f"🔎 {dataset_for_delta}｜Δ 排行（全部 {sub['category'].nunique()} 類別）")
+
+    chart_height = 25 * max(1, sub["category"].nunique())
+
+    base = alt.Chart(sub).encode(
+        y=alt.Y("category:N", sort=y_sort, title="Category"),
+        x=alt.X("delta:Q", title="Δ = Candidate − Baseline"),
+        color=alt.Color("candidate:N", title="Candidate"),
+        tooltip=[
+            alt.Tooltip("category:N", title="Category"),
+            alt.Tooltip("candidate:N", title="Candidate"),
+            alt.Tooltip("baseline:N", title="Baseline"),
+            alt.Tooltip("baseline_score:Q", title="Baseline 分數", format=".3f"),
+            alt.Tooltip("candidate_score:Q", title="Candidate 分數", format=".3f"),
+            alt.Tooltip("delta:Q", title="Δ", format=".3f"),
+        ],
+    )
+
+    chart = (
+        base.mark_bar()
+        .encode(row=alt.Row("candidate:N", header=alt.Header(title=None)))
+        .properties(height=chart_height)
+        .resolve_scale(y=resolve_y)  # 各 candidate 分面各自排序或共用
+    )
+    st.altair_chart(chart, use_container_width=True)
+
+    # 表格：依 rank_in_candidate 排序，與圖一致
+    table = table_sort(sub)[["category", "candidate", "baseline_score", "candidate_score", "delta"]]
+    st.dataframe(table, use_container_width=True)
+
+    st.download_button(
+        label="下載 Δ 排行 CSV（全部類別）",
+        data=table.to_csv(index=False).encode("utf-8"),
+        file_name=f"delta_{dataset_for_delta}_ALL.csv",
+        mime="text/csv",
+    )
+
+
+
+with tab2:
+    # per-candidate 總結：mean/median Δ、win/lose/tie、覆蓋率、Top/Bottom-N
+    summaries = []
+    top_k = st.number_input("Top/Bottom-N（顯示每個 Candidate 的最大/最小差距分類）", min_value=1, value=10, step=1)
+
+    for c in valid_candidates:
+        pair = wide[[baseline, c]].dropna()
+        if pair.empty:
+            continue
+        deltas = pair[c] - pair[baseline]
+        m = float(np.mean(deltas))
+        med = float(np.median(deltas))
+        win = int((deltas > 0).sum())
+        lose = int((deltas < 0).sum())
+        tie = int((deltas == 0).sum())
+        coverage = f"{len(deltas)}/{wide.shape[0]}"  # 有共同分數的類別數 / 全部類別數
+
+        # 取 Top/Bottom-N 類別（按 Δ）
+        top_rows = (pair.assign(delta=deltas)
+                    .sort_values("delta", ascending=False)
+                    .head(top_k)
+                    .reset_index()[["category", baseline, c, "delta"]])
+        bottom_rows = (pair.assign(delta=deltas)
+                       .sort_values("delta", ascending=True)
+                       .head(top_k)
+                       .reset_index()[["category", baseline, c, "delta"]])
+
+        summaries.append({
+            "candidate": c,
+            "mean_delta": m,
+            "median_delta": med,
+            "win": win,
+            "lose": lose,
+            "tie": tie,
+            "coverage": coverage,
+            "top_list": top_rows,
+            "bottom_list": bottom_rows
+        })
+
+    if not summaries:
+        st.warning("沒有可用的 per-candidate 總結（可能都沒有交集）。")
+    else:
+        # 概覽表
+        overview = pd.DataFrame([{
+            "Candidate": s["candidate"],
+            "Mean Δ": s["mean_delta"],
+            "Median Δ": s["median_delta"],
+            "Win": s["win"],
+            "Lose": s["lose"],
+            "Tie": s["tie"],
+            "Coverage (交集/總類別)": s["coverage"],
+        } for s in summaries]).sort_values("Mean Δ", ascending=False)
+        st.markdown("### 總覽（與 Baseline 成對比較）")
+        st.dataframe(overview, use_container_width=True)
+        st.download_button(
+            label="下載 per-candidate 總覽 CSV",
+            data=overview.to_csv(index=False).encode("utf-8"),
+            file_name=f"delta_overview_{dataset_for_delta}.csv",
+            mime="text/csv"
+        )
+
+        # 逐 Candidate 顯示 Top/Bottom-N 清單（可收合）
+        st.markdown("### 各 Candidate 的差距清單（Top/Bottom-N）")
+        for s in summaries:
+            with st.expander(f"🔸 {s['candidate']}"):
+                st.write("**Top-N（提升最多）**")
+                top_tbl = s["top_list"].rename(columns={baseline: "baseline_score", s["candidate"]: "candidate_score"})
+                st.dataframe(top_tbl, use_container_width=True)
+                st.download_button(
+                    label=f"下載 {s['candidate']} Top-N",
+                    data=top_tbl.to_csv(index=False).encode("utf-8"),
+                    file_name=f"delta_top_{dataset_for_delta}_{s['candidate']}.csv",
+                    mime="text/csv"
+                )
+
+                st.write("**Bottom-N（下降最多）**")
+                bottom_tbl = s["bottom_list"].rename(columns={baseline: "baseline_score", s["candidate"]: "candidate_score"})
+                st.dataframe(bottom_tbl, use_container_width=True)
+                st.download_button(
+                    label=f"下載 {s['candidate']} Bottom-N",
+                    data=bottom_tbl.to_csv(index=False).encode("utf-8"),
+                    file_name=f"delta_bottom_{dataset_for_delta}_{s['candidate']}.csv",
+                    mime="text/csv"
+                )