Regras para Figuras com Nível de Publicação
Um checklist para figuras científicas corretas, legíveis e internamente consistentes. Este
skill não impõe um estilo visual — moldura, fonte e paleta são
parâmetros. Antes de plotar, siga a chamada de Notebook abaixo e invoque
apply_figure_style().
Chamada de Notebook para Ciência Aberta
Toda solicitação notebook_execute cujo code use uma função nomeada neste skill
inclui este ID de skill:
{ "kernelSkillIds": ["figure-style"], "code": "apply_figure_style()\n..." }
kernelSkillIds contém o ID do skill; as chamadas de função pertencem ao code. Esta
solicitação está completa como escrita: chame as funções nomeadas diretamente e não
adicione uma etapa de importação ou descoberta.
§0 Escopo
Gatilho de carga (mesma regra da seção "Gráficos com nível de publicação" do prompt do sistema): este skill é para figuras de entrega final — aquelas enviadas em um relatório, artigo ou exportação, ou salvas como um artefato que o usuário manterá — não para gráficos exploratórios/intermediários (visualizações rápidas, EDA, verificações de sanidade), que são desenhados de forma simples sem ele. Uma vez carregado, "cada gráfico" abaixo significa cada gráfico que você renderizar em direção à entrega.
As seções §1–§3, §8 e §9 são de correção — aplicam-se a cada gráfico, em todos os
contextos, e não têm conteúdo estético. As seções §4–§7 são de orientação — padrões que
produzem um resultado limpo, mas que uma alternativa deliberada pode substituir
(regras individuais dentro de §4–§7 que afirmam uma invariante factual/perceptual — por exemplo,
§4.4 centralização semântica-zero, §4.5 CVD, §6.9 ancoragem de líder — ainda vinculam).
Sozinho, este skill é o nível interno (fazer um gráfico bom); figure-composer
e paper-narrative fornecem contexto de múltiplos painéis e de artigo completo.
§1 Fidelidade de dados e autoconsistência
1.1 Linhas excluídas. Uma linha marcada como excluída ou sinalizada nos dados de origem é totalmente omitida ou desenhada com um marcador aberto/hatched visualmente distinto e nomeada na legenda. Ela nunca entra em uma estatística resumida plotada junto com as linhas incluídas.
1.2 Apenas condições comparáveis. Braços medidos sob condições não comparáveis (N diferente, orçamento de época, inicialização, protocolo) não são plotados como pares visuais. Separe-os com uma quebra de faceta ou um marcador no rótulo e indique a diferença uma vez na legenda.
1.3 Autoconsistência. Cada chave, limite e título dentro da figura deve ser satisfeito por cada linha plotada. Antes de salvar, percorra cada rótulo de resultado categórico de volta à regra que o define; se o valor de uma linha contradizer seu rótulo ou o título, a figura está errada, não os dados.
1.4 Títulos de afirmação devem ser verdadeiros. Um título-frase (§5.1) é testado contra cada categoria no eixo antes de renderizar. Se algum o contradizer, qualifique o título ("em 3 de 4 pares") ou rebaixe-o para uma descrição.
1.5 Indique n e o que foi mantido fixo. Cada painel que desenha uma marca de resumo
indica n e a unidade de replicação, e cada small-multiple que mantém uma variável
fixa indica o valor fixo — no painel ou, quando o orçamento da §2 estiver apertado,
na legenda.
1.6 Estrutura de referência é referência. Uma árvore, ordenação ou topologia desenhada como contexto (uma barra de escala, uma faixa de categoria) usa uma referência estabelecida, não uma inferida dos dados plotados. Infira a estrutura apenas quando a estrutura for o resultado.
1.7 Um número por afirmação. Uma afirmação quantitativa (tempo de execução, precisão, contagem) tem exatamente um valor canônico em cada painel, legenda e resumo. Defina o que ela mede e use esse valor em todos os lugares.
§2 Economia de rótulos — piso e teto
A figura mostra o padrão; a legenda carrega o contexto. Projete para um leitor científico geral, não o autor.
2.1 Piso (não removível). Cada marca, série, glifo ou comparador distinto deve ser identificável apenas pela figura. A legenda explica por que isso importa, não o que é. Um rótulo é não removível se deletá-lo deixar o leitor perguntando "o que é isso?"; é removível apenas se a pergunta se tornar "por que isso está aqui?". Rótulos de comparadores nomeiam a coisa ("método anterior", "sem treinamento conjunto"), nunca uma palavra de papel funcional nua ("linha de base", "anterior"). Qualquer termo que um cientista geral não possa entender recebe um glossário de uma palavra.
2.2 Teto. Por painel: título + rótulos de eixos + rótulos de ticks + identidade da série (rotulada uma vez por linha de small multiples) + no máximo 2–3 anotações de resultado. Conte as strings; >6 além dos eixos/ticks significa que você excedeu. O teto conta anotações narrativas (chamadas, rótulos de valor, colchetes) — rótulos de identidade são piso, não orçamento.
2.3 Mova para a legenda: n=, o que foi mantido fixo, expansões de abreviações, notas de rodapé não comparáveis, justificativa de exclusão, ressalvas metodológicas.
2.4 Títulos são conclusões. Um leitor que vê apenas o título sabe o que o painel mostra. "Robusto a perda de genes" passa; "Menos genes" falha. Teste: leia em voz alta sem contexto — se o ouvinte perguntar "menos genes o quê?", reescreva. Para uma linha de small multiples que variam uma coisa, remova títulos por painel para um cabeçalho de linha.
2.5 Valor na marca apenas para o número principal — aquele que o leitor citaria. Todo o resto é lido no eixo.
2.6 Em caso de dúvida, exclua o rótulo e releia. Se a mensagem sobreviver, ela permanece excluída.
§3 Eixos, escalas, small multiples
Quando um eixo existente precisar de um quadro diferente da configuração geral da figura, chame
set_frame(ax, style=...).
3.1 Espaçamento do eixo. Os limites do eixo ultrapassam os dados por ≥ um raio de marcador em todos
os lados; marcadores e texto nunca tocam uma borda. ax.margins(0.04) após plotar,
ou estenda o limite além de qualquer anotação.
3.2 Quebras de eixo sobre intervalo desperdiçado. Quando os dados ocupam <40% de um eixo, quebre o eixo ou comece-o no piso dos dados com um tick claro não zero. Nunca desenhe uma linha de referência, limite ou anotação dentro de uma lacuna de eixo quebrado — a lacuna não tem coordenada.
3.3 Eixos logarítmicos recebem ticks legíveis por humanos — 10², 10³, ou 1k / 10k / 100k,
não expoentes brutos. Nunca desenhe barras preenchidas em um eixo de valor em escala logarítmica
(o comprimento da barra codifica a razão para um piso arbitrário); use pontos + tick de mediana em vez disso.
3.4 Eixos compartilhados entre small multiples. Uma linha ou coluna de small multiples
mostra rótulos de tick uma vez (painel mais à esquerda / mais abaixo); painéis internos mantêm ticks
mas removem rótulos. Quando os painéis compartilham um eixo y e diferem apenas pela variável x,
renderize-os como subplotagens adjacentes (wspace≤0.06) com um título de cabeçalho de linha.
3.5 Preencha a caixa. O envelope de dados de um painel ocupa ≥75% do seu retângulo alocado. Se a proporção natural de um painel deixar faixas mortas, remodele a grade (linha múltipla, painéis complementares empilhados) — não acolchoe o painel.
3.6 Direção de bondade. Quando maior ou menor é melhor não for óbvio a partir do
rótulo do eixo, coloque uma pequena dica vertical ("maior = melhor") na
margem — uma vez por linha de painéis, nunca por painel, e nunca apenas na legenda.
Um glifo direcional embutido em texto rotacionado rotaciona com ele; defina a dica como
vertical. goodness_arrow(ax, ...) coloca esta dica.
3.7 Largura física. Uma figura de linha única a 300 dpi se encaixa na largura de coluna dupla do veículo. Adicionar um esquema ou rótulos não empurra os painéis de dados para mais estreitos do que eram antes.
§4 Cor
4.1 Encadeamento. Uma vez que uma cor é vinculada a uma entidade (um método, uma característica, uma condição), reutilize essa cor exata para cada marca que representa essa entidade em toda a figura — linha, preenchimento, marcador, texto, linha de heatmap. Cor é a referência cruzada; um leitor nunca deve ter que consultar uma legenda duas vezes.
4.2 Limitar matizes. Use o mínimo de matizes distintas que os dados exigirem.
Quando a figura compara uma série focal contra outras, torne a série focal
visualmente dominante (saturada, peso mais pesado) e renderize os comparadores com peso
visual menor (dessaturados, mais claros ou mais finos). O matiz focal não deve coincidir
com nenhum matiz em uma paleta categórica usada na mesma figura. A série focal
deve permanecer identificável mesmo quando sua marca tem largura zero ou coincidente com outras —
via contorno, marcador ou uma faixa levemente tingida. Use focal_palette(...) para vincular as
cores focal e de comparador aos rótulos ordenados.
4.3 Categorias hierárquicas. Quando categorias aninham (grupos dentro de grupos), o nível externo escolhe a família de matizes e o nível interno amostra dentro dela.
4.4 Contínuo e divergente. Use um mapa sequencial perceptualmente uniforme para valores contínuos genéricos; uma rampa de matiz único para classificação ordinal ou tamanho; um mapa divergente para quantidades com sinal — sempre centrado no zero semanticamente significativo (0, 1.0 ou mediana), nunca no ponto médio dos dados.
4.5 Segurança CVD. Nunca confie em um contraste vermelho/verde para uma distinção binária ou oposta. Qualquer par binário deve permanecer distinguível em simulação de deuteranopia. Reserve um matiz de alarme para marcas de erro/anomalia/perturbação e não o reutilize como cor de série de dados.
4.6 Duas paletas, duas legendas. Quando uma figura usa dois sistemas de cores categóricas, cada legenda fica adjacente ao primeiro painel onde sua paleta se aplica.
§5 Tipografia
5.1 Títulos de frase. Um título de painel afirma a comparação em linguagem simples, peso normal, alinhado à esquerda. Nomes de métricas vão no eixo, não no título.
5.2 Escada de tamanho mapeada por função. Uma figura usa no máximo três tamanhos
de fonte, mapeados para função, não espaço: títulos/rótulos de eixos/identidade de série no
tamanho base; texto de legenda/anotação um passo abaixo; rótulos de tick mais um passo
abaixo. Letras de painel são a única exceção (negrito, maior). Se um rótulo não couber no
tamanho de sua função, corrija o layout ou encurte o texto — não use um
tamanho intermediário. apply_figure_style(sizes=(8,7,6)) define a escada. Quando umalinha de metadados secundária for necessária, construa o texto de duas linhas com
two_tier_label(name, meta).
5.3 Nomenclatura. Nomes de espécies, genes e variáveis que a convenção científica itálico são itálico. Códigos abreviados herdam a regra; expanda uma vez na primeira aparição.
5.4 Sufixos de magnitude. Contagens grandes usam k / M / B (4,2B, 120 kb),
não numerais completos agrupados por vírgulas.
5.5 Anotações numéricas. Números na marca usam no máximo 2 algarismos significativos — a menos que o arredondamento para 2 algarismos significativos fizesse duas linhas distintas imprimir o mesmo valor, caso em que mostre o dígito que as separa. O texto em uma marca preenchida atinge contraste ≥4,5:1; se não atingir, coloque o texto fora da marca.
5.6 Sem códigos internos. Rótulos de eixos usam nomes em linguagem simples; abreviações do código-fonte aparecem apenas entre parênteses após o nome legível ou na legenda. Séries de comparadores são rotuladas pelo que são, não por uma palavra funcional.
5.7 Letras de painel. Negrito, canto superior esquerdo, fora da caixa de eixos. Caixa
alta ou baixa segue a convenção do veículo alvo; panel_letter(ax, 'a', case=...) lida
com qualquer uma.
§6 Orientação de família de gráficos (por formato de dados)
6.1 Categórico × numérico. Mostre a distribuição, não apenas o resumo.
A escolha do gráfico segue n: strip com jitter e um tick de mediana para n pequeno; box
ou violino para n grande; barra + pontos brutos sobrepostos ou barra + intervalo quando a média é
a mensagem. Use strip_with_median(...) para a forma de strip com jitter e
bar_with_points(...) para barras com pontos brutos ou um intervalo. O
intervalo errorbar='ci95' é o IC de 95% da distribuição t da média (meia largura
t_{0,975,n−1}·s/√n), portanto é válido para n pequeno. Barras de erro e sobreposições de pontos brutos
são alternativas — mostrar ambos é geralmente redundante. Uma categoria
ausente de um grupo é marcada (n/d, — ou um fantasma hachurado) em seu lugar;
um slot vazio é lido como zero. Uma barra com valor zero recebe um toco ou ponto visível
na linha de base.
6.2 Categorias de observação única. Um ponto preenchido com uma haste neutra fina até o zero semântico (picolé). Rótulos de valor ficam ao lado do ponto.
Os auxiliares de plotagem agrupados exigem observações reais finitas unidimensionais não vazias em
cada grupo fornecido. Eles rejeitam grupos vazios e NaN/Inf antes de
desenhar: resolva exclusões explicitamente, relate o n retido e adicione um marcador de categoria
ausente separadamente quando apropriado. Eles não descartam silenciosamente observações ausentes.
Matrizes mascaradas com observações excluídas são rejeitadas antes da
conversão; matrizes sem entradas mascaradas permanecem válidas.
Intervalos SD/IC solicitados exigem pelo menos duas observações por
grupo; para uma única observação, use pontos sem um intervalo. Os rótulos e os
grupos de dados devem estar alinhados. Para strip_with_median, sequências de cores não vazias circulam;
None ou uma sequência vazia usa cinza padrão.
Uma sequência de cores de barra vazia usa a cor de barra padrão do Matplotlib; uma sequência base focal_palette
vazia usa o ciclo de cores padrão.
6.3 Séries contínuas. Média por x como uma linha com marcadores; execuções individuais como
linhas finas translúcidas ou pontos atrás dela. Rotule cada série com texto direto
na extremidade direita de sua linha, de preferência a uma caixa de legenda;
end_of_line_labels(...) coloca esses rótulos. Glifos de resumo (média/mediana
por bin) usam uma forma que não pode ser confundida com uma observação bruta,
idêntica entre séries, desenhada abaixo dos pontos brutos em ordem z.
end_of_line_labels valida contagens de série/rótulo e comprimentos x/y correspondentes não vazios
antes de adicionar rótulos. Os pontos finais devem ser finitos; lacunas internas podem permanecer.
Ele acessa o final de cada sequência indexada sem copiar a série completa.
Sequências de cores não vazias circulam; None ou uma sequência vazia usa a cor de texto padrão
atual. As letras dos painéis devem ser únicas para panel_crops.
6.4 Distribuições em suporte compartilhado. Quando duas distribuições se sobrepõem fortemente, empilhe-as como pequenos painéis com um eixo x compartilhado ou use uma crista. Sobreponha apenas quando a separação for visualmente clara.
6.5 Matrizes. Quando um heatmap é pequeno o suficiente para ler (< ~200 células), imprima o valor em cada célula. Indique o limite uma vez no rótulo da barra de cores.
6.6 Embeddings. Dispersões de redução de dimensionalidade (UMAP, t-SNE, PCA) removem marcas e rótulos de tick; um par de setas de canto pequenas nomeia os eixos. Os clusters são rotulados por linhas de líder finas para texto em espaço em branco ao redor.
6.7 Predição pareada vs. observação. Empilhe os dois como faixas adjacentes com x e cor idênticos; deixe o alinhamento carregar a comparação.