Protein Structures: Marking Residues in 3Dmol.js or Mol*

Show mmCIF, BinaryCIF or PDB structures in Potato with pLDDT colouring and a residue table, and record binding sites, epitopes or interface residues.

New in v2.12.0

The protein_structure display shows a macromolecular structure in the browser, and annotators select residues by clicking them in the 3D view or in a residue table under it. A viewer_selection scheme stores the selection, such as a binding site, an epitope, a region judged disordered, residues at an interface, or residues where a predicted model looks wrong. Other questions about the item, such as a rating or a note, go in ordinary schemes beside it.

The display draws a cartoon, shows ligands as sticks (single-atom ions as spheres), and draws each selected residue as sticks in its label's colour. It can colour the cartoon by model confidence (pLDDT) and show a PAE image beside the structure.

Formats: mmCIF (.cif, .mmcif), BinaryCIF (.bcif) and PDB (.pdb, .ent), each optionally gzipped. Plan new projects around mmCIF: from 2027-07-21, new PDB entries get 12-character IDs and are distributed as mmCIF only. The server reads BinaryCIF only when the msgpack package is installed, and without it the residue table is unavailable while the 3D view still works.
Engines: 3dmol (the default) uses 3Dmol.js 2.5.5, which ships with Potato. molstar uses Mol* 5.12.0, which is about 5 MB and is installed with potato vendor fetch molstar. Both need WebGL.
Without WebGL, the 3D view shows a message and the residue table still works.
Offline by default: a structure is read from the media directory. A URL, such as an AlphaFold DB or RCSB file, loads only when the display sets allow_remote: true, and then the annotator's browser fetches it, not the Potato server.

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

Each item names its structure file relative to media_directory:

json

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

Display option	Default	Meaning
`engine`	`3dmol`	`3dmol` or `molstar`
`height`	`420`	Height of the 3D view, in pixels or a CSS length
`format`	from the extension	`cif`, `bcif` or `pdb`, for a file whose name does not say
`color_by`	`chain`	`chain`, `spectrum` (N- to C-terminus) or `secondary`. Ignored when `plddt` is on
`plddt`	`false`	Colours the cartoon by the B-factor column read as pLDDT, in the four AlphaFold bands. Values written as 0-1 are scaled
`pae_field`	none	An item field holding an image, such as a PAE plot, shown beside the structure
`show_ligands`	`true`	Draws HETATM groups other than water
`residue_table`	`true`	Shows the residue table
`residue_table_limit`	`3000`	Above this many residues the table is replaced by a note, and residues are selected in the 3D view
`allow_remote`	`false`	Lets the browser load an http(s) URL named in the item

`viewer_selection` option	Default	Meaning
`viewer_field`	required	The `instance_display` field key of the viewer
`labels`	none	Names for selections, as strings or `{name, color}`. New selections take the current label, and each can be relabelled
`min_selections`	none	The item is incomplete until this many residues are selected, when the scheme is required
`max_selections`	none	Selecting more is refused with a message

Preparing structures

One model per file. Only the first model of a multi-model file is read, so split NMR ensembles or prediction batches into one file per item.
Predicted models. AlphaFold, ColabFold and similar tools write pLDDT into the B-factor column, so set plddt: true to colour by it. With engine: molstar, pLDDT colouring reads the ma_qa_metric_local table that AlphaFold DB mmCIF files carry.
Chains and numbers. The stored selection uses the file's author fields (auth_asym_id, auth_seq_id), which is the numbering 3Dmol.js and Mol* display. If your analysis uses label_seq_id numbering, map it after export.
Attribution. AlphaFold DB predictions are licensed CC-BY-4.0, so a study that redistributes them, or publishes figures made from them, must credit the source.

The pLDDT bands are very high (above 90, dark blue), confident (70 to 90, light blue), low (50 to 70, yellow) and very low (50 or below, orange). A legend is shown under the view, and each residue button in the table carries its band as a coloured bar.

Selecting residues

Annotators pick a label, then click residues in the 3D view or the residue table, and clicking again removes one. Hovering in the 3D view shows the residue and its pLDDT. The residue table is the keyboard route: Tab moves to a chain, the arrow keys move between residues, Home and End jump to the ends, and Space or Enter toggles the residue. The list under the question shows each selection, with a menu to change its label and a Remove button. Selections are restored when the annotator comes back to an item.

Stored answer

json

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

A residue with an insertion code adds "icode": "A". There is no export format made for viewer_selection, so this JSON is the scheme's value in the jsonl, csv and tsv exports. Potato's agreement metrics compare label names, not residue lists, so compare annotators by computing set overlap per item yourself, for example Jaccard over (chain, resi) pairs.

Choosing an engine

	3Dmol.js (`engine: 3dmol`)	Mol* (`engine: molstar`)
Installed	Ships with Potato	`potato vendor fetch molstar`
Licence	BSD-3-Clause	MIT
Selected residues	Sticks in the label colour	Mol*'s selection highlight
pLDDT colouring	From the B-factor column	From `ma_qa_metric_local`
Residue table for a remote URL	Built from the loaded model	Not available

potato vendor fetch molstar downloads Mol* 5.12.0 and checks it against recorded SHA-256 hashes before installing it, and nothing is downloaded unless you run it. A config with engine: molstar fails potato validate and server start until the bundle is installed, and the error names the command.

Example

bash

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

The example has two synthetic models and a binding-site task.