科研數據可視化(research-figure-builder)
目標不是「畫出一張圖」,而是讓圖上每個數據元素都能回到源數據,並讓別人用隨附快照和腳本重跑出同一交付件。
何時使用
- 輸入科研數據表與出圖任務,需要真實圖件、統計口徑、圖註和複現證據;
- 需要比較、相關、趨勢、分佈、構成、分類計數或相關熱圖;
- 需要指定期刊欄寬、畫布、DPI、字體或導出格式;
- 需要識別缺失、非有限數、重複、小樣本和類別過多,而不是靜默刪數據。
不用於實驗設計、統計方法創新、圖像後期美化或交互式儀表盤。顯著性標記只接受已提供且帶統計方法/校正口徑的結果,不自動生成星號。
輸入
-
讀取實際
/input/case.json、/input/task.md和案例材料,不根據數據集名稱猜任務。 -
數據支援內聯
dataset.rows、CSV、TSV、JSON 和唯讀 SQLite;相對路徑按 case 所在目錄解析,case 被遷移到/app/work等目錄時自動回退查找各級祖先目錄下的input/、當前目錄與/input(Harbor 佈局);全部找不到時報出完整嘗試路徑,不猜測數據內容。 -
出圖工單
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。
-
data_dictionary的label/type/unit/missing_values/sentinels會進入標籤、類型和清洗規則。數值型-999等哨兵必須顯式聲明,不能全域猜測。數據字典的短label優先作為熱圖等坐標軸顯示名,原始列名保留在血緣與 analysis。 -
若案例只有自然語言任務而缺
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_auto | n<3 只畫點;3–9 畫點與聲明的摘要;每組 n≥10 用箱線 + jitter |
boxplot_points / violin_points | 顯式箱線/小提琴 + jitter;每組 n<3 時降級為點圖並記錄 |
scatter_with_fit | 散點 + 總體 OLS 與 95% 置信帶;fit_group=true 才分組擬合;顏色 + 形狀雙編碼 |
line_series | 按真實時間/有序數值排序,顏色 + 線型;重複點給均值趨勢,保留原始點 |
histogram | Sturges 分組,可按組分面 |
stacked_bar | 明確整體/組分字段,柱頂按累計總量設置刻度;無組分時用排序橫條 |
category_count | 分類計數,排序橫條 |
correlation_heatmap | pairwise-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
- 科學表達:圖型、分組、單位、誤差線、顯著性和圖註口徑一致。
- 數值複核:Python 獨立重算均值/SD/SE、OLS/Pearson 和相關矩陣,與 R 結果比對。
- 文件與視覺檢查:easyplot 檢查尺寸/DPI/PDF 字體/SVG 文字;檢查 PNG 非空白、實際邊距和色板上下文。邊距語義:空白圖或內容貼邊/裁切(距畫布 <0.02 in)判失敗;留白低於 0.1 in 僅記
tight標誌,不把合格圖判成 partial。 - 端到端復現:從隨附原始快照再次執行
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 行合成數據,包含一個組間比較和一個相關圖;示例輸出只用於回歸,不是正式案例結果。