Estructuras de proteínas: marcar residuos en 3Dmol.js o Mol*

Nuevo en v2.12.0

La visualización protein_structure muestra una estructura macromolecular en el navegador, y los anotadores seleccionan residuos haciendo clic en ellos en la vista 3D o en una tabla de residuos que hay debajo. Un esquema viewer_selection guarda la selección, como un sitio de unión, un epítopo, una región que se considera desordenada, residuos de una interfaz o residuos donde un modelo predicho parece incorrecto. Las demás preguntas sobre el ítem, como una valoración o una nota, van en esquemas normales a su lado.

La visualización dibuja una representación en cartoon, muestra los ligandos como varillas (los iones de un solo átomo como esferas) y dibuja cada residuo seleccionado como varillas en el color de su etiqueta. Puede colorear el cartoon según la confianza del modelo (pLDDT) y mostrar una imagen de PAE junto a la estructura.

• Formatos: mmCIF (.cif, .mmcif), BinaryCIF (.bcif) y PDB (.pdb, .ent), cada uno opcionalmente comprimido con gzip. Planifica los proyectos nuevos en torno a mmCIF: a partir del 2027-07-21, las entradas nuevas del PDB reciben ID de 12 caracteres y se distribuyen solo como mmCIF. El servidor lee BinaryCIF solo cuando está instalado el paquete msgpack, y sin él la tabla de residuos no está disponible, aunque la vista 3D sigue funcionando.
• Motores: 3dmol (el valor por defecto) usa 3Dmol.js 2.5.5, que viene con Potato. molstar usa Mol* 5.12.0, que ocupa unos 5 MB y se instala con potato vendor fetch molstar. Ambos necesitan WebGL.
• Sin WebGL, la vista 3D muestra un mensaje y la tabla de residuos sigue funcionando.
• Sin conexión por defecto: una estructura se lee del directorio de multimedia. Una URL, como un archivo de AlphaFold DB o de RCSB, solo se carga cuando la visualización fija allow_remote: true, y en ese caso la descarga el navegador del anotador, no el servidor de Potato.

Configuración

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"]

Cada ítem nombra su archivo de estructura en relación con media_directory:

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

Preparar las estructuras

• Un modelo por archivo. Solo se lee el primer modelo de un archivo con varios modelos, así que divide los conjuntos de RMN o los lotes de predicciones en un archivo por ítem.
• Modelos predichos. AlphaFold, ColabFold y herramientas similares escriben el pLDDT en la columna del factor B, así que define plddt: true para colorear según él. Con engine: molstar, la coloración por pLDDT lee la tabla ma_qa_metric_local que llevan los archivos mmCIF de AlphaFold DB.
• Cadenas y números. La selección guardada usa los campos de autor del archivo (auth_asym_id, auth_seq_id), que es la numeración que muestran 3Dmol.js y Mol*. Si tu análisis usa la numeración label_seq_id, haz la correspondencia después de exportar.
• Atribución. Las predicciones de AlphaFold DB tienen licencia CC-BY-4.0, así que un estudio que las redistribuya, o que publique figuras hechas a partir de ellas, tiene que citar la fuente.

Las bandas de pLDDT son muy alta (por encima de 90, azul oscuro), segura (de 70 a 90, azul claro), baja (de 50 a 70, amarillo) y muy baja (50 o menos, naranja). Bajo la vista se muestra una leyenda, y cada botón de residuo de la tabla lleva su banda como una barra de color.

Seleccionar residuos

Los anotadores eligen una etiqueta y después hacen clic en residuos de la vista 3D o de la tabla de residuos, y un segundo clic quita el residuo. Al pasar el cursor por la vista 3D se muestran el residuo y su pLDDT. La tabla de residuos es la vía para el teclado: Tab pasa a una cadena, las flechas se mueven entre residuos, Home y End saltan a los extremos, y Space o Enter activa o desactiva el residuo. La lista bajo la pregunta muestra cada selección, con un menú para cambiar su etiqueta y un botón Remove. Las selecciones se restauran cuando el anotador vuelve a un ítem.

Respuesta guardada

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

Un residuo con código de inserción añade "icode": "A". No hay un formato de exportación específico para viewer_selection, así que este JSON es el valor del esquema en las exportaciones jsonl, csv y tsv. Las métricas de concordancia de Potato comparan nombres de etiquetas, no listas de residuos, así que compara a los anotadores calculando tú el solapamiento de conjuntos por ítem, por ejemplo Jaccard sobre los pares (chain, resi).

Elegir un motor

potato vendor fetch molstar descarga Mol* 5.12.0 y lo comprueba con hashes SHA-256 registrados antes de instalarlo, y no se descarga nada a menos que lo ejecutes. Una configuración con engine: molstar no supera potato validate ni el arranque del servidor hasta que el paquete está instalado, y el error nombra el comando.

Ejemplo

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

El ejemplo tiene dos modelos sintéticos y una tarea de sitios de unión.

Lecturas adicionales

• Loci genómicos - Loci de igv.js para revisar variantes
• Visualización de instancias - Cómo se configuran los campos de visualización
• Anotación sin conexión a la red - Ejecutar Potato sin conexión

Para detalles de implementación, consulta la documentación fuente sobre las estructuras de proteínas y la biología estructural.