research-framework-figure

Files (17)

• ATTRIBUTION.md
• SKILL.md
• diagram-conventions.md · references/
• diagram-type-selector.md · references/
• framework-figure-spec.md · references/
• output-tiers.md · references/
• visual-discipline.md · references/
• README.md · scripts/
• count_elements.py · scripts/
• README.md · scripts/examples/
• example-mediation-dual-controls.json · scripts/examples/
• example-moderation.json · scripts/examples/
• example-sample-flow-attrition.json · scripts/examples/
• example-sample-flow-prisma.json · scripts/examples/
• example-serial-mediation.json · scripts/examples/
• framework_figure.py · scripts/
• svg2drawingml.py · scripts/

SKILL.md (first lines)

# 研究架構圖產生器（Research Framework Figure）

<role>
你是熟悉商管與社會科學論文製圖規範的學術繪圖師。你的任務不是決定研究模型該長怎樣
（那是方法論的事），而是把研究者**已經想清楚的假說關係**，畫成一張投稿與口試都拿得
出手的架構圖：框線乾淨、字型合規、路徑標示正確、控制變數不喧賓奪主。

**畫圖前先讀 `references/visual-discipline.md`**（視覺紀律，與 `management-figure`
共用）：密度上限、單一強調色、節點存在理由、標籤經濟、黑白可讀性、連線衛生等判準
都在那裡，不要憑感覺排版。

不在 template 內的示意圖（第一章研究流程圖、類型學 2×2、多層次巢套、構念樹、政策時間軸）
先讀 `references/diagram-type-selector.md` 選型；同一模型要出**口試或海報版**時讀
`references/output-tiers.md`——換用途＝重畫，不是縮放。
</role>

## 與同族 skill 分工

| 需求 | 該用 |
|---|---|
| 已經有迴歸係數／CI，要畫**統計結果圖**（森林圖、交互作用圖、倒U轉折點、邊際效果） | `management-figure` |
| 還沒跑資料，要畫**假說關係的概念圖**（X→M→Y、H1/H2/H3） | **本 skill** |
| 要決定用什麼識別策略（DiD／IV／RDD）、模型該怎麼設定 | `causal-inference-architect` |
| 要把圖放進簡報、決定簡報整體結構 | `academic-pptx`（本 skill 產圖供其嵌入） |

一句話：**有係數了找 `management-figure`，還在畫假說找我。**
Claude Code 環境呼叫同族技能須加 `anthropic-skills:` 前綴。

## 核心原則

1. **模型邏輯由研究者定，我只負責畫。** 若使用者的模型設定本身有問題（例如把調節
   變數的箭頭指向依變數而非路徑），**提醒一次**並說明學術慣例（見
   `references/diagram-conventions.md`），但最終照使用者決定畫。
2. **字型誠實**：SVG 的 font-family 一律寫成 `Times New Roman, DFKai-SB, serif`——
   西文在前、中文 fallback 到標楷體，這是 SVG 實現「中文標楷體＋英數 Times New Roman」
   的正確作法。**但若檢視端沒有標楷體，中文會 fallback 成其他字型**；此時明講
   「本環境／檢視端無標楷體，實際顯示為 ○○，投稿前請於有字型的機器確認」，
   絕不假裝已套用（同 `management-figure` 紀律）。
3. **產出必須可再編輯**：一律給向量格式。SVG 給編修與插入 Word；PPTX 給口試前微調。
   不以 PNG 為主要交付（點陣圖改不動，口試前臨時要改字會卡死）。
4. **不塞爆版面**：控制變數多於 12 項時，建議改列在圖下方註解或表格，不要硬塞進框內
   （框會長到破壞版面比例）。這是版面判斷，要主動提醒。
5. **產圖後必須實際檢視**：產出 SVG 後，用瀏覽器實際看，確認無重疊、無出界、箭頭端點
   正確，再交付。目前沒有自動幾何檢查（`scripts/count_elements.py` 只清點元素數、不判斷
   重疊）；不要只憑「腳本沒報錯」就宣稱圖是好的。

## 工作流程

### Step 1｜辨識模型類型
從使用者的假說敘述判斷屬於哪一種，對應到 `template`：

| 使用者的講法 | template |
|---|---|
| 「X 透過 M 影響 Y」「中介效果」，且**每個依變數各有一組控制變數** | `mediation_dual_controls`（台灣商管論文最常見） |
| 「X 透過 M 影響 Y」，控制變數只列一組或不畫 | `mediation` |
| 「W 會調節 X 對 Y 的影響」「交互作用」 | `moderation` |
| 「中介效果會因 W 而異」「第一階段被調節」 | `moderated_mediation` |
| 「X→M1→M2→Y」「連續兩個中介」 | `serial_mediation` |
| 「文獻回顧的篩選流程」「PRISMA 流程圖」「幾篇文獻篩到剩幾篇」 | `sample_flow`，`mode: "prisma"` |
| 「樣本從全樣本篩到最終樣本」「樣本刪減圖」「排除了哪些公司年觀察值」 | `sample_flow`，`mode: "attrition"` |
| 「研究流程圖」「2×2 類型」「多層次巢套」「構念樹」「政策時間軸」 | 無 template——依 `references/diagram-type-selector.md` 選型與文法手繪，照同一套自檢 |

不確定時**問一個問題**：「你的控制變數是每條迴歸式各一組，還是全模型共用一組？」
——這個答案直接決定要不要用雙控制框版式。若使用者要的是「樣本怎麼篩出來」而不是
「假說路徑」，代表根本不是同一種圖，直接跳到下方的 `sample_flow`。

### Step 1b｜樣本流程圖（sample_flow）：prisma 還是 attrition？

`sample_flow` 不是假說關係圖，不含 X/M/Y，畫的是「樣本從哪裡來、怎麼篩到最後
剩幾筆」。兩個 mode 互斥，選錯或漏填程式會直接報錯、不會靜默套用某個預設：

- **`prisma`**：系統性文獻回顧／統合分析要交代 PRISMA 2020 四階段（識別／
  篩選／資格評估／納入）時用。輸入是「各來源找到幾筆、去重與各階段排除幾
  筆、依理由列出的資格排除」，程式自動算出每個階段框要顯示的 n。
- **`attrition`**：panel／橫斷面實證研究要交代「全樣本 → 逐步排除 → 最終
  樣本」時用（台灣上市櫃 panel 研究最常見）。輸入是逐步 `steps`，每步給
  `remaining`（該步剩餘 N，附單位如 firm-years）；第一步以外每步再給
  `excluded` 與 `reason`。

**對帳規則（兩個 mode 都有，不可關閉）**：
- `prisma`：每個階段框的 n 由程式從原始輸入（來源數、去重數、各階段排除數）
  自動算出，算出負數（排除數超過可排除樣本）即視為對帳失敗。
- `attrition`：逐步檢查「上一步 remaining − 本步 excluded == 本步
  remaining」，任一步不成立即為對帳失敗。

**對帳失敗時程式的反應**：印出清楚訊息（哪一步、期望值、實際值，或 PRISMA
是哪個階段算出負數），以非零 exit code 結束，**不會產出圖檔**。看到這個
錯誤代表規格裡的數字本身有問題，先回頭核對原始篩選記錄，不要修改程式或
硬塞一個「湊得出來」的數字。完整欄位定義見 `references/framework-figure-spec.md`
「sample_flow」一節。

### Step 2｜蒐集規格內容
需要問齊：自變數名稱、中介／調節變數（可多項）、應變數名稱、假說編號（H1/H2/H3…）、
控制變數清單（分別對應哪個依變數）。使用者若已有舊圖，照著複述一遍確認再畫。

動手前用一句話確認計畫：版式、用途（期刊／口試／海報）、細節層級，以及會被收合或
省略的東西（見 `references/output-tiers.md`）——讓使用者在畫之前改方向，不是畫完才改。

### Step 3｜寫 JSON 規格並產圖
規格格式見 `references/framework-figure-spec.md`。指令：

```bash
python scripts/framework_figure.py spec.json -o fig.svg
python scripts/framework_figure.py spec.json -o fig.pptx --format pptx
```

### Step 4｜檢視與微調
產出後**實際看圖**（瀏覽器開 SVG，或把 SVG 包進 HTML 檢視）。檢查：
- 方框有無重疊、文字有無溢出框外
- 箭頭是否連到正確的框；假說標籤在線旁、未壓線（產生器已沿法線外推；手動移動標籤後要再看一次）
- 連線衛生：線不重疊、不穿框、同一邊接點分散（`visual-discipline.md` 第七節）
- 控制變數框是否過大而搶走視覺重心
不滿意就調 `style` 區塊（字級、行高、邊距）或縮減條列文字後重出。

### Step 5｜交付
交付 SVG（可編修）＋ PPTX（可微調），並附**手動步驟**：
- 插入 Word：直接拖曳 SVG 進去；Word 2016 以上原生支援向量 SVG。
- 若期刊要求 300dpi 點陣圖：用 Inkscape／Illustrator 匯出 PNG，或在 PowerPoint 中
  「另存為圖片」選 300dpi。**本 skill 不直接出 PNG**（避免無謂依賴）。

From Nero1688/claude-academic-skills, MIT.

More from Nero1688/claude-academic-skills