chem-msms-predict

Files (5)

• SKILL.md
• README.md · examples/
• predict_smiles.py · examples/
• download_weights.py · scripts/
• predict_msms.py · scripts/

SKILL.md (first lines)

# LC-MS/MS Spectrum Prediction

## Goal

Predict the LC-MS/MS (tandem mass) spectrum of a molecule given its SMILES string using ICEBERG — a two-stage GNN that first generates a fragmentation DAG (fragment ions) and then predicts their intensities. Output is a predicted spectrum (m/z, intensity) with optional fragment SMILES assignments per peak.

## When to Use This Skill

- A SMILES string is known and a predicted LC-MS/MS spectrum (m/z vs intensity) is needed.
- Fragment ion assignments (SMILES per peak) are required.
- No reference spectrum exists, or comparison to a predicted spectrum is desired.
- Companion skill `chem-spectrum-matcher` can compare predicted vs experimental spectra.

## When NOT to Use This Skill

- **Experimental spectrum already available** — use it directly; no prediction needed.
- **Only compound name known** — first resolve to SMILES via `drug-db-pubchem`, then call this skill.
- **GC-MS or other MS types** — ICEBERG is trained on LC-MS/MS only; flag a warning before proceeding.
- **Organometallics or MW > 1000** — predictions may be unreliable or fail due to unsupported element types.

## Prerequisites

Scripts run in the `msms` environment, created on first use by `venv/run`. It
installs ICEBERG 2.1 (`ms-pred`, pinned to a commit) on a CPU torch build, and
is x86_64 Linux only: DGL publishes no aarch64 wheels.

### Download the ICEBERG 2.1 checkpoints

```bash
${CLAUDE_SKILL_DIR}/../../venv/run msms python ${CLAUDE_SKILL_DIR}/scripts/download_weights.py
```

This fetches the public weights trained on MassSpecGym (`msg_all`, ~80 MB) from
the ms-pred authors:

```
downloads/iceberg_msg_all/
├── gen/best.ckpt           # generator (stage 1)
└── inten_contr/best.ckpt   # intensity predictor (stage 2)
```

Weights trained on NIST are available from the ms-pred authors on proof of a
NIST license. ICEBERG 2.0 checkpoints do not load: 2.1 adds instrument types.
**Flag error and stop** if either checkpoint is missing.

## Instructions

### Step 1 — Run inference and generate spectrum

```bash
${CLAUDE_SKILL_DIR}/../../venv/run msms python ${CLAUDE_SKILL_DIR}/scripts/predict_msms.py \
    --smiles "c1ccccc1C(=O)OCCN" \
    --gen_ckpt downloads/iceberg_msg_all/gen/best.ckpt \
    --inten_ckpt downloads/iceberg_msg_all/inten_contr/best.ckpt \
    --collision_energies 20 40 \
    --adduct "[M+H]+" \
    --instrument "Orbitrap" \
    --output_dir results/msms_prediction
```

**Key parameters:**
- `--smiles` — input molecule as SMILES string
- `--gen_ckpt` / `--inten_ckpt` — paths to ICEBERG checkpoints
- `--collision_energies` — one or more collision energies in eV (e.g. `20 40 60`); model was trained on absolute eV values
- `--adduct` — supported adducts: `[M+H]+`, `[M-H]-`, `[M+Na]+`, `[M+NH4]+`, and others from `ms_pred.common.ion2mass`
- `--instrument` — instrument type for intensity prediction (e.g. `"Orbitrap"`, `"QTOF"`)
- `--threshold` — confidence cutoff for DAG fragment generator (default `0.1`; lower = more fragments)
- `--sparse_k` — maximum number of peaks returned (default `100`)
- `--num_workers` — parallel CPU workers (default `0`: serial); inference runs on the CPU

**Outputs written to `--output_dir`:**
| File | Description |
|------|-------------|
| `spectrum.png` | Stem plot of predicted spectrum, one panel per collision energy |
| `fragments.json` | JSON list per CE: `{mz, intensity, fragment_smiles}` sorted by intensity |
| `input_configs.yaml` | All run parameters for reproducibility |

### Step 2 — Inspect fragment assignments (optional)

`fragments.json` maps each predicted peak to the fragment ICEBERG assigns it,
as the Kekulé SMILES of the heavy-atom substructure (hydrogen shifts are not
shown). There is one entry per fragment, so fragments with the same formula
repeat an m/z; `spectrum.png` sums them. For 2-aminoethyl benzoate at 20 eV:

```json
{
  "20": [
    {"mz": 149.0597, "intensity": 1.0, "fragment_smiles": "CCOC(=O)C1=CC=CC=C1"},
    {"mz": 105.0335, "intensity": 0.944, "fragment_smiles": "O=CC1=CC=CC=C1"},
    ...
  ]
}
```

Use this to rationalize which bonds fragment at which energy.

### Step 3 — Compare with experimental spectrum (optional)

If an experimental spectrum is available, use the companion skill:

→ [`chem-spectrum-matcher`](../chem-spectrum-matcher/SKILL.md)

## Examples

### 2-Aminoethyl benzoate (`c1ccccc1C(=O)OCCN`)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run msms python ${CLAUDE_SKILL_DIR}/examples/predict_smiles.py \
    --gen_ckpt downloads/iceberg_msg_all/gen/best.ckpt \
    --inten_ckpt downloads/iceberg_msg_all/inten_contr/best.ckpt \
    --output_dir .agents/test/msms_example
```

Expected output:
- `spectrum.png` — two-panel spectrum (20 eV + 40 eV)
- `fragments.json` — fragment assignments for both energies
- Precursor `[M+H]+` ≈ 166.086 Da

## Constraints

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills