Nature-grade Figure Composer

Nature-grade Figure Composer은(는) 무엇을 하나요?

Figure는 「결과 표시」가 아닌 **「과학적 주장을 시각적으로 논증하는 수단」**으로 설계합니다. 이 스킬은 흩어진 분석 결과를 「1 Figure = 1개의 주장」이라는 스토리로 재구성하여, Nature 계열의 기술 사양을 충족하는 파일로 완성합니다.

<SKILL_DIR>은 이 SKILL.md가 있는 디렉토리입니다. 필요 사항: Python 3.9+, matplotlib, numpy, pandas, Pillow, PyMuPDF (pip install pymupdf), scipy (95% CI 사용 시).

동봉 리소스

경로	내용	읽는 시점
references/guidelines.md	사용자 지정 도면 지침(7원칙), Nature 기술 사양, 최종 체크리스트	계획 전에 한 번 읽고, QA에서 다시 읽음
references/storyboard.md	결과→Figure 정리 방법, Figure 1 유형, 레이아웃 유형, 자동 설계 절차	Step 3
references/charts.md	주장 유형별 그래프 형식, 불확실성·축, 지도(맵) 그리는 방법, nfig 코드 예제	Step 3 (형식 선택), 5
references/captions-tables.md	Caption, Table, Supplementary 작성 방법과 예제	Step 7
scripts/inventory.py	결과 파일 목록 작성 + 번호가 있는 콘택트 시트	Step 1
scripts/nfig.py	스타일, 의미가 고정된 색상, 패널 레이블, 도면 헬퍼, 자동 QA	Step 4–6
scripts/assemble.py	기존 PDF/SVG/PNG를 벡터 상태로 다중 패널에 합성	다시 그릴 수 없는 패널이 있을 때
scripts/check_figure.py	완성 파일 사양 확인 + 색각 시뮬레이션 이미지	Step 6
scripts/make_table.py	CSV → booktabs LaTeX / Markdown 표	Step 7
assets/figure_plan_template.md	Figure 계획서 템플릿	Step 3
assets/style_template.py	표시명·색상 범위·축 레이블 등 모든 Figure 공통 규약 템플릿	Step 4
assets/layout_example.json	assemble.py 레이아웃 예제	assemble 사용 시

Workflow

Step 1 — 결과 목록 작성 (질문 전에 신속히)

python <SKILL_DIR>/scripts/inventory.py <project_root> --sheet paper_figures/_inventory --out paper_figures/_inventory/inventory.md

• paper_figures/_inventory/contact_sheet_*.png 를 Read로 보고 각 결과가 무엇을 나타내는지 파악합니다. 보고서의 「made by / read by」 열을 통해 그림→생성 스크립트→원본 데이터를 추적할 수 있습니다 (재그래프에 필요).
• 원고·README·메모가 있으면 읽고, 연구의 질문·제안 방법·주장을 파악합니다.
• 각 결과에 한 문장의 소견을 추가합니다 (예: #6 benchmark.csv → 제안 방법이 3개 데이터셋 모두에서 최고 정확도, +6 pt). 이는 Step 2의 선택지와 Step 3 계획의 재료가 됩니다.
• 결과를 찾을 수 없으면 Step 2에서 함께 위치를 물어봅니다.

Step 2 — 히어링 (스킬 실행 후 반드시 수행)

정리 방법의 결정권은 사용자에게 있으므로, 도면 작성 전에 확인합니다. 단, 실행 메시지에서 이미 답을 알고 있는 항목은 다시 묻지 않습니다. AskUserQuestion이 있으면 그것을 사용하고, 없으면 번호가 있는 질문을 텍스트로 제시하여 답변을 기다립니다. 선택지는 Step 1의 목록에서 구체적으로 (파일 번호·소견 포함) 만듭니다.

1. 대상 (필수) 「어떤 결과를 하나의 Figure로 정리하시겠습니까?」
   • 자동: 전체 결과에서 논문 전체 Figure 구성 (Fig. 1~N + SI) 설계 (권장)
   • 목록에서 만든 후보 그룹 1–2개 (예: 「성능 비교: #1 accuracy_bar, #6 benchmark.csv」)
   • 자유 기술 (Other)로 「#1, #4, #6 을 하나로」와 같이 지정 가능
2. 주장 「그 Figure에서 가장 전달하고 싶은 것은?」— 추정한 주장 1–2개 + 자동
3. 게재 크기 — 2컬럼 183 mm (권장) / 1컬럼 89 mm / 1.5컬럼 120–136 mm / 자동
4. 출력물 (복수 선택) — Figure (PDF+SVG+PNG) / Caption (영어) / Table / SI 후보 목록

답변 처리:

• 실행 메시지에서 대상(Q1)이 이미 지정되어 있으면 Q2–Q4는 기본값(주장은 추정, 183 mm, Figure + Caption)으로 진행해도 되며, 판단이 갈릴 때만 묻습니다.
• 「자동」또는 지시가 없는 항목은 어떤 결과를 채택하고, 어떻게 배치하고, 어떻게 정리할지까지 Claude가 결정합니다. references/storyboard.md의 「자동 설계 절차」를 따릅니다.
• 「질문 없이 진행해 주세요」라고 하면 모든 항목을 자동으로 처리합니다.
• 그림 속 문자와 Caption은 영어가 기본입니다 (제출처가 영어이므로). 대화는 사용자의 언어로 진행합니다.

Step 3 — Figure 계획 (스토리보드)

코드를 작성하기 전에 references/storyboard.md를 읽고, assets/figure_plan_template.md 형식으로 paper_figures/figure_plan.md를 작성합니다. 포함할 내용:

• 논문 전체 흐름 (What → How → Why → Performance → Impact)과 각 Figure의 역할
• 각 Figure: 주장 1문장 (그대로 Caption의 제목 문장이 됨), 패널 표 (레이블/내용/ 그래프 형식 (references/charts.md §1에서 선택)/데이터 소스/hero 인지 support 인지), mosaic과 치수, 색상 역할
• 본문에서 제외할 결과 (SI行)와 그 이유. 한계·실패 사례는 숨기지 않고, 본문의 한계 패널이나 SI에 배치
• 부족 정보 (n, 오차 막대 정의, 검정, 단위)를 [AUTHOR TODO]로 열거

채팅에는 계획을 짧은 표로 보여줍니다. 자동이거나 사용자의 지정대로 구성된 경우 확인을 기다리지 않고 도면 작성으로 진행하고, 「계획은 나중에 변경할 수 있습니다」라고 덧붙입니다. 지정된 결과로는 주장을 뒷받침할 수 없거나 지정 간에 모순이 있는 경우에만 멈추고 상담합니다.

Step 4 — 공통 스타일 고정

• nfig.py를 paper_figures/src/에 복사합니다 (그림 스크립트가 스킬 없이도 재실행될 수 있도록).
• 논문 전체에서 하나의 paper_figures/figure_style.json에 방법·조건 → 색상·마커·선 종류를 고정합니다. 색상의 의미가 그림마다 바뀌면 독자가 매번 범례를 다시 읽어야 하므로, 모든 Figure에서 이것을 사용합니다.

import style                      # paper_figures/src/style.py (경로는 실행 위치에 의존하지 않음)
pal = nfig.Palette.load_or_build(style.PALETTE,
        proposed=["Ours"], highlight=["SOTA-X"],
        baselines=["Base A", "Base B"], references=["Oracle"])

• proposed＝액센트 색상 (채도를 낮춘 주홍), highlight＝가장 강한 비교 방법 1개만 파랑, 그 외 비교 방법＝ 회색 농담 + 마커/선 종류, reference (이론값·상한·찬스 레벨)＝검정 점선.
• 기존 할당은 그대로 유지되고, 새 이름은 추가됩니다. 방법 이외의 카테고리 (데이터셋 등)에는 같은 색상을 사용하지 않고 위치·패널 분할·마커로 구분합니다.
• 모든 Figure에서 공유하는 「표시 규약」은 paper_figures/src/style.py (assets/style_template.py를 복사)에 한 곳에 정리하고, 각 그림 스크립트에서 import 합니다: 데이터 상의 이름→표시명 ("PISurr (ours)" → "PISurr"), 같은 양의 지도 색상 범위 (예: TEMP_LIM = (300, 345), ERR_LIM = (0, 6)), 단위가 있는 축 레이블. 그림마다 작성하면 어긋나므로.

Step 5 — 도면 작성

원칙적으로 원본 데이터에서 nfig로 재그래프합니다. 기존 PNG를 붙이면 글꼴·선 두께·색상이 맞지 않고 축소 시 문자가 5 pt 미만이 되기 쉽기 때문입니다. 그래프 형식은 references/charts.md에서 선택합니다.

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))   # 어디서 실행해도 동작
import nfig
nfig.use_style()                                          # Arial 7/6 pt, 0.5 pt 축, TrueType 42
fig, axd = nfig.figure("double", 120, mosaic="aab;cde")  # 최종 게재 크기로 그리기
# ... 각 패널 (charts.md의 레시피) ...
nfig.shared_legend(fig, pal.handles(["Ours", "SOTA-X", "Base A"]))  # 범례는 그림 전체에서 1개
nfig.label_panels(fig, axd)          # 마지막에 호출: a, b, c… 8 pt 굵게, 행·열로 정렬
nfig.save(fig, "paper_figures/fig2")       # .pdf/.svg/.png ＋ 자동 QA 보고

label_panels는 레이아웃을 확정(고정)하므로, 범례·주석·컬러바는 모두 그 전에 추가합니다.

• 1 Figure = 1 스크립트 (paper_figures/src/fig2.py). 데이터 로드~저장까지 재현 가능하게 만듭니다.
• 최종 크기로 그리고, 나중에 축소하지 않습니다. bbox_inches="tight"는 폭이 변하므로 사용하지 않습니다.
• hero 패널을 최대로 하여 왼쪽 상단 또는 최상단에 배치합니다. 같은 종류의 그래프는 크기·축 범위·눈금을 통일합니다.
• 행마다 패널 종류가 다른 그림 (모식도 띠 / 이미지·맵 열 / 그래프)은 하나의 mosaic로 만들지 않고 nfig.figure("double", 120, rows=[("a", 0.8), ("bcdef", 1), ("g", 1)])로 행별로 구성합니다. 하나의 그리드로 하면 어떤 열의 눈금 레이블 여백이 같은 열의 다른 행에도 적용되어 이미지나 맵이 찌그러집니다. 같은 종류의 행만 있으면 하나의 mosaic을 유지합니다 (열 끝이 맞춰짐).
• 온도장·오차 맵 등의 장은 nfig.field (색상 범위는 style.py의 공통값) + nfig.colorbar로, 같은 양에는 하나의 컬러바. 사진·현미경 이미지는 nfig.image_panel.
• 다시 그릴 수 없는 패널 (외부 도구의 개요도, 현미경 이미지, 데이터가 남아 있지 않은 그림):
  • 소수라면 nfig.image_panel(ax, path)로 삽입합니다 (래스터가 됨).
  • 벡터 상태로 조합하려면 nfig로 그린 패널 PDF와 외부 PDF를 scripts/assemble.py로 합성합니다 (assets/layout_example.json, 경로는 JSON에서 상대). nfig 측 패널은 합성 후 셀과 동일한 치수 (mm)로 그려 축소율을 ≈1로 만듭니다. 보고의 「text below 5 pt」「below 300 dpi」 「cell mostly empty」가 사라질 때까지 셀 비율과 높이를 조정합니다.
  • 다시 그릴 수 없었던 이유와 원본 데이터가 있으면 정돌릴 수 있음을 사용자에게 알립니다.
• 데이터의 성실성: 값을 변경하지 않음, 편리한 부분만 선택하지 않음, 막대는 0부터, 차이를 과장하는 축 잘라내기를 하지 않음. 이미지는 전체에 균일한 조정과 트리밍만 (부분 가공·합성·생성 AI 편집 불가).

Step 6 — QA와 수정 루프 (최소 2회)

1. 자동 체크: nfig.save 보고에 더해 python <SKILL_DIR>/scripts/check_figure.py paper_figures/fig2.pdf를 실행합니다. ERROR는 반드시 해소하고, WARN은 의도가 있는 경우만 남기고 그 이유를 기록합니다.
2. 육안 확인: paper_figures/qa/fig2_preview.png (최종 크기 상당)와 fig2_access.png (2형·1형 색각, 그레이스케일)를 Read로 보고 references/guidelines.md의 최종 체크리스트를 확인합니다. 특히: 3초 안에 주장이 전달되는가 / hero가 가장 눈에 띄는가 / 왼쪽 위→오른쪽 아래로 읽히는가 / 문자·선의 겹침이나 튀어나옴·정렬 어긋남 / 의미 없는 여백이나 너무 빽빽한가 / 색각·그레이스케일에서도 구별 가능한가.
3. 수정하여 다시 생성하고, 다시 확인합니다. 마지막으로 리뷰어 입장에서 「이 그림과 Caption만으로 주장에 납득할 수 있는가」를 스스로 질문합니다.

Step 7 — Caption·Table·납품

• Caption은 references/captions-tables.md 형식으로 paper_figures/captions.md에 작성합니다 (굵은 제목 문장 = 주장 → 각 패널을 순서대로 → 기호·색상·약어 정의 → n·오차 막대·검정).
• 정확한 수치 비교는 Table로: scripts/make_table.py (booktabs, 세로 줄 없음, 최적값만 굵게). 1행 1시드의 긴 형식 데이터는 --groupby와 --stat로 그대로 mean ± s.d.와 n으로 집계할 수 있습니다.
• 사용자 보고: 생성 파일 목록, 각 Figure의 주장과 패널 구성, SI로 돌린 결과와 이유, [AUTHOR TODO] (미확인 통계 정보 등), 남긴 WARN과 그 이유.

출력 배치 (기본)

사용자의 기존 파일 (figures/ 등)과 섞이거나 덮어쓰지 않도록 출력은 paper_figures/에 정리합니다. 사용자가 다른 위치를 지정하면 따릅니다.

paper_figures/
├── figure_plan.md  figure_style.json  captions.md
├── src/            nfig.py, fig1.py, fig2.py, ...
├── fig1.pdf .svg .png, fig2.*, ...
├── tables/         table1.tex, table1.md
├── qa/             *_preview.png, *_access.png
└── _inventory/     inventory.md, contact_sheet_*.png

판단이 망설여질 때

• 무엇을 보여줄지는 「그 주장의 증거가 되는가」로 결정합니다. 증거가 되지 않는 결과는 아무리 수고가 들어간 것이어도 SI로 돌립니다.
• 수치 개선에는 그것이 실제로 무엇을 의미하는지 보여주는 구체적인 예를 반드시 조합합니다.
• 최상의 결과뿐만 아니라 적용 조건·한계·실패 사례도 보여주면 주장의 신뢰성이 높아집니다.
• 망설여지면 간결한 쪽을 선택합니다: 색상을 줄임, 문자를 줄임 (설명은 Caption으로), 범례를 공유함.