reproducibility-architect

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

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 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。