Community影像github.com

research-figure-builder

將科研數據表製成可投稿圖件:聲明式清洗與行級血緣、按數據和研究目的選圖、R/ggplot2 統計繪圖、PDF/600dpi PNG/可編輯 SVG 三格式導出,並用獨立數值複核、easyplot 元數據/色板審計、真實渲染邊距和兩次全鏈重跑驗收。

research-figure-builder 是什麼?

此技能旨在從科研數據表生成符合學術投稿標準的圖件,並確保每個數據元素均可追溯至原始來源,且提供完整的可重複執行證據。它專注於處理科研數據可視化的核心挑戰:根據數據特徵與研究目的自動選擇合適的圖表類型(如比較用柱狀圖加誤差線、相關用散點圖加擬合線、分佈用直方圖等),並支援嚴格的行級數據清洗與血緣追蹤。技能支援多種輸入資料格式(CSV、TSV、JSON、SQLite),並可透過結構化工單或自然語言描述指定圖表需求。其輸出包含 PDF、600 dpi PNG 及可編輯 SVG 三種格式,並附帶獨立的數值複核、佈局自適應記錄及端到端的可重複性驗證(SHA-256 哈希比較)。關鍵功能包括:自動處理缺失值與異常值、根據樣本數調整統計摘要呈現方式(如 n<3 僅繪點,n≥3 繪製點與誤差線)、自適應圖面佈局以避免標籤重疊、以及強健的異常處理機制(如依賴缺失時保存可復用材料)。此技能非常適合需要將數據分析結果轉化為可投稿圖件、且對數據透明性與結果可重複性有嚴格要求的科研人員與數據分析師。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Hao-IANWY/research-figure-builder/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

科研數據可視化(research-figure-builder)

目標不是「畫出一張圖」,而是讓圖上每個數據元素都能回到源數據,並讓別人用隨附快照和腳本重跑出同一交付件。

何時使用

  • 輸入科研數據表與出圖任務,需要真實圖件、統計口徑、圖註和複現證據;
  • 需要比較、相關、趨勢、分佈、構成、分類計數或相關熱圖;
  • 需要指定期刊欄寬、畫布、DPI、字體或導出格式;
  • 需要識別缺失、非有限數、重複、小樣本和類別過多,而不是靜默刪數據。

不用於實驗設計、統計方法創新、圖像後期美化或交互式儀表盤。顯著性標記只接受已提供且帶統計方法/校正口徑的結果,不自動生成星號。

輸入

  1. 讀取實際 /input/case.json、/input/task.md 和案例材料,不根據數據集名稱猜任務。

  2. 數據支援內聯 dataset.rows、CSV、TSV、JSON 和唯讀 SQLite;相對路徑按 case 所在目錄解析,case 被遷移到 /app/work 等目錄時自動回退查找各級祖先目錄下的 input/、當前目錄與 /input(Harbor 佈局);全部找不到時報出完整嘗試路徑,不猜測數據內容。

  3. 出圖工單 figure_requests[] 支援:

    • figure_id、purpose、chart_hint/chart_type;
    • x、y、group、variables、unit_id/replicate_unit、label;
    • x_label、y_label、x_unit、unit/y_unit、title、panel;
    • error_bar=sd|se|ci95|none、fit_group、significance;
    • venue、width_mm、height_mm、dpi、format/formats。
  4. data_dictionary 的 label/type/unit/missing_values/sentinels 會進入標籤、類型和清洗規則。數值型 -999 等哨兵必須顯式聲明,不能全域猜測。數據字典的短 label 優先作為熱圖等坐標軸顯示名,原始列名保留在血緣與 analysis。

  5. 若案例只有自然語言任務而缺 figure_requests,先由 Agent 在 /app/work 生成一個保留原 case_id、數據引用和 output_contract 的工作案例,只補充結構化工單;相對數據路徑無需改寫(按第 2 條回退解析),在證據中記錄該轉換,不偽造數據。工單映射示例(保持任務原文語義,不添加任務沒提的結論):

    任務說「比較三種基因型表達量差異,誤差線用標準誤」→

    {"figure_id":"F1","purpose":"comparison","x":"基因型","y":"表達量","error_bar":"se",
     "x_label":"基因型","y_label":"表達量","title":"三種基因型表達量比較"}
    

    選圖理由寫進工單轉化記錄:purpose=comparison 且顯式誤差線 → bar_with_error_points(均值柱+全部原始點);拒絕圓餅圖(無序分類不做角度編碼)。

    任務說「花瓣長寬的關聯按物種分色,給擬合與置信帶」→

    {"figure_id":"F2","purpose":"correlation","x":"petal_length_cm","y":"petal_width_cm",
     "group":"species","fit_group":true,"x_label":"花瓣長度","y_label":"花瓣寬度"}
    

    拒絕折線(無序觀測不連線);fit_group=true 才分組擬合。

    任務說「探索性看全部變量相關結構」→ {"figure_id":"F3","purpose":"correlation","chart_hint":"heatmap"}(變量未列則由數據字典連續列自動識別,並記錄該決定)。

執行

生產環境直接運行:

python3 -B /skills/weekly-skill/scripts/pipeline.py \
  --case /input/case.json --task /input/task.md --out /app/output
python3 -B /skills/weekly-skill/scripts/validate.py \
  --case /input/case.json --result /app/output/result.json
python3 -B /skills/weekly-skill/scripts/validate_figures.py \
  --result /app/output/result.json

依賴:Rscript + ggplot2 + ggprism + svglite + jsonlite + systemfonts;Python 審計使用 Pillow 與 pypdf。缺依賴時保存快照、運行計劃和腳本,狀態標為部分完成並列出缺失項。若容器缺 R 包且有網路,可先冷啟動安裝再復跑:

Rscript -e 'install.packages(c("ggplot2","ggprism","svglite","jsonlite","systemfonts"), repos="https://cloud.r-project.org")'
python3 -m pip install --user Pillow pypdf

安裝失敗不阻塞:依賴探測結果寫入 dependencies.json,交付材料按部分完成口徑如實降級。

流程

1. 凍結輸入與契約

保存 source_data.tsv、原始來源/哈希、run_plan.json、清洗規則和依賴版本。動態綁定案例 output_contract,未產出的字段明確進入 status.unmet。

2. Shell/Python 只整備數據

data_prep.sh 調用 scripts/prepare_data.py,生成乾淨 TSV,不畫圖:

  • 默認缺失標記:空值、NA、N/A、NaN、null、None、.;
  • 非有限數和不可解析數值排除並記錄原行號與原因;
  • 完全重複行默認保留並報告,只有顯式 drop_duplicates=true 才刪除;
  • 類別不取前 N 個;類別較多時保留全部並調整佈局;
  • 輸出 cleaned_data.tsv、figure_N.tsv、figure_N_lineage.json、data_quality.json。

3. R/ggplot2 統計與繪圖

plot.R 唯讀 TSV 與運行計劃,調用 theme.R:

路由實際表達
bar_with_error_points原始 jitter 點 + 均值柱 + 顯式 SD/SE/95% CI
comparison_auton<3 只畫點;3–9 畫點與聲明的摘要;每組 n≥10 用箱線 + jitter
boxplot_points / violin_points顯式箱線/小提琴 + jitter;每組 n<3 時降級為點圖並記錄
scatter_with_fit散點 + 總體 OLS 與 95% 置信帶;fit_group=true 才分組擬合;顏色 + 形狀雙編碼
line_series按真實時間/有序數值排序,顏色 + 線型;重複點給均值趨勢,保留原始點
histogramSturges 分組,可按組分面
stacked_bar明確整體/組分字段,柱頂按累計總量設置刻度;無組分時用排序橫條
category_count分類計數,排序橫條
correlation_heatmappairwise-complete Pearson;常量列/有效對不足為 NA;發散色階固定 [-1,1] 並帶 colorbar

n=1 的 SD/SE/CI、常量變量相關和零 X 方差擬合均為 null,不寫成 0。柱/條從 0 起,最高刻度覆蓋柱頂和誤差線。

可讀性自動防禦(不截斷數據):全圖基礎字號由 min(寬, 1.55×高) 驅動,寬扁畫布不隨寬度放大字號;散點/折線點徑按「可用繪圖面積/點數」密度收縮(下限 0.9mm);類別 >8 轉橫向佈局並按行數自動增高畫布(封頂 max_height_mm),行距不足時按行距收縮類別標籤字號(下限 6pt);垂直佈局預測標籤重疊時改 45° 旋轉;熱圖按變量數與寬度增高畫布,軸標籤優先使用數據字典短名並剝離括號單位,水平投影裝不下時升到 90°,字號按格寬收縮,格內數字按格寬定徑(上限 ~9pt,格 <5.5mm 或變量 >12 時省略);時間軸刻度按畫布寬度封頂抽稀並用「MM-DD / YYYY」兩行式標籤;標題按畫布寬度換行。每次調整都寫入 layout_adjustment、analysis 的 notes 與 warnings,可追溯。

4. 三格式導出

每圖默認生成:

  • figure_N.pdf:Cairo PDF,檢查實際頁面尺寸和字體嵌入證據;
  • figure_N.png:預設 600 dpi,任務可指定更高/更低但不得低於 300 dpi;
  • figure_N.svg:svglite,保留可編輯 <text>;
  • figure_N.tsv + figure_N.csv、figure_N_spec.json、figure_N_analysis.json、figure_N_lineage.json。

即使使用者只請求 PDF,也保留 PNG 預覽和 SVG 可編輯件。導出格式分級:請求且屬於支援範圍(PDF/PNG/SVG)的格式缺失時該圖不得標為完整;請求不支援的格式(如 emf)記錄為 format_gaps 範圍外缺口並交付預設三格式,不靜默忽略也不偽造。

5. 四級 QA

  1. 科學表達:圖型、分組、單位、誤差線、顯著性和圖註口徑一致。
  2. 數值複核:Python 獨立重算均值/SD/SE、OLS/Pearson 和相關矩陣,與 R 結果比對。
  3. 文件與視覺檢查:easyplot 檢查尺寸/DPI/PDF 字體/SVG 文字;檢查 PNG 非空白、實際邊距和色板上下文。邊距語義:空白圖或內容貼邊/裁切(距畫布 <0.02 in)判失敗;留白低於 0.1 in 僅記 tight 標誌,不把合格圖判成 partial。
  4. 端到端復現:從隨附原始快照再次執行 data_prep.sh + plot.R + normalize_pdf.py,比較繪圖 TSV/CSV、lineage、統計 JSON、PDF、PNG、SVG 的 SHA-256。PDF 標準化只把 Cairo/pypdf 的 CreationDate/ModDate 固定為 Unix epoch,不改頁面、字體或圖形內容。

自動檢查完成後,Agent 必須查看實際 PNG(必要時再渲染 PDF),檢查標籤重疊、亂碼、遮擋和科學語義。像素邊距檢查不等於人工/多模態視覺審查。

輸出

result.json 保留 case_id 與原輸出契約,並包含:

  • figures:逐圖路由、實際圖型、準備記錄、R 分析、獨立圖註、文件元數據/哈希、QA、全鏈復現結果、layout_adjustment(佈局自適應記錄)與 format_gaps(範圍外格式缺口);
  • data_to_visual_map:源列 → 視覺通道、繪圖 TSV 與行級 lineage;
  • baseline_comparison:與基礎 Agent/通用繪圖方案的七維度確定性防禦對照(圖表選擇/坐標軸/編碼可讀性/標註圖註/導出規格/復現證據/異常降級),每項註明典型失敗、本 Skill 處理與證據位置;平台側公平對照由組織方自行運行,本表不虛構基線數字;
  • evidence_map:源快照、運行計劃、規則哈希、依賴、腳本和復現命令;
  • 狀態說明:與 status.overall 一致的缺口、說明和不確定性。

所有交付文件位於 /app/output。可獨立重跑:

cd /app/output
bash data_prep.sh
Rscript plot.R
python3 -B scripts/normalize_pdf.py --plan run_plan.json --out .
python3 -B scripts/audit_outputs.py --plan run_plan.json --out .

異常處理

情況行為
案例不可解析、重複列名、缺字段寫誠實的錯誤/部分結果和缺口,不偽造圖件
缺失/NaN/Inf/聲明哨兵排除該圖不可用觀測,保留源行號和原因
完全重複默認保留並報告;僅在明確規則下去重
某組 n=1畫原始點,SD/SE/CI 為 null
常量相關/零 X 方差只畫可用點,相關/擬合為 null
類別或系列過多不截斷;自動增高畫布/橫向佈局/收縮標籤字號/分面並記錄 layout_adjustment;超出最大高度時明示標籤可能仍密集
熱圖變量多/標籤長畫布按變量數與寬度增高;字典短名+剝離括號單位;角度 45°→90° 自適應;字號按格寬收縮(≥6pt);>12 變量省略格內數值
日期刻度密集刻度按畫布寬度封頂抽稀,兩行式 MM-DD/YYYY 標籤
請求不支援的導出格式(如 emf)記錄 format_gaps 範圍外缺口並交付預設三格式,不判 partial、不靜默
任務提供顯著性結果透傳渲染:配對→括線+標註,單類別→組末端字母;圖註註明方法與「未計算任何檢驗」,絕不自造星號
R 包、字體、Pillow、pypdf 缺失保存可復跑材料並明確未完成項;有網路時可按冷啟動命令安裝後復跑;matplotlib 可用時降級渲染真實 PNG(300dpi+,僅 PNG,PDF/SVG 缺口如實記錄不偽造)
數據檔案路徑失效按多基目錄回退解析;仍失敗時報告全部嘗試路徑
單圖渲染失敗其它圖繼續;該圖寫 status=error 和真實原因
任一出圖或 QA 失敗整體狀態為 partial,不寫 complete

自查

# 從倉庫根目錄運行
python3 -B answer/060_科研數據可視化/scripts/test_pipeline.py
python3 answer/_shared/verify.py --only 060

最小示例必須滿足:通用契約 PASS、圖件專項 PASS、每圖三格式存在、QA 全過、兩次全鏈運行哈希一致。重複運行時僅 generated_at 可變化。

方法來源與許可

  • 本機 sci-plot:R/ggplot2、ggprism 主題、Arial/Cairo、svglite、Sturges、刻度覆蓋與視覺 QA 規則。
  • Rimagination/easyplot 提交 d150e01:複用 easyplot_metadata.py 與 easyplot_palette_audit.py;MIT 原文在 scripts/easyplot-LICENSE.txt。
  • 中文標籤是本題輸入保真要求:默認 Arial;只有實際標籤需要 CJK 時選擇真實中文字體並記錄,不把缺字回退當成成功。

最小調用示例

cd answer/060_科研數據可視化
python3 -B scripts/pipeline.py \
  --case examples/min_example/input/case.json --out /tmp/figure060-demo
python3 -B scripts/validate.py \
  --case examples/min_example/input/case.json --result /tmp/figure060-demo/result.json
python3 -B scripts/validate_figures.py --result /tmp/figure060-demo/result.json

示例為 24 行合成數據,包含一個組間比較和一個相關圖;示例輸出只用於回歸,不是正式案例結果。

相關技能