DrNbnonono/paper-figures

Figuras para artigos

Uma figura é um argumento tornado visível. Ela ganha seu lugar quando um leitor que a olha por cinco segundos, antes de ler a legenda, consegue afirmar a declaração que ela faz. Tudo nesta skill serve a esse teste.

O estilo que ela codifica é aquele que os melhores artigos no S&P, USENIX Security, CCS e NDSS compartilham: pequeno, vetorial, figuras com largura de duas colunas; poucos itens de exibição; rótulos diretos; cores seguras para impressão; legendas que indicam a conclusão em vez de descrever os eixos.

Princípio central

Uma figura = uma afirmação = uma mensagem na legenda.

Se duas afirmações precisam ser mostradas, desenhe dois painéis ou duas figuras. Uma figura que mostra três coisas é lida como nenhuma delas.

Inegociáveis

1. Uma mensagem por figura. A primeira frase da legenda a declara; o gráfico a suporta.
2. Desenhe no tamanho de impressão. Uma figura de coluna única tem 3,5 pol de largura (IEEE), 3,33 pol (ACM sigconf), 3,4 pol (USENIX). Nunca desenhe grande e reduza a escala no LaTeX: as fontes encolhem abaixo do piso de 7 pt.
3. Saída vetorial (.pdf do matplotlib) para qualquer coisa com texto ou linhas. Raster de 300 dpi apenas para fotografias e capturas de tela.
4. Fontes ≥ 7 pt no tamanho de impressão; rótulos de eixo 8 pt, rótulos de marcação 7 pt.
5. Cores seguras para impressão: paleta Okabe-Ito, nada distinguido apenas por cor, e a figura deve sobreviver à escala de cinza (scripts/check_figure.py --preview).
6. Sem eixos enganosos: gráficos de barras começam em zero; escalas logarítmicas são rotuladas; nenhum eixo y truncado para dramatizar uma diferença; nenhum eixo y duplo sem uma razão explícita e declarada.
7. Mostre incerteza onde a afirmação é quantitativa: bandas de IC, barras de erro, ou n na legenda. Uma estimativa pontual sem um denominador não é um resultado.
8. A legenda declara o que notar, depois as unidades, depois n. Não é uma lista de cores.
9. Sem enfeites desnecessários: sem 3-D, sem sombras, sem gradientes como decoração, sem mapas arco-íris, sem preenchimentos de fundo, sem linhas de grade que combatam os dados.
10. Reprodutível: o script que gerou a figura reside ao lado dela no repositório, com o arquivo de dados ou uma semente. Uma figura que ninguém pode regenerar é um passivo na versão final.

Etapa 0 — Decida a afirmação primeiro

Escreva uma frase, em palavras, que a figura deve tornar evidente:

"O código de exploração público agora aparece mais rápido que os advisories: a proporção de artefato-para-advisory em 30 dias subiu de 0,63 para 1,83 em quatro eras."

Se você não consegue escrever essa frase sem "e", você tem duas figuras.

Preencha templates/figure-brief.md antes de tocar no matplotlib. Leva dois minutos e previne o retrabalho mais comum: uma bela figura que mostra a quantidade errada.

Etapa 1 — Escolha a codificação a partir da afirmação

Leia references/encoding-guide.md. A versão resumida:

Tipo de afirmação	Codificação	Evite
Distribuição / quão rápido	CDF (degrau), violino, box, strip	barra de médias sem dispersão
Comparação pareada	haltere, inclinação, pontos pareados	duas barras flutuantes
Composição ao longo do tempo	área empilhada, pequenos múltiplos	pizza, pizza 3-D
Ranqueamento	barras horizontais ordenadas, gráfico de pontos	barras não ordenadas, arco-íris
Compensação de duas variáveis	dispersão + fronteira de Pareto	bolha com tamanhos ilegíveis
Matriz / cobertura	mapa de calor com mapa perceptualmente uniforme, valores nas células	mapa de calor arco-íris sem valores
Processo / linha do tempo	raia, linha do tempo, diagrama de sequência	uma tabela de datas em prosa
Taxonomia / decisão	árvore rotulada, matriz de células preenchidas	texto aninhado com marcadores

Etapa 2 — Desenhe com o estilo compartilhado

import sys; sys.path.insert(0, "scripts")
from figure_style import apply_style, new_fig, save, SERIES, panel_label

apply_style()                       # base 8 pt, Okabe-Ito, rcParams seguros para impressão
fig, ax = new_fig(3.5, 2.3)         # coluna única, proporção correta
ax.plot(x, y, color=SERIES[0], label="Pré-IA")
save(fig, "figs/fig1_cdf")          # escreve .pdf (para LaTeX) + .png (visualização)

Ajuste o estilo globalmente, nunca por figura: duas figuras em um mesmo artigo com fontes diferentes ou espessuras de linha diferentes parecem dois artigos diferentes.

references/style-spec.md lista cada configuração e por que ela está definida dessa forma.

Etapa 3 — Rotule diretamente, legenda por último

• Coloque o nome da série no final de sua linha, ou no gráfico, em vez de em uma caixa de legenda. Use uma legenda apenas quando os rótulos diretos colidirem (veja examples/fig01_cdf.png).
• Rótulos de painel A, B, C em negrito no canto superior esquerdo, referenciados na legenda.
• Rótulos de eixo: quantidade + unidade + escala (Dias desde a divulgação (escala log)).
• Em seguida, escreva a legenda com references/captions.md: conclusão → o que os eixos mostram → unidades/n/IC → a única ressalva que um leitor não pode perder.

Etapa 4 — Torne-a segura para impressão

• Paleta: SERIES em scripts/figure_style.py (Okabe-Ito). Dados sequenciais: cividis, nunca jet. Divergente: RdBu_r, apenas em torno de um zero significativo.
• Codifique também por forma: marcadores e estilos de linha variam com a série, para que a figura sobreviva à impressão em escala de cinza e a revisores daltônicos.
• Execute o verificador:

python scripts/check_figure.py figs/fig1_cdf.png --preview

Ele reporta tamanho/dpi, a paleta cromática, a separação em escala de cinza e deuteranopia, e escreve fig1_cdf_gray.png / fig1_cdf_cvd.png. Olhe para ambos.

references/accessibility.md cobre os detalhes (contraste, CVD, texto alternativo).

Etapa 5 — Exporte e inclua

• Exporte PDF vetorial com fontes TrueType incorporadas (pdf.fonttype = 42, já definido).
• Inclua na largura de impressão: \includegraphics[width=\columnwidth]{figs/fig1_cdf.pdf}.
• Verifique o PDF compilado em 100%: nenhum texto abaixo de 7 pt, nenhum rótulo cortado, nenhuma figura mais alta que meia coluna, a menos que seja a figura conceitual principal do artigo.
• references/production.md cobre inclusão em LaTeX, incorporação de fontes e layout de arquivos.

Etapa 6 — Verifique como um revisor

1. Teste de cinco segundos: mostre a figura sozinha para alguém; eles conseguem afirmar a conclusão?
2. Teste da legenda: a primeira frase deve ser a afirmação, não "A Figura 3 mostra…".
3. Teste de escala de cinza: ambas as visualizações são lidas corretamente.
4. Teste de zoom: a 100% do PDF compilado, todo rótulo é legível.
5. Teste de integridade: os números na figura correspondem à tabela e ao texto; o eixo não está truncado; as barras de erro são definidas na legenda.
6. Teste de reutilização: exclua o PNG; o script o regenera de forma idêntica byte a byte? Deveria.

Orçamento de itens de exibição

Classe de veículo	Total de itens de exibição	Notas
Conferência top-4	6–10	Uma figura conceitual, uma linha do tempo, tabelas de resultados; cada item referenciado no texto
Revista	4–6	Uma mensagem por item; barras laterais em vez de apêndices
Periódico	8–12	Mais espaço, mesmas regras

Se uma figura não é referenciada com uma afirmação no texto ("A Figura 5 mostra que X"), remova-a ou reescreva a frase.

Antipadrões

Antipadrão	Por que falha
Mapa de cores arco-íris/jet	Não é perceptualmente ordenado; valores enganosos; ilegível em escala de cinza
Barras/pizzas 3-D ou com sombra	Decoração que distorce a comparação
Pizza com >3 fatias	Humanos comparam ângulos mal; use barras ordenadas
Eixo y duplo	Convida a uma afirmação de correlação que os dados não suportam; use dois painéis
Eixo y truncado em barras	Exagera diferenças; um revisor notará
Caixa de legenda com 6 entradas	Força a correspondência de cores; use rótulos diretos ou pequenos múltiplos
Texto minúsculo reduzido no LaTeX	Fontes caem abaixo de 7 pt; a figura se torna ruído cinza
Legenda que lista cores	"A linha azul mostra…" não diz ao leitor nada que ele não possa ver
Captura de tela de uma tabela	Não é vetorial, não é editável, não é acessível
Figura que repete uma tabela	Desperdício de um item de exibição; mantenha a que suporta a afirmação
Eixo log não rotulado	O leitor não pode comparar inclinações em décadas
n / barras de erro ausentes	Uma estimativa pontual sem incerteza não é evidência

Mapa de recursos

Arquivo	Uso
references/venue-figure-profiles.md	O que os veículos top-4 esperam, larguras de coluna, regras de legenda/posicionamento
references/encoding-guide.md	Mapeamento afirmação → gráfico, escalas log, incerteza, quando uma tabela vence
references/style-spec.md	Cada configuração do matplotlib com sua razão; códigos hex da paleta
references/captions.md	Fórmula de legenda e exemplos de antes/depois
references/accessibility.md	Segurança para daltônicos e escala de cinza, contraste, texto alternativo
references/production.md	Exportação, inclusão em LaTeX, fontes, layout de arquivos, reprodutibilidade
references/anti-patterns.md	O que remover, com o exemplo que o mostra
scripts/figure_style.py	rcParams, paleta Okabe-Ito, new_fig, save, panel_label
scripts/check_figure.py	Verificação de tamanho/dpi, visualizações em escala de cinza e deuteranopia, relatório de paleta
scripts/make_examples.py	Gera cada figura de exemplo (dados sintéticos)
examples/	Imagens de referência: como é o bom, além de um par ruim-vs-bom
templates/figure-brief.md	Resumo de uma página antes de desenhar