0x6869726f6b69/claude-skills

Compositor de Figuras de Grau Nature

As figuras não são meras "exibições de resultados", mas sim meios de demonstrar visualmente uma afirmação científica. Este skill reorganiza resultados de análise dispersos em uma história de "1 Figura = 1 afirmação" e os finaliza em arquivos que atendem às especificações técnicas dos periódicos Nature.

<SKILL_DIR> é o diretório onde este SKILL.md está localizado. Pré-requisitos: Python 3.9+, matplotlib, numpy, pandas, Pillow, PyMuPDF (pip install pymupdf), scipy (para IC de 95%).

Recursos Inclusos

Caminho	Conteúdo	Quando ler
references/guidelines.md	Diretrizes de plotagem (7 princípios), especificações técnicas Nature, checklist final	Leitura antes do planejamento, releitura no QA
references/storyboard.md	Como agrupar resultados em figuras, tipos de Figura 1, tipos de layout, procedimento de design automático	Passo 3
references/charts.md	Tipo de afirmação → formato de gráfico, incerteza, eixos, como desenhar campos (mapas), exemplos de código nfig	Passo 3 (escolha do formato), 5
references/captions-tables.md	Como escrever legendas, tabelas e material suplementar com exemplos	Passo 7
scripts/inventory.py	Inventário de arquivos de resultado + folha de contato numerada	Passo 1
scripts/nfig.py	Estilo, paleta de cores fixa, rótulos de painel, auxiliares de plotagem, QA automático	Passos 4–6
scripts/assemble.py	Compõe PDF/SVG/PNG existentes em múltiplos painéis, mantendo vetores	Quando há painéis que não podem ser redesenhados
scripts/check_figure.py	Verificação de especificações do arquivo final + imagens de simulação de daltonismo	Passo 6
scripts/make_table.py	CSV → tabela LaTeX (booktabs) / Markdown	Passo 7
assets/figure_plan_template.md	Modelo para o plano de figura	Passo 3
assets/style_template.py	Modelo para convenções comuns de todas as figuras (nomes, intervalos de cores, rótulos de eixos)	Passo 4
assets/layout_example.json	Exemplo de layout para assemble.py	Ao usar assemble

Fluxo de Trabalho

Passo 1 — Inventário de Resultados (rápido, antes de perguntar)

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

• Leia paper_figures/_inventory/contact_sheet_*.png para entender o que cada resultado mostra. A coluna "made by / read by" do relatório permite rastrear figura → script gerador → dados originais (necessário para redesenho).
• Leia manuscritos, READMEs ou anotações para compreender a pergunta de pesquisa, o método proposto e a afirmação.
• Atribua uma observação de uma frase a cada resultado (ex: #6 benchmark.csv → O método proposto alcança a maior precisão em todos os 3 conjuntos de dados, +6 pt). Isso servirá de insumo para o Passo 2 (opções) e Passo 3 (planejamento).
• Se nenhum resultado for encontrado, pergunte ao usuário sobre sua localização no Passo 2.

Passo 2 — Entrevista (obrigatória após a ativação do skill)

A decisão sobre como agrupar os resultados é do usuário, então confirme antes de plotar. No entanto, se a mensagem de ativação já fornecer respostas claras para algumas perguntas, não as repita. Use AskUserQuestion se disponível; caso contrário, faça perguntas numeradas em texto e aguarde a resposta. As opções devem ser concretas (com números de arquivo e observações) com base no inventário do Passo 1.

1. Alvo (obrigatório) "Quais resultados você deseja combinar em uma figura?"
   • Automático: Projete a estrutura completa de figuras (Fig. 1~N + SI) a partir de todos os resultados (Recomendado)
   • 1–2 grupos candidatos criados a partir do inventário (ex: "Comparação de desempenho: #1 accuracy_bar, #6 benchmark.csv")
   • Descrição livre (Outro): especifique como "#1, #4, #6 em uma figura"
2. Afirmação "Qual é a mensagem principal que esta figura deve transmitir?" — 1–2 afirmações estimadas + automático
3. Tamanho de publicação — 2 colunas 183 mm (Recomendado) / 1 coluna 89 mm / 1,5 coluna 120–136 mm / automático
4. Saídas (seleção múltipla) — Figura (PDF+SVG+PNG) / Legenda (Inglês) / Tabela / Lista de candidatos a SI

Tratamento das respostas:

• Se a mensagem de ativação já especificar o alvo (P1), prossiga com os valores padrão para P2–P4 (afirmação estimada, 183 mm, Figura+Legenda) e só pergunte quando houver dúvida.
• Para itens "automático" ou não instruídos, o Claude decide quais resultados adotar, como dispor e como resumir. Siga o "procedimento de design automático" em references/storyboard.md.
• Se o usuário disser "vá em frente sem perguntar", trate todos os itens como automáticos.
• O texto nas figuras e a legenda devem estar em inglês (padrão, pois o periódico alvo é em inglês). A conversa pode ser no idioma do usuário.

Passo 3 — Plano da Figura (Storyboard)

Antes de escrever código, leia references/storyboard.md e escreva paper_figures/figure_plan.md no formato de assets/figure_plan_template.md. Inclua:

• Fluxo geral do artigo (What → How → Why → Performance → Impact) e o papel de cada figura
• Para cada figura: afirmação em uma frase (que se tornará o título da legenda), tabela de painéis (rótulo / conteúdo / formato de gráfico (escolha em references/charts.md §1) / fonte de dados / hero ou support /), mosaico e dimensões, papel das cores
• Resultados excluídos do texto principal (destinados a SI) e motivo. Não esconda limitações ou exemplos de falha; coloque-os em um painel de limitações no texto principal ou no SI
• Informações ausentes (n, definição de barras de erro, teste, unidades) listadas como [AUTHOR TODO]

Mostre o plano em uma tabela resumida no chat. Em caso de automático ou quando o plano segue exatamente as instruções do usuário, prossiga para a plotagem sem esperar confirmação, acrescentando "O plano pode ser alterado posteriormente". Pare e consulte apenas se os resultados especificados não suportarem a afirmação ou se as instruções forem contraditórias.

Passo 4 — Fixar o Estilo Comum

• Copie nfig.py para paper_figures/src/ (para que os scripts das figuras possam ser reexecutados mesmo sem o skill).
• Para todo o artigo, fixe em um único paper_figures/figure_style.json as correspondências: método/condição → cor/marcador/tipo de linha. Se o significado das cores mudar de figura para figura, o leitor terá que consultar a legenda repetidamente; portanto, use este arquivo para todas as figuras.

import style                      # paper_figures/src/style.py (caminho independente do local de execução)
pal = nfig.Palette.load_or_build(style.PALETTE,
        proposed=["Ours"], highlight=["SOTA-X"],
        baselines=["Base A", "Base B"], references=["Oracle"])

• proposed = cor de destaque (vermelho alaranjado com saturação suave), highlight = a única linha de base mais forte em azul, outras linhas de base = tons de cinza + marcadores/tipos de linha, reference (valor teórico, limite superior, nível de chance) = linha tracejada preta.
• Atribuições existentes não mudam; novos nomes são adicionados. Para categorias que não são métodos (como conjuntos de dados), não reutilize as mesmas cores; distinga por posição, divisão de painéis e marcadores.
• As "convenções de exibição" compartilhadas por todas as figuras devem ser consolidadas em um único lugar em paper_figures/src/style.py (copie assets/style_template.py) e importadas por cada script de figura: nomes nos dados → nomes de exibição ("PISurr (ours)" → "PISurr"), intervalo de cores para mapas da mesma grandeza (ex: TEMP_LIM = (300, 345), ERR_LIM = (0, 6)), rótulos de eixos com unidades. Escrever isso figura por figura leva a inconsistências.

Passo 5 — Plotagem

Em princípio, redesenhando a partir dos dados originais com nfig. A colagem de PNGs existentes tende a resultar em fontes, espessuras de linha e cores inconsistentes, e a redução pode fazer com que o texto fique abaixo de 5 pt. Escolha o formato do gráfico em references/charts.md.

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))   # Funciona independentemente de onde é executado
import nfig
nfig.use_style()                                          # Arial 7/6 pt, eixos 0.5 pt, TrueType 42
fig, axd = nfig.figure("double", 120, mosaic="aab;cde")  # Desenhe no tamanho final de publicação
# ... cada painel (receitas de charts.md) ...
nfig.shared_legend(fig, pal.handles(["Ours", "SOTA-X", "Base A"]))  # Uma legenda para toda a figura
nfig.label_panels(fig, axd)          # Chame por último: a, b, c… 8 pt negrito, alinhado em linhas e colunas
nfig.save(fig, "paper_figures/fig2")       # .pdf/.svg/.png + relatório de QA automático

label_panels fixa (torna imutável) o layout, portanto, legendas, anotações e barras de cores devem ser adicionados antes.

• 1 Figura = 1 script (paper_figures/src/fig2.py). Deve ser reproduzível desde a leitura dos dados até o salvamento.
• Desenhe no tamanho final; não reduza depois. Não use bbox_inches="tight", pois altera a largura.
• O painel hero deve ser o maior e posicionado no canto superior esquerdo ou na linha superior. Gráficos do mesmo tipo devem ter tamanho, intervalo de eixos e ticks alinhados.
• Figuras com linhas de diferentes tipos de painéis (faixa de diagrama / coluna de imagens ou mapas / gráficos) não devem ser combinadas em um único mosaico; use nfig.figure("double", 120, rows=[("a", 0.8), ("bcdef", 1), ("g", 1)]) para agrupar por linha. Em uma única grade, o espaço dos rótulos de ticks de uma coluna se aplica a outras linhas da mesma coluna, comprimindo imagens ou mapas. Se as linhas forem do mesmo tipo, mantenha um único mosaico (as bordas das colunas se alinham).
• Para campos como mapas de temperatura ou erro, use nfig.field (intervalo de cores definido em style.py) + nfig.colorbar; para a mesma grandeza, use uma única barra de cores. Para fotografias ou imagens de microscopia, use nfig.image_panel.
• Painéis que não podem ser redesenhados (diagramas de ferramentas externas, imagens de microscopia, figuras sem dados originais):
  • Se forem poucos, incorpore com nfig.image_panel(ax, path) (resultará em raster).
  • Para combinar mantendo vetores, componha PDFs de painéis desenhados com nfig e PDFs externos usando scripts/assemble.py (assets/layout_example.json, caminhos relativos ao JSON). Os painéis do nfig devem ser desenhados com as mesmas dimensões (mm) das células finais para que a taxa de redução seja ≈1. Ajuste as proporções das células e a altura até que relatórios de "text below 5 pt", "below 300 dpi" e "cell mostly empty" desapareçam.
  • Informe ao usuário por que não foi possível redesenhar e que poderia ser refeito se os dados originais estivessem disponíveis.
• Integridade dos dados: não altere valores, não selecione apenas os favoráveis, barras devem começar em zero, não trunque eixos para exagerar diferenças. Imagens só podem ter ajustes e cortes uniformes (sem edição localizada, composição ou edição por IA generativa).

Passo 6 — QA e Ciclo de Correção (mínimo de 2 rodadas)

1. Verificação automática: Além do relatório do nfig.save, execute python <SKILL_DIR>/scripts/check_figure.py paper_figures/fig2.pdf. Corrija erros (ERROR) obrigatoriamente; avisos (WARN) só podem permanecer se houver uma intenção justificada, e a razão deve ser registrada.
2. Inspeção visual: Leia paper_figures/qa/fig2_preview.png (tamanho final) e fig2_access.png (simulação de deuteranopia, protanopia e escala de cinza). Verifique o checklist final em references/guidelines.md. Especialmente: a afirmação é compreendida em 3 segundos? O hero é o mais proeminente? A leitura flui do canto superior esquerdo para o inferior direito? Há sobreposição ou estouro de texto/linhas? Alinhamento está correto? Espaços em branco sem sentido ou compressão excessiva? As cores são distinguíveis em simulações de daltonismo e escala de cinza?
3. Corrija e regenere, depois verifique novamente. Por fim, pergunte a si mesmo, como revisor: "Esta figura, com sua legenda, é suficiente para me convencer da afirmação?"

Passo 7 — Legenda, Tabela e Entrega

• Escreva a legenda em references/captions-tables.md e salve em paper_figures/captions.md (título em negrito = afirmação → descrição de cada painel em ordem → definição de símbolos, cores e abreviações → n, barras de erro, teste).
• Para comparações numéricas precisas, use tabelas: scripts/make_table.py (booktabs, sem linhas verticais, apenas o melhor valor em negrito). Dados em formato longo (uma linha por semente) podem ser agregados diretamente em média ± d.p. e n usando --groupby e --stat.
• Relate ao usuário: lista de arquivos criados, afirmação e composição de cada figura, resultados movidos para SI com motivo, [AUTHOR TODO] (estatísticas não verificadas, etc.), e WARNs mantidos com justificativa.

Estrutura de Saída (Padrão)

Para não se misturar com arquivos existentes do usuário (como figures/) e evitar sobrescritas, a saída é consolidada em paper_figures/. Se o usuário especificar outro local, siga-o.

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

Quando Estiver em Dúvida

• Decida o que mostrar com base em "Isso serve como evidência para a afirmação?". Resultados que não servem como evidência, por mais trabalhosos que tenham sido, devem ir para o SI.
• Para melhorias numéricas, sempre combine com exemplos concretos que mostrem o significado real.
• Mostrar não apenas os melhores resultados, mas também condições de aplicação, limitações e exemplos de falha aumenta a credibilidade da afirmação.
• Em caso de dúvida, escolha a opção mais simples: reduza cores, reduza texto (explique na legenda), compartilhe legendas.