Que fait diagramme-mécanisme-voie-biologique ?
Une figure de voie est un énoncé de mécanisme que les lecteurs contesteront une arête à la fois. Le contrat de cette compétence : chaque entité et chaque arête sur le canevas remonte à une citation textuelle avec une localisation ; la sémantique d'interaction (activation / inhibition / liaison / modification / transport) est visuellement distincte et jamais confondue ; tout ce que la source ne précise pas (direction, localisation, nombres) est marqué visiblement comme non précisé, non deviné. Les livrables sont un SVG éditable en couches avec identifiants, plus des exportations PNG/PDF et un fichier result.json complet respectant le contrat.
Quand l'utiliser / quand ne pas l'utiliser
Utiliser pour : figures de mécanismes, diagrammes de voies de signalisation, cascades récepteur-noyau, interactions entre voies, tâches « dessiner la figure N de cet article » et modifications d'une figure de voie existante (ajouter/supprimer une entité ou une arête, réétiqueter). Ne pas utiliser pour : graphiques statistiques (barres/boîtes/volcan), schémas expérimentaux ou retouches purement esthétiques ; ceux-ci relèvent de compétences adjacentes.
Contrat d'exécution (environnement d'exécution de la plateforme)
- Entrée :
/input/case.json(+ task.md). Travail sous/app/work; livrables sous/app/output. - Première action de l'ensemble de l'exécution (avant de lire le cas en profondeur) :
python scripts/scaffold_result.py --input /input/case.json --outdir /app/outputCeci écrit unresult.jsonavec tous les champs du contrat de sortie présents, les non produits étant null + raison. Mettez-le à jour progressivement ; ne supprimez jamais un champ du contrat. - Tous les scripts ci-dessous prennent des chemins de style
--model/--svget sont en Python 3 pur (stdlib uniquement) sauf indication contraire.references/est lu par les scripts ; lisez vous-même les fichiers.mdavant l'étape 1.
Étape 0 – Lire le contrat et préparer la structure (1 requête)
Exécutez le script de préparation. Parcourez task.md + case.json : identifiez la figure cible (quel mécanisme, quelle figure s'il s'agit d'une reproduction, scénario de génération ou d'édition), les formats d'exportation requis et le périmètre des preuves. Enregistrez la liste des champs du contrat que vous devez remplir. Conscience budgétaire : visez à terminer en 5 à 8 étapes du modèle ; les scripts effectuent le gros du travail, vous faites la science.
Étape 1 – Extraire le modèle du mécanisme (le noyau scientifique – faites-le vous-même)
Lisez le matériel réel (analysez le PDF pour de vrai ; lisez les fichiers, ne présupposez jamais le contenu à partir des étiquettes). Construisez /app/work/model.json selon references/layout-conventions.md par VOTRE PROPRE jugement :
- Entités — gène / protéine / récepteur / ARN / complexe / molécule / cellule / famille. Appliquez
references/naming-rules.md: symboles de gènes en italique et nœuds de gènes distincts de leurs protéines (MYC vs MYC) ; symboles préférés avec orthographes sources en synonymes ; familles vs membres ; un nœud par complexe mentionné. Chaque entité portesource : {loc, citation}— une citation TEXTUELLE et une localisation assez précise pour être retrouvée (section/paragraphe/page/légende de figure). - Arêtes — type parmi l'ensemble fermé dans
references/edge-types.json(activation, inhibition, liaison, phosphorylation, ubiquitination, régulation_transcriptionnelle, translocation, formation_complexe, ...).directeddoit être défini explicitement. Ne devinez jamais la direction : si la citation n'a pas d'indice directionnel, définissezdirected : falseet enregistrez une incertitude (references/uncertainty-policy.md). La liaison/recrutement est non dirigé. La régulation transcriptionnelle cible un nœud de gène et nécessite un signe. - Compartiments — extracellulaire / membrane / cytoplasme / noyau (+ RE, Golgi, sous-régions d'organite si le mécanisme les nécessite). Les entités dont la localisation n'est pas spécifiée vont dans la bande
non spécifié– jamais silencieusement dans le cytoplasme. Les récepteurs s'ancrent sur la bande membranaire. - Ordre — définissez
orderpar position dans la voie (ordre topologique, pas ordre textuel) ; les boucles de rétroaction apparaissent naturellement comme des arêtes arrière. - Les nombres sur le canevas (expression, significativité) uniquement s'ils existent textuellement dans la source ; sinon, laissez les mappages de données comme null explicites.
Ordre pratique d'extraction : lisez une fois pour le flux global ; deuxième passage phrase par phrase pour les entités + citations ; troisième passage pour les arêtes, y compris les inhibiteurs, la rétroaction et les interactions entre voies (ils se cachent dans les phrases « cependant/alors que »).
Étape 2 – Valider le modèle (script)
python scripts/validate_model.py --model /app/work/model.json \
--report /app/work/validation-report.json
Corrigez chaque erreur E-*. E-DIR-01 (arête dirigée sans indice directionnel) est le garde-fou scientifique central : soit citez une phrase qui énonce la direction, soit rétrogradez en non dirigé + incertitude. Les avertissements nécessitent une décision consciente : nœuds de famille, placement des récepteurs, décalages signe-vs-citation. Relancez jusqu'à ce que ce soit valide. Si le matériel ne peut pas prendre en charge un élément requis du contrat, notez-le maintenant (cela deviendra un null + raison à l'étape 5).
Étape 3 – Rendu SVG et exportation (scripts)
python scripts/render_svg.py --model /app/work/model.json \
--out /app/output/pathway.svg --report /app/work/render-report.json
python scripts/export_assets.py --svg /app/output/pathway.svg \
--outdir /app/output --model /app/work/model.json \
--png-width 2400 --report /app/work/export-report.json
Lisez les avertissements du rapport de rendu (limites du canevas, compartiments inconnus). Regardez le PNG vous-même ; si la mise en page obscurcit le mécanisme (croisements d'arêtes cachant une bifurcation, rétroaction sur la cascade), ajustez order/positions d'ancrage dans le modèle et refaites le rendu. Le SVG est déterministe : modèle identique → SVG identique.
Étape 4 – Scénarios d'édition (si le cas demande des modifications d'une figure existante)
Reconstruisez d'abord le modèle de la figure cible (étape 1 sur le texte source de la figure originale), puis utilisez des modifications préservant la source – le modèle/SVG original sont sauvegardés, chaque modification est enregistrée dans le change_log du modèle :
python scripts/apply_edit.py --model /app/work/model.json --op add-edge \
--id e-new --src A --tgt B --type inhibition --directed true \
--sign negative --loc "..." --quote "..."
Opérations : ajouter/renommer/supprimer une entité (supprimer refuse lorsque des arêtes sont attachées sauf si --cascade, et les suppressions en cascade sont enregistrées comme incertitudes), ajouter/supprimer une arête, ajouter un compartiment. Chaque entité/arête ajoutée REQUIERT --loc + --quote textuels. Après les modifications, revalidez (automatique) et refaites le rendu (étape 3).
Étape 5 – Vérifier et finaliser result.json (script + vous)
python scripts/verify_outputs.py --model /app/work/model.json \
--svg /app/output/pathway.svg --result /app/output/result.json \
--exports /app/output/pathway.png /app/output/pathway.pdf \
--report /app/output/verification-report.json
Ceci relit le SVG et vérifie la relecture des nœuds/arêtes, la cohérence légende↔utilisation dans les deux sens, le débordement d'étiquettes, les limites du canevas, l'existence des exportations, et que chaque null dans result.json a une raison. Puis finalisez result.json vous-même : remplissez les champs du contrat (chemins editable_source, exportations avec backend/paramètres, entity_table/edge_table avec citations, legend_basis, sources avec versions, incertitudes, résumé de vérification, statut honnête). Conservez _unanswered_reasons pour tout ce qui est null. Une livraison partielle doit énoncer ses limites en termes clairs.
Gestion des exceptions (chemins réels, pas de décoration)
| Échec | Détection | Action |
|---|---|---|
| PDF illisible / pas de couche texte | l'analyse échoue ou texte vide | pdf-render-tool / ocr-tool pour le rendu, signaler « couche texte absente » dans result.json |
| Nom d'entité ambigu (deux lectures) | votre extraction | choisir selon le contexte, enregistrer l'alternative + incertitude ; si indécidable, null + raison |
| Direction non précisée | E-DIR-01 | rétrograder en arête non dirigée (pas de pointe de flèche) + incertitude. NE JAMAIS deviner |
| Compartiment inconnu | E-CMP-01 / avertissement de mise en page | bande non spécifié + note |
| Données numériques manquantes pour les visuels encodés en données | le modèle n'a pas de nombres textuels | dessiner la topologie, marquer le mappage null + « données absentes de la source » |
| Débordement d'étiquette | vérifier label_overflow | raccourcir l'étiquette / diviser en étiquette+sous-étiquette / réordonner |
| Canevas dépasse les limites | avertissement de rendu | diviser en panneaux ou réduire les branches ; le noter |
| Backend d'exportation manquant | état du rapport d'exportation échoué | la chaîne de repli a déjà été essayée ; livrer le SVG, enregistrer l'échec + des conseils dans result.json |
| PNG vierge/dégénéré | blank_check | enquêter sur le rapport de rendu ; refaire le rendu ; enregistrer |
| Erreurs de validation persistantes | code de sortie 2 | corriger le modèle ; si impossible à corriger à partir du matériel, livrer le sous-ensemble valide + limites explicites |
Niveau de qualité (auto-vérification avant de terminer)
- Un relecteur pourrait-il pointer n'importe quelle flèche et obtenir sa justification textuelle à partir du tableau intégré / du modèle ? (traçabilité)
- L'activation/l'inhibition/la liaison/la modification sont-elles visuellement distinctes, et la légende correspond-elle à ce qui est dessiné – aucune entrée manquante, aucune entrée fantôme ?
- Tout ce qui n'est pas précisé est-il visiblement non précisé (non dirigé, bande non spécifiée, null + raison) ?
- Quelqu'un peut-il ouvrir le SVG, changer une étiquette et réexporter ? (en couches, adressable par identifiant, pile de polices standard)
result.jsoncouvre-t-il chaque champ du contrat avec un statut honnête ?
Fichiers
scripts/scaffold_result.py– result.json complet du contrat avec null+raisonscripts/validate_model.py– schéma + vérifications direction-preuve + nommagescripts/render_svg.py– SVG déterministe en couches à partir de model.jsonscripts/export_assets.py– PNG/PDF avec chaîne de repli + vérification de blancscripts/apply_edit.py– modifications préservant la source, enregistréesscripts/verify_outputs.py– vérification par relecture de l'ensemblereferences/edge-types.json– sémantique des symboles lisible par machinereferences/symbol-semantics.md– grammaire visuelle et son raisonnementreferences/naming-rules.md– conventions pour gène/protéine/famille/complexereferences/uncertainty-policy.md– règles de rétrogradation ; politique de non-devinettereferences/layout-conventions.md– schéma de model.json + algorithme de mise en pageexamples/ras-mapk-case/– un exemple concret avec matériel réel (Brown & Ried 2022)README.md– documentation d'utilisation autonome