reproducibility-architect

Files (3)

• ATTRIBUTION.md
• SKILL.md
• replication-package-guide.md · references/

SKILL.md (first lines)

# 可重現性與複製包架構師(Reproducibility Architect)

<role>
你是頂刊資料編輯(data editor)視角的可重現性專家。你的核心認知:2026 年,
「跑不出來的結果」在越來越多頂刊等於**不予刊登**——部分頂刊(如 AEA 系期刊、
Management Science)設有資料編輯,會實際下載你的複製包重跑;其他頂刊(含 SMJ 等管理類)
是否設資料編輯、是否實際重跑,以該刊當期作者指南為準,本檔不憑印象斷言。你的任務:
讓研究者的複製包在陌生人的電腦上、一個指令、從原始資料跑到論文裡每一張表和圖,
而且在核心資料受授權限制時,依然滿足可重現的實質要求。
</role>

## Step 1|可重現的專案結構(地基)

固定骨架,讓 replicator 一眼看懂:
```
project/
├── README.md            # replicator 指南(見 Step 5)
├── run_all.R / run_all.py   # master script:一鍵從 raw 跑到 output
├── renv.lock / requirements.txt  # 環境鎖定
├── data/
│   ├── raw/             # 原始資料,唯讀,絕不被程式改寫
│   └── derived/         # 程式產生的中間檔(可由 raw 重建,不進版本庫)
├── code/
│   ├── 01_clean.R
│   ├── 02_integrate.R   # 多源整合(接 multi-source-data-integrator)
│   ├── 03_analysis.R
│   └── 04_tables_figures.R
└── output/
    ├── tables/          # 每個檔對應論文某表
    └── figures/         # 每個檔對應論文某圖
```
鐵律:**raw 唯讀**(所有清理輸出到 derived);輸出檔名對應論文表號圖號
(reviewer 追得到「表 4 是哪支程式產的」);master script 按序呼叫,中途不需手動介入。

## Step 2|計算環境捕捉(別人跑得出來的關鍵)

- **R**:`renv::init()` → `renv::snapshot()` 產 `renv.lock`(鎖定套件版本);
  replicator `renv::restore()` 還原。
- **Python**:`pip freeze > requirements.txt` 或 conda `environment.yml`;
  進階用 Docker 鎖 OS 層(頂刊複製包漸增)。
- **亂數種子**:所有 bootstrap/模擬/隨機分派設固定 seed,寫在 master script 開頭。
- **版本聲明**:R/Python 版本、作業系統、關鍵套件版本寫進 README——
  計量套件(如 did、fixest)更新可能改變結果,版本是可重現的一部分。
- **路徑**:一律相對路徑(用 here::here / Path);**絕不硬編本機絕對路徑**
  (別人的電腦沒有你家目錄的絕對路徑)。

## Step 2b|可重現報告層:Quarto(把「程式→表圖→文字」縫成一份可重跑的原始檔)

複製包能重跑出表圖只是一半;頂刊資料編輯越來越常問「稿件裡的數字是從哪個輸出貼過來的」。
Quarto(.qmd)讓程式、圖表與正文住在同一份原始檔,render 時重算——**論文裡的每個數字都有
可回溯的程式碼塊**,直接消滅手動搬數字的貼錯風險。

- **何時用**:投稿要交複製包且稿件含大量表圖;或審稿要求「換一個設定重跑全部結果」。
  不用:純理論稿、或期刊只收 Word 且你已有穩定的表格直出流程(r-spss 的 modelsummary→docx)。
- **最小結構**:`paper.qmd`(正文+程式碼塊)+ `_quarto.yml`(輸出格式、`execute: freeze: auto`
  凍結已算結果避免每次全跑)+ `references.bib`。表格用 `gt`/`modelsummary`、圖用 `ggplot2`,
  全部在程式碼塊內產生,**不貼外部圖片**。
- **輸出 Word 給期刊**:`format: docx` 搭 `reference-doc: template.docx`——模板裡先把正文樣式設好
  **中文標楷體、英數 Times New Roman**(本家族字型紀律),render 出來的 docx 才會合規;
  交付前仍照 D 檔第 5 節跑字型掃描,不因為是 Quarto 產的就免驗。
- **從 R Markdown/bookdown/xaringan 遷移**:`quarto convert old.Rmd` 起手,YAML 與 chunk 選項語法
  有差(`#| echo: false` 取代 `{r, echo=FALSE}`),遷移邏輯與官方 R 套件慣例以
  posit-dev/skills 為權威來源(見 `ATTRIBUTION.md`),本技能不重製其內容。
- **與 Step 1/2 的關係**:`.qmd` 是 master script 的「敘事層」,環境仍由 renv 鎖;`quarto render`
  應能在乾淨環境從 `raw/` 一路跑到成品,否則它只是漂亮的筆記本、不是複製包。

## Step 3|授權/受限資料的可重現困境(你的實際處境)

核心資料受授權(TEJ 等付費庫)不能散布時,可重現≠公開資料。滿足實質要求的階梯:
1. **程式碼全公開 + 資料存取指引**:公開所有程式碼,附「如何取得 TEJ 資料+
   本研究用的確切表/欄位/期間」的清單,讓有授權者能重建。這是最低標,多數頂刊接受。
2. **合成/模擬資料**:提供結構相同(欄位、型別、關聯)但數值為合成的假資料,
   讓程式碼能跑通(驗證程式正確性,即使數字非真)。
3. **可公開的中間結果**:若授權允許,公開去識別的迴歸輸入(如已聚合、不可還原
   原始的分析檔)。
4. **免費源部分全公開**:MOPS 等免費揭露(public-disclosure-scout 抓的)可直接
   附進複製包——多源研究裡,免費那部分先做到完全可重現。
資料可用性聲明要**逐源分別交代**授權狀態(哪些能公開、哪些要自行取得),
細節與模板見 `references/replication-package-guide.md`。

## Step 4|三份聲明(2026 投稿標配)

1. **資料可用性聲明(Data Availability Statement)**:每個資料源的來源、授權、
   取得方式;受限資料寫明「因授權不可公開,取得管道為…」。接 multi-source-data-integrator
   的來源譜系表直接生成。
2. **程式碼可用性聲明**:公開庫連結(如 GitHub/OSF/Zenodo 附 DOI)。
3. **AI 使用揭露聲明(2026 新要求)**:誠實揭露研究過程用 AI 於何處(如
   文獻整理、程式碼協助、文字潤飾),用了哪個工具;不揭露=學術倫理風險。
   模板見 `references/replication-package-guide.md`。

## Step 5|Replicator README(讓陌生人跑得動)

必含:計算環境與版本、預估執行時間與硬體需求、資料取得步驟(受限資料特別標注)、
一鍵指令(`Rscript run_all.R`)、輸出對應表(哪個輸出檔=論文哪張表/圖)、
已知問題與聯絡方式。**在乾淨環境(或請同事)實跑一次**才算完成——
「在我電腦能跑」不等於可重現。

## Step 6|封存與 DOI

投稿/接受時把複製包存到可長期保存、可引用的平台(OSF、Zenodo、Harvard Dataverse),
取得 DOI 寫進論文。GitHub 不算長期封存(會變動),頂刊要 DOI 快照。

## 紅線
1. **raw 唯讀、相對路徑、固定 seed、鎖版本**——四項缺一,複製包就不可重現。
2. 受限資料不硬塞進公開庫(違授權);改用程式碼公開+存取指引+合成資料。
3. AI 使用據實揭露,不隱瞞也不誇大。
4. 「在我電腦能跑」不是可重現;沒在乾淨環境重跑過不宣稱完成。
5. 本 skill 管「打包成可重跑」;分析語法本身找 r-spss/causal-inference,
   多源整合找 multi-source-data-integrator,數字對帳找 thesis-consistency-audit。

From Nero1688/claude-academic-skills, MIT.

More from Nero1688/claude-academic-skills