Structures de protéines : marquer des résidus dans 3Dmol.js ou Mol*

Affichez des structures mmCIF, BinaryCIF ou PDB dans Potato avec une coloration par pLDDT et une table des résidus, et enregistrez des sites de liaison, des épitopes ou des résidus d'interface.

Nouveau dans la v2.12.0

L'affichage protein_structure présente une structure macromoléculaire dans le navigateur, et les annotateurs sélectionnent des résidus en cliquant dessus dans la vue 3D ou dans une table des résidus placée en dessous. Un schéma viewer_selection stocke la sélection, par exemple un site de liaison, un épitope, une région jugée désordonnée, des résidus situés à une interface, ou des résidus où un modèle prédit semble erroné. Les autres questions sur l'item, comme une note ou un commentaire, se placent dans des schémas ordinaires à côté.

L'affichage trace une représentation en cartoon, montre les ligands en bâtonnets (les ions monoatomiques en sphères), et trace chaque résidu sélectionné en bâtonnets dans la couleur de son étiquette. Il peut colorer le cartoon selon la confiance du modèle (pLDDT) et afficher une image PAE à côté de la structure.

Formats : mmCIF (.cif, .mmcif), BinaryCIF (.bcif) et PDB (.pdb, .ent), chacun éventuellement compressé en gzip. Prévoyez les nouveaux projets autour de mmCIF : à partir du 2027-07-21, les nouvelles entrées de la PDB reçoivent des identifiants de 12 caractères et ne sont distribuées qu'en mmCIF. Le serveur ne lit BinaryCIF que si le paquet msgpack est installé ; sans lui, la table des résidus n'est pas disponible, mais la vue 3D fonctionne toujours.
Moteurs : 3dmol (par défaut) utilise 3Dmol.js 2.5.5, fourni avec Potato. molstar utilise Mol* 5.12.0, qui pèse environ 5 Mo et s'installe avec potato vendor fetch molstar. Les deux ont besoin de WebGL.
Sans WebGL, la vue 3D affiche un message et la table des résidus fonctionne toujours.
Hors ligne par défaut : une structure est lue depuis le répertoire des médias. Une URL, comme un fichier d'AlphaFold DB ou de la RCSB, n'est chargée que si l'affichage définit allow_remote: true, et c'est alors le navigateur de l'annotateur qui la récupère, et non le serveur Potato.

Configuration

yaml

media_directory: media
data_files: [data/structures.json]
item_properties: {id_key: id, text_key: note}
 
instance_display:
  fields:
    - key: note
      type: text
    - key: structure            # item field holding the file path
      type: protein_structure
      label: "Structure"
      display_options:
        engine: 3dmol
        height: 440
        plddt: true             # colour by B-factor read as pLDDT
        pae_field: pae          # item field holding a PAE image
 
annotation_schemes:
  - annotation_type: viewer_selection
    name: binding_site
    description: "Select the residues that form the binding site"
    viewer_field: structure
    labels: ["ligand contact", "interface"]
    min_selections: 1
    max_selections: 12
    label_requirement:
      required: true
 
  - annotation_type: radio
    name: site_confidence
    description: "How clear is the site in this model?"
    labels: ["Clear", "Plausible", "Unsupported"]

Chaque item désigne son fichier de structure par un chemin relatif à media_directory :

json

{"id": "model_1", "note": "...", "structure": "structures/model_1.cif", "pae": "structures/model_1_pae.png"}

Option d'affichage	Valeur par défaut	Signification
`engine`	`3dmol`	`3dmol` ou `molstar`
`height`	`420`	Hauteur de la vue 3D, en pixels ou sous forme de longueur CSS
`format`	d'après l'extension	`cif`, `bcif` ou `pdb`, pour un fichier dont le nom ne l'indique pas
`color_by`	`chain`	`chain`, `spectrum` (de l'extrémité N à l'extrémité C) ou `secondary`. Ignoré quand `plddt` est activé
`plddt`	`false`	Colore le cartoon selon la colonne du facteur B lue comme pLDDT, dans les quatre bandes d'AlphaFold. Les valeurs écrites entre 0 et 1 sont mises à l'échelle
`pae_field`	aucune	Un champ de l'item contenant une image, comme un graphique PAE, affichée à côté de la structure
`show_ligands`	`true`	Trace les groupes HETATM autres que l'eau
`residue_table`	`true`	Affiche la table des résidus
`residue_table_limit`	`3000`	Au-delà de ce nombre de résidus, la table est remplacée par une note, et les résidus se sélectionnent dans la vue 3D
`allow_remote`	`false`	Permet au navigateur de charger une URL http(s) indiquée dans l'item

Option de `viewer_selection`	Valeur par défaut	Signification
`viewer_field`	obligatoire	La clé du champ `instance_display` du visualiseur
`labels`	aucune	Noms des sélections, sous forme de chaînes ou de `{name, color}`. Les nouvelles sélections prennent l'étiquette courante, et chacune peut être réétiquetée
`min_selections`	aucune	L'item reste incomplet tant que ce nombre de résidus n'est pas sélectionné, quand le schéma est obligatoire
`max_selections`	aucune	Toute sélection supplémentaire est refusée avec un message

Préparer les structures

Un modèle par fichier. Seul le premier modèle d'un fichier multi-modèles est lu ; découpez donc les ensembles RMN ou les lots de prédictions en un fichier par item.
Modèles prédits. AlphaFold, ColabFold et des outils similaires écrivent le pLDDT dans la colonne du facteur B ; définissez donc plddt: true pour colorer selon cette valeur. Avec engine: molstar, la coloration par pLDDT lit la table ma_qa_metric_local que portent les fichiers mmCIF d'AlphaFold DB.
Chaînes et numéros. La sélection stockée utilise les champs auteur du fichier (auth_asym_id, auth_seq_id), qui correspondent à la numérotation qu'affichent 3Dmol.js et Mol*. Si votre analyse utilise la numérotation label_seq_id, faites la correspondance après l'export.
Attribution. Les prédictions d'AlphaFold DB sont sous licence CC-BY-4.0 ; une étude qui les redistribue, ou qui publie des figures réalisées à partir d'elles, doit donc en citer la source.

Les bandes de pLDDT sont très élevée (au-dessus de 90, bleu foncé), confiante (de 70 à 90, bleu clair), faible (de 50 à 70, jaune) et très faible (50 ou moins, orange). Une légende est affichée sous la vue, et chaque bouton de résidu de la table porte sa bande sous forme d'une barre colorée.

Sélectionner des résidus

Les annotateurs choisissent une étiquette, puis cliquent sur des résidus dans la vue 3D ou dans la table des résidus, et un nouveau clic en retire un. Le survol dans la vue 3D affiche le résidu et son pLDDT. La table des résidus est la voie d'accès au clavier : Tab passe à une chaîne, les touches fléchées passent d'un résidu à l'autre, Début et Fin sautent aux extrémités, et Espace ou Entrée active ou désactive le résidu. La liste sous la question montre chaque sélection, avec un menu pour changer son étiquette et un bouton Remove. Les sélections sont restaurées quand l'annotateur revient sur un item.

Réponse stockée

json

{"viewer": "protein_structure",
 "items": [{"chain": "A", "resi": 8, "resn": "HIS", "label": "ligand contact"},
           {"chain": "B", "resi": 3, "resn": "LYS", "label": "interface"}]}

Un résidu doté d'un code d'insertion ajoute "icode": "A". Il n'existe pas de format d'export conçu pour viewer_selection ; ce JSON est donc la valeur du schéma dans les exports jsonl, csv et tsv. Les métriques d'accord de Potato comparent des noms d'étiquettes, et non des listes de résidus ; comparez donc les annotateurs en calculant vous-même le recouvrement des ensembles par item, par exemple un indice de Jaccard sur les paires (chain, resi).

Choisir un moteur

	3Dmol.js (`engine: 3dmol`)	Mol* (`engine: molstar`)
Installation	Fourni avec Potato	`potato vendor fetch molstar`
Licence	BSD-3-Clause	MIT
Résidus sélectionnés	Bâtonnets dans la couleur de l'étiquette	Surbrillance de sélection de Mol*
Coloration par pLDDT	Depuis la colonne du facteur B	Depuis `ma_qa_metric_local`
Table des résidus pour une URL distante	Construite à partir du modèle chargé	Non disponible

potato vendor fetch molstar télécharge Mol* 5.12.0 et le vérifie par rapport à des empreintes SHA-256 enregistrées avant de l'installer, et rien n'est téléchargé tant que vous ne lancez pas cette commande. Une configuration avec engine: molstar échoue à potato validate et au démarrage du serveur tant que le paquet n'est pas installé, et le message d'erreur indique la commande.

Exemple

bash

python potato/flask_server.py start examples/advanced/protein-binding-site/config.yaml -p 8000

L'exemple contient deux modèles synthétiques et une tâche de site de liaison.

Pour aller plus loin

Loci génomiques - Loci igv.js pour la revue de variants
Affichage des instances - Configuration des champs d'affichage
Annotation hors ligne (air-gapped) - Exécuter Potato hors ligne

Pour les détails d'implémentation, consultez la documentation source sur les structures de protéines et la biologie structurale.