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 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/ 一路跑到成品,否則它只是漂亮的筆記本、不是複製包。