MassBank MS/MS Fragment Peaks and Formula Assignment

# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json
#
# MassBank: pick the fragment peaks of an MS/MS spectrum and assign each a
# molecular formula.
#
# Dataset: MassBank/MassBank-data, the open records of the MassBank mass
# spectral library, in MassBank Record Format 2.6.0 (MassBank Consortium).
# Paper (describes the record format, its validation pipeline and the
# current library):
#   @article{Neumann_2025,
#     title     = {MassBank: an open and FAIR mass spectral data resource},
#     author    = {Neumann, Steffen and Meier, Ren{\'e} and Wenk, Michael and Elapavalore, Anjana and Nishioka, Takaaki and Schulze, Tobias and Stravs, Michael and Tsugawa, Hiroshi and Matsuda, Fumio and Schymanski, Emma L},
#     journal   = {Nucleic Acids Research},
#     volume    = {54}, number = {D1}, pages = {D601--D606}, year = {2025},
#     publisher = {Oxford University Press (OUP)},
#     doi       = {10.1093/nar/gkaf1193}
#   }
# DOI: 10.1093/nar/gkaf1193
# Dataset DOI: 10.5281/zenodo.3378723 (MassBank/MassBank-data, CC BY 4.0 for
# the repository)
# Dataset URL: https://github.com/MassBank/MassBank-data
# Record format: https://github.com/MassBank/MassBank-documentation/blob/dev/MassBankRecordFormat.md
#
# Licence: every MassBank record carries its own LICENSE line. The record
# format allows CC0, CC BY, CC BY-NC, CC BY-NC-SA and CC BY-SA. The ten
# records in sample-data.json are all CC BY and are real, copied unchanged
# (m/z and relative intensity) from the records named in each item's
# "credit" line. The item fields accession, license, source_url, authors and
# copyright repeat the record header.
#
# What a record holds, quoted from the MassBank Record Format 2.6.0:
#   PK$PEAK: "Peak Data. Mandatory and Multiple line Information"
#     "PK$PEAK: m/z int. rel.int."
#     "M/Z: m/z of the peak. INT: intensity of the peak. REL: an integer from
#     1 to 999 which denotes relative intensity of the peak."
#   PK$ANNOTATION: "Chemical Annotation of Peaks with Molecular Formula.
#     Optional and Multiple Line Information. Line 1 defines the record format
#     of the annotation blocks. Contributors freely define the record format
#     by using appropriate terms."
#     The UFZ and Athens records here use the RMassBank layout
#     "PK$ANNOTATION: m/z tentative_formula formula_count mass error(ppm)".
#     The format says "The automated annotation by RMassBank is currently
#     tentative."
#
# How this design maps onto a record:
#   - The spectrum display draws the PK$PEAK list as sticks (x is m/z, y is
#     the REL column, 1 to 999).
#   - The peak_picking scheme records the peaks the annotator keeps, and the
#     peak_fields record a formula (the PK$ANNOTATION tentative_formula
#     column) and a status for each.
#   - The formulas the submitters deposited are kept in each item's
#     "deposited_formulas" field (m/z to formula). The page does not show
#     them, so the annotator assigns formulas independently and the two sets
#     can be compared afterward.
#
# Adaptations:
#   - Real records, but a small sample: ten MS2 spectra of ten compounds, 17
#     to 25 peaks each, from the UFZ and University of Athens contributors,
#     all with LICENSE CC BY. They are not a sample of MassBank.
#   - MassBank annotations are written by the contributors, with RMassBank
#     software, not by a crowd protocol. This design asks for the same
#     judgment (is this a fragment peak, and which formula fits) as a
#     review of a deposited record.
#   - The status field (tentative formula, confirmed formula, no formula
#     fits) is added here. The record format has no per-peak status; the
#     RMassBank annotations are all "tentative" as a whole.
#   - Only peaks and formulas are collected. Ion type, mass error and formula
#     count (the other PK$ANNOTATION columns) are left out.
#   - Suggested peaks come from the display's peak detector (and from a
#     trained peak-cnn model once one has run), not from the submitters'
#     annotations.
#
# Model-assisted peak picking (peak-cnn). Open /admin/training with the
# admin key below, pick peak-cnn for the "peaks" scheme, and train (pip
# install "potato-annotation[train-vision]"). It learns where the annotators
# kept peaks, from the spectrum alone, and suggests peak POSITIONS (m/z) on
# spectra nobody has finished, marked "model". It does not predict formulas,
# statuses or any other peak label, and it does not serve or deploy a model.
# It needs 5 annotated spectra in its training split (min_instances); ten
# spectra from two labs exercise the loop and do not teach a model that
# generalizes to other instruments.
#
# Run: potato start config.yaml -p 8000

port: 8000
annotation_task_name: "MassBank: pick MS2 fragment peaks and assign formulas"
task_dir: "."

data_files:
  - sample-data.json

item_properties:
  id_key: id
  text_key: context
  private_keys: [deposited_formulas]

output_annotation_dir: annotation_output
export_annotation_format: jsonl

require_password: false
admin_api_key: "demo-admin-key"

user_config:
  allow_all_users: true

instance_display:
  fields:
    - key: context
      type: text
      label: "Record"
    - key: spectrum
      type: spectrum
      label: "MS2 spectrum"
      display_options:
        height: 380
        spectrum_type: ms
        mode: sticks
        x_label: "m/z"
        y_label: "Relative intensity (1 to 999)"
        # Suggested peaks: the peak detector at first, a trained peak-cnn
        # model's predictions once one has run (method auto).
        prepick:
          method: auto
          prominence: 0.05
          max_peaks: 30
    - key: credit
      type: text
      label: "Source and licence"

annotation_schemes:
  - annotation_type: peak_picking
    name: peaks
    description: "Keep the fragment peaks and assign each a molecular formula. Click a stick to pick it, click it again to remove it, drag to zoom. Accept or reject every suggested peak."
    viewer_field: spectrum
    peak_fields:
      - name: formula
        label: "Formula"
        type: text
        placeholder: "e.g. C6H14N+"
      - name: status
        label: "Status"
        type: choice
        options: ["tentative formula", "confirmed formula", "no formula fits"]
    min_peaks: 1
    require_review: true
    label_requirement: {required: true}

model_training:
  enabled: true
  writeback:
    # Show peak-cnn's predicted peak positions as suggestions on the spectrum.
    schemas: ["peaks"]
    include_unlabeled: true
    min_confidence: 0.5

annotation_instructions: |
  Each item is the MS/MS spectrum of one compound, as deposited in
  MassBank. The record line gives the compound's formula and the precursor
  ion, so a fragment formula has to be a subset of the precursor's atoms.
  Pick the peaks that are fragments of the compound and skip noise. For
  each picked peak, write the fragment's molecular formula, including the
  charge sign the ion carries (C6H14N+ in positive mode, C13H8O- in
  negative mode), and set the status. Use "no formula fits" when no
  formula is consistent with the compound and the m/z.