BioLiP2 Ligand Relevance and Binding Residues on PDB Structures

# BioLiP2: judging ligand relevance and marking binding residues on PDB structures
#
# Dataset: BioLiP2, a database of biologically relevant ligand-protein interactions
#   extracted from the Protein Data Bank (PDB).
# URL: https://zhanggroup.org/BioLiP/
# Paper: Zhang, C., Zhang, X., Freddolino, L., and Zhang, Y. (2023). BioLiP2: an updated
#   structure database for biologically relevant ligand-protein interactions. Nucleic Acids
#   Research 52(D1), D404-D412.
#   @article{Zhang_2023, title={BioLiP2: an updated structure database for biologically
#     relevant ligand-protein interactions}, volume={52}, DOI={10.1093/nar/gkad630},
#     number={D1}, journal={Nucleic Acids Research}, publisher={Oxford University Press (OUP)},
#     author={Zhang, Chengxin and Zhang, Xi and Freddolino, Lydia and Zhang, Yang},
#     year={2023}, pages={D404-D412}}
# DOI: 10.1093/nar/gkad630
# Earlier version: Yang, J., Roy, A., and Zhang, Y. (2012), Nucleic Acids Research 41(D1),
#   D1096-D1103, DOI 10.1093/nar/gks966.
#
# Licences: the BioLiP2 labels are not redistributed here, as a design choice. The paper's
#   Data availability statement says the database and source code are available under the
#   BSD license. The structures are PDB archive files, which the wwPDB
#   releases under CC0 1.0 (https://www.rcsb.org/pages/policies). The ten structures are not
#   copied into this folder. The browser fetches each one from files.rcsb.org (allow_remote).
#
# Protocol quotes (Zhang et al. 2023, Nucleic Acids Research):
#   "Since many structures are determined with purification and crystallization additives that
#   are unrelated to a protein's in vivo function, it is nontrivial to identify the subset of
#   protein-ligand interactions that are biologically relevant."
#   "A protein residue with at least two inter-molecular atomic contacts to a ligand is
#   labeled as a ligand binding residue." Contacts are "protein-ligand atom pairs within sum
#   of van der Waals radii plus 0.5 A".
#   "A ligand on the artifact list will be discarded if it appears >15 times in the structure,
#   or if its binding site only contains two consecutive residues. Otherwise, the title and
#   abstract of the primary citation describing the structure is downloaded from PubMed to
#   check the remaining potential artifacts."
#
# Adaptations:
#   - BioLiP2 decides relevance with geometric rules, a list of 463 commonly used
#     non-biological ligands, and a check of the primary citation's title and abstract. It
#     uses no annotator crowd. This design asks a person to make the same call by eye, with the
#     structure in front of them, so the labels here are annotator judgments and not BioLiP2
#     labels.
#   - No BioLiP2 annotation is copied. Items name one ligand in a public PDB entry and carry no
#     reference answer.
#   - The third radio label, "Cannot tell from the structure", is an addition of this design
#     and has no source in BioLiP2 or its paper.
#   - The radio labels paraphrase the paper's wording ("biologically relevant" versus
#     additives for "purification and crystallization"). They are not an official label set.
#   - Binding residues are picked by hand in the 3D view or the residue table. BioLiP2 computes
#     them from the contact rule quoted above. The rule is given in the instructions as a guide
#     and is not applied by Potato.
#
# Model training: none. No Potato trainer reads a protein structure or a viewer_selection
#   scheme. Trainers for radio schemes learn from an item's text or image, and the only text
#   here is the one-line task note, so a classifier would learn nothing about ligands.
#
# Run (the structure viewer needs WebGL in the browser and network access to files.rcsb.org;
#   without WebGL the residue table still works):
#   potato start config.yaml -p 8000

annotation_task_name: "BioLiP2 ligand binding-site review"

task_dir: "."

data_files:
  - "sample-data.json"

item_properties:
  id_key: "id"
  text_key: "note"

output_annotation_dir: "annotation_output"
export_annotation_format: jsonl

user_config:
  allow_all_users: true
  users: []

require_password: false

annotation_instructions: |
  Each item names one ligand in a public PDB structure. Find that ligand in the 3D view, then
  decide whether it is a biologically relevant partner of the protein or an additive used for
  purification or crystallization. Select the protein residues that touch the ligand. BioLiP2
  counts a residue as binding when it has at least two atomic contacts with the ligand, with
  contact meaning a distance within the sum of the van der Waals radii plus 0.5 angstroms.
  Judge by eye and select the residues you think meet that description.

instance_display:
  fields:
    - key: note
      type: text
      label: "Ligand to review"
    - key: structure
      type: protein_structure
      label: "PDB structure"
      display_options:
        engine: 3dmol
        allow_remote: true
        format: pdb
        color_by: chain
        show_ligands: true
        residue_table: true
        height: 460

annotation_schemes:
  - annotation_type: viewer_selection
    name: binding_residues
    description: "Select the protein residues that form the binding site of the named ligand"
    viewer_field: structure
    labels:
      - "binding residue"
    min_selections: 1
    label_requirement:
      required: true
    instructions: >-
      Click residues in the 3D view or in the residue table. Click a selected residue again to
      remove it.

  - annotation_type: radio
    name: ligand_relevance
    description: "Is the named ligand biologically relevant to this protein, or a crystallization or purification additive?"
    labels:
      - name: "Biologically relevant"
        key_value: "1"
      - name: "Crystallization or purification additive"
        key_value: "2"
      - name: "Cannot tell from the structure"
        key_value: "3"
    label_requirement:
      required: true