Règles pour figures de qualité publication
Une check-list pour des figures scientifiques correctes, lisibles et internellement cohérentes. Cette compétence n'impose pas de style visuel maison — le cadre, la police et la palette sont des paramètres. Avant de tracer, suivez l'appel de notebook ci-dessous et invoquez apply_figure_style().
Appel de notebook open-science
Toute requête notebook_execute dont le code utilise une fonction nommée dans cette compétence inclut cet identifiant de compétence :
{ "kernelSkillIds": ["figure-style"], "code": "apply_figure_style()\n..." }
kernelSkillIds contient l'identifiant de la compétence ; les appels de fonction appartiennent à code. Cette requête est complète telle qu'écrite : appelez les fonctions nommées directement et n'ajoutez pas d'étape d'importation ou de découverte.
§0 Portée
Déclencheur de charge (même règle que la section "Graphiques de qualité publication" de l'invite système) : cette compétence est destinée aux figures livrables finales — celles publiées dans un rapport, un article ou une exportation, ou sauvegardées comme un artefact que l'utilisateur conservera — et non aux tracés exploratoires/intermédiaires (vues rapides, EDA, vérifications de vraisemblance), qui sont dessinés simplement sans elle. Une fois chargée, "chaque graphique" ci-dessous signifie chaque graphique que vous rendez pour le livrable.
Les §1–§3, §8 et §9 concernent la correction — ils s'appliquent à chaque graphique, dans chaque contexte, et n'ont aucun contenu esthétique. Les §4–§7 sont des directives — valeurs par défaut qui produisent un résultat propre mais qu'une alternative délibérée peut remplacer (les règles individuelles à l'intérieur de §4–§7 qui énoncent un invariant factuel/perceptuel — par exemple §4.4 centrage du zéro sémantique, §4.5 daltonisme, §6.9 ancrage du leader — restent contraignantes). À elle seule, cette compétence est le niveau interne (rendre un graphique bon) ; compositeur-de-figures et narratif-d-article fournissent le contexte multi-panneaux et d'article entier.
§1 Fidélité des données et auto-cohérence
1.1 Lignes exclues. Une ligne marquée comme exclue ou signalée dans les données source est soit omise entièrement, soit dessinée avec un marqueur ouvert/hatché visuellement distinct et nommée dans la légende. Elle n'entre jamais dans une statistique récapitulative tracée à côté des lignes incluses.
1.2 Conditions comparables uniquement. Les bras mesurés dans des conditions non comparables (N différent, budget d'époque, initialisation, protocole) ne sont pas tracés comme des pairs visuels. Séparez-les par un saut de facette ou un marqueur sur l'étiquette, et indiquez la différence une fois dans la légende.
1.3 Auto-cohérence. Chaque clé, seuil et titre à l'intérieur de la figure doit être satisfait par chaque ligne tracée. Avant de sauvegarder, parcourez chaque étiquette de résultat catégoriel jusqu'à la règle qui la définit ; si la valeur d'une ligne contredit son étiquette ou le titre, la figure est erronée, pas les données.
1.4 Les titres-affirmations doivent être vrais. Un titre-phrase (§5.1) est testé par rapport à chaque catégorie sur l'axe avant le rendu. Si l'une le contredit, qualifiez le titre ("sur 3 des 4 paires") ou rétrogradez-le en description.
1.5 Indiquez n et ce qui a été maintenu fixe. Chaque panneau qui dessine une marque récapitulative indique n et l'unité de réplication, et chaque petit multiple qui maintient une variable fixe indique la valeur fixée — dans le panneau ou, lorsque le budget du §2 est serré, dans la légende.
1.6 La structure de référence est une référence. Un arbre, un ordre ou une topologie dessiné comme contexte (une barre d'échelle, une bande de catégorie) utilise une référence établie, et non une inférée à partir des données tracées. N'inférez la structure que lorsqu'elle est le résultat.
1.7 Un nombre par affirmation. Une affirmation quantitative (temps d'exécution, précision, nombre) a exactement une valeur canonique à travers chaque panneau, légende et résumé. Définissez ce qu'elle mesure et utilisez cette valeur partout.
§2 Économie des étiquettes — plancher et plafond
La figure montre le motif ; la légende porte le contexte. Concevez pour un lecteur scientifique général, pas pour l'auteur.
2.1 Plancher (non supprimable). Chaque marque, série, glyphe ou comparateur distinct doit être identifiable à partir de la figure seule. La légende explique pourquoi cela importe, pas ce que c'est. Une étiquette est non supprimable si sa suppression laisse un lecteur demander "qu'est-ce que c'est ?" ; elle n'est supprimable que si la question devient "pourquoi est-ce là ?". Les étiquettes de comparateur nomment la chose ("méthode antérieure", "pas d'entraînement conjoint"), jamais un mot de rôle nu ("référence", "précédent"). Tout terme qu'un scientifique général ne peut pas analyser reçoit un glossaire d'un mot.
2.2 Plafond. Par panneau : titre + étiquettes d'axe + étiquettes de graduation + identité de série (étiquetée une fois par ligne de petits multiples) + au plus 2–3 annotations de résultat. Comptez les chaînes ; >6 au-delà des axes/graduations signifie que vous dépassez. Le plafond compte les annotations narratives (appels, étiquettes de valeur, parenthèses) — les étiquettes d'identité font partie du plancher, pas du budget.
2.3 Déplacez vers la légende : n=, ce-qui-est-maintenu-fixe, expansions des abréviations, notes de bas de page non comparables, justification d'exclusion, réserves méthodologiques.
2.4 Les titres sont des points à retenir. Un lecteur ne voyant que le titre sait ce que montre le panneau. "Robuste à la perte de gènes" passe ; "Moins de gènes" échoue. Test : lisez-le à voix haute à froid — si l'auditeur demande "moins de gènes quoi ?", réécrivez. Pour une ligne de petits multiples qui font varier une chose, abandonnez les titres par panneau pour un en-tête de ligne.
2.5 Valeur-sur-marque uniquement pour le nombre clé — celui qu'un lecteur citerait. Tout le reste se lit sur l'axe.
2.6 En cas de doute, supprimez l'étiquette et relisez. Si le message survit, elle reste supprimée.
§3 Axes, échelles, petits multiples
Lorsqu'un axe existant a besoin d'un cadre différent du réglage général de la figure, appelez set_frame(ax, style=...).
3.1 Marge des axes. Les limites des axes dépassent les données d'au moins un rayon de marqueur de chaque côté ; les marqueurs et le texte ne touchent jamais une arête. ax.margins(0.04) après le tracé, ou étendez la limite au-delà de toute annotation.
3.2 Ruptures d'axe sur plage gaspillée. Lorsque les données occupent <40 % d'un axe, rompez l'axe ou commencez-le au plancher des données avec une graduation claire non nulle. Ne dessinez jamais de ligne de référence, seuil ou annotation à l'intérieur d'un espace de rupture d'axe — l'espace n'a pas de coordonnée.
3.3 Les axes logarithmiques reçoivent des graduations lisibles — 10², 10³, ou 1k / 10k / 100k, pas des exposants bruts. Ne dessinez jamais de barres remplies sur un axe de valeurs logarithmique (la longueur de la barre code le rapport à un plancher arbitraire) ; utilisez plutôt des points + une coche médiane.
3.4 Axes partagés entre petits multiples. Une ligne ou colonne de petits multiples affiche les étiquettes de graduation une fois (panneau le plus à gauche / le plus en bas) ; les panneaux intérieurs gardent les graduations mais abandonnent les étiquettes. Lorsque les panneaux partagent un axe y et ne diffèrent que par la variable x, rendez-les comme des sous-graphes contigus (wspace≤0.06) avec un titre d'en-tête de ligne.
3.5 Remplissez la boîte. L'enveloppe de données d'un panneau occupe ≥75 % de son rectangle alloué. Si le rapport d'aspect naturel d'un panneau laisse des bandes mortes, remodelez la grille (fusion de lignes, panneaux complémentaires empilés) — ne rembourrez pas le panneau.
3.6 Direction de la bonté. Lorsque plus-élevé-ou-plus-bas-est-meilleur n'est pas évident à partir de l'étiquette de l'axe, placez un petit indice droit ("plus élevé = meilleur") dans la marge — une fois par ligne de panneaux, jamais par panneau, et jamais uniquement dans la légende. Un glyphe directionnel intégré dans du texte pivoté tourne avec lui ; définissez l'indice droit. goodness_arrow(ax, ...) place cet indice.
3.7 Largeur physique. Une figure à une seule rangée à 300 dpi correspond à la largeur double colonne du lieu. L'ajout d'un schéma ou d'étiquettes ne rend pas les panneaux de données plus étroits qu'avant.
§4 Couleur
4.1 Threading. Une fois qu'une couleur est liée à une entité (une méthode, une caractéristique, une condition), réutilisez cette couleur exacte pour chaque marque représentant cette entité à travers la figure — ligne, remplissage, marqueur, texte, ligne de heatmap. La couleur est la référence croisée ; un lecteur ne devrait jamais avoir à consulter une légende deux fois.
4.2 Limiter les teintes. Utilisez aussi peu de teintes distinctes que les données l'exigent. Lorsque la figure compare une série focale à d'autres, rendez la série focale visuellement dominante (saturée, poids plus lourd) et rendez les comparateurs avec un poids visuel plus faible (désaturé, plus clair ou plus fin). La teinte focale ne doit pas coïncider avec une teinte d'une palette catégorielle utilisée dans la même figure. La série focale doit rester identifiable même lorsque sa marque a une largeur nulle ou coïncide avec d'autres — via un contour, un marqueur ou une bande légèrement teintée. Utilisez focal_palette(...) pour lier les couleurs focales et comparatrices aux étiquettes ordonnées.
4.3 Catégories hiérarchiques. Lorsque les catégories s'imbriquent (groupes dans des groupes), le niveau externe choisit la famille de teintes et le niveau interne échantillonne à l'intérieur.
4.4 Continu et divergent. Utilisez une carte séquentielle perceptuellement uniforme pour les valeurs continues génériques ; un gradient monochrome pour le rang ordinal ou la taille ; une carte divergente pour les quantités signées — toujours centrée au zéro sémantiquement significatif (0, 1.0 ou médiane), jamais au milieu des données.
4.5 Sécurité daltonisme (CVD). Ne comptez jamais sur un contraste rouge/vert pour une distinction binaire ou opposée. Toute paire binaire doit rester distinguable dans une simulation de deutéranopie. Réservez une teinte d'alarme pour les marques d'erreur/anomalie/perturbation et ne la réutilisez pas comme couleur de série de données.
4.6 Deux palettes, deux légendes. Lorsqu'une figure utilise deux systèmes de couleurs catégorielles, chaque légende se trouve à côté du premier panneau où sa palette s'applique.
§5 Typographie
5.1 Titres-phrases. Un titre de panneau énonce la comparaison en langage simple, poids régulier, aligné à gauche. Les noms de métriques vont sur l'axe, pas dans le titre.
5.2 Échelle de taille liée au rôle. Une figure utilise au plus trois tailles de police, liées au rôle et non à l'espace : titres/étiquettes-d'axe/identité-de-série à la taille de base ; texte de légende/annotation une taille en dessous ; étiquettes de graduation encore une taille en dessous. Les lettres de panneau sont la seule exception (gras, plus grandes). Si une étiquette ne tient pas à la taille de son rôle, corrigez la disposition ou raccourcissez le texte — n'utilisez pas de taille intermédiaire. apply_figure_style(sizes=(8,7,6)) définit l'échelle. Lorsqu'une ligne de métadonnées secondaire est nécessaire, construisez le texte sur deux lignes avec two_tier_label(name, meta).
5.3 Nomenclature. Les noms d'espèces, gènes et variables que la convention scientifique met en italique sont en italique. Les codes abrégés héritent de la règle ; développez une fois à la première apparition.
5.4 Suffixes de magnitude. Les grands nombres utilisent k / M / B (4,2B, 120 kb), pas de chiffres complets groupés par virgules.
5.5 Annotations numériques. Les nombres sur les marques utilisent au plus 2 chiffres significatifs — à moins que l'arrondi à 2 chiffres significatifs ne fasse apparaître la même valeur pour deux lignes distinctes, auquel cas montrez le chiffre qui les sépare. Le texte sur une marque remplie atteint un contraste ≥4,5:1 ; si ce n'est pas le cas, placez le texte à l'extérieur de la marque.
5.6 Pas de codes internes. Les étiquettes d'axe utilisent des noms en langage clair ; les abréviations de codebase n'apparaissent qu'entre parenthèses après le nom lisible ou dans la légende. Les séries comparatrices sont étiquetées avec ce qu'elles sont, pas un mot de rôle.
5.7 Lettres de panneau. Grasse, en haut à gauche, en dehors de la boîte des axes. La casse suit la convention du lieu cible ; panel_letter(ax, 'a', case=...) gère les deux.
§6 Guide par forme de données (par type de graphique)
6.1 Catégoriel × numérique. Montrez la distribution, pas seulement le résumé. Le choix du graphique suit n : bande avec points aléatoires et une coche médiane pour petit n ; boîte ou violon pour grand n ; barre + points bruts superposés ou barre + intervalle lorsque la moyenne est le message. Utilisez strip_with_median(...) pour la forme de bande aléatoire et bar_with_points(...) pour les barres avec points bruts ou un intervalle. L'intervalle errorbar='ci95' est l'intervalle de confiance à 95 % de la distribution t de la moyenne (demi-largeur t_{0,975,n−1}·s/√n), donc il est valide pour petit n. Les barres d'erreur et les superpositions de points bruts sont des alternatives — montrer les deux est généralement redondant. Une catégorie absente d'un groupe est marquée (n.d., —, ou un fantôme hachuré) à son emplacement ; un emplacement vide se lit comme zéro. Une barre de valeur zéro reçoit un bout visible ou un point sur la ligne de base.
6.2 Catégories à une seule observation. Un point rempli avec une fine tige neutre jusqu'au zéro sémantique (sucette). Les étiquettes de valeur se trouvent à côté du point.
Les helpers de tracé groupés nécessitent des observations réelles non vides, unidimensionnelles et finies dans chaque groupe fourni. Ils rejettent les groupes vides et NaN/Inf avant de dessiner : résolvez les exclusions explicitement, signalez le n retenu et ajoutez un marqueur de catégorie manquante séparément si approprié. Ils ne suppriment pas silencieusement les observations manquantes. Les tableaux masqués avec des observations exclues sont rejetés avant la conversion ; les tableaux sans entrées masquées restent valides.
Les intervalles SD/IC demandés nécessitent au moins deux observations par groupe ; pour une seule observation, utilisez des points sans intervalle. Les étiquettes et les groupes de données doivent correspondre. Pour strip_with_median, les séquences de couleurs non vides cyclent ; None ou une séquence vide utilise le gris par défaut.
Une séquence de couleurs de barre vide utilise la couleur de barre par défaut de Matplotlib ; une séquence focal_palette de base vide utilise le cycle de couleurs par défaut.
6.3 Séries continues. Moyenne-par-x sous forme de ligne avec marqueurs ; courses individuelles sous forme de lignes fines translucides ou de points derrière elle. Étiquetez chaque série avec du texte direct à l'extrémité droite de sa ligne de préférence à une boîte de légende ; end_of_line_labels(...) place ces étiquettes. Les glyphes résumés (moyenne/médiane par bac) utilisent une forme qui ne peut pas être confondue avec une observation brute, identique d'une série à l'autre, dessinée en dessous des points bruts dans l'ordre z.
end_of_line_labels valide les nombres de séries/étiquettes et les longueurs x/y correspondantes non vides avant d'ajouter les étiquettes. Les extrémités doivent être finies ; les écarts internes peuvent rester. Il accède à l'extrémité de chaque séquence indexée sans copier la série entière. Les séquences de couleurs non vides cyclent ; None ou une séquence vide utilise la couleur de texte par défaut actuelle. Les lettres de panneau doivent être uniques pour panel_crops.
6.4 Distributions sur support partagé. Lorsque deux distributions se chevauchent fortement, empilez-les comme de petits panneaux avec un axe x partagé ou utilisez une crête. Superposez uniquement lorsque la séparation est visuellement claire.
6.5 Matrices. Lorsqu'une heatmap est assez petite pour être lue (< ~200 cellules), imprimez la valeur dans chaque cellule. Indiquez le seuil une fois dans l'étiquette de la barre de couleur.
6.6 Plongements. Les nuages de réduction de dimensionnalité (UMAP, t-SNE, PCA) abandonnent les graduations et les étiquettes de graduation ; une petite paire de flèches dans le coin nomme les axes. Les clusters sont étiquetés par des lignes de repère fines vers du texte dans l'espace blanc environnant.
6.7 Prédiction appariée vs observation. Empilez les deux comme des pistes adjacentes avec x et couleur identiques ; laissez l'alignement porter la comparaison. Cible