Deep learning model checkpoint loading

Deep-Learning Model Checkpoint Loading

Summary

Load pre-trained neural network weights from disk checkpoints to enable inference without retraining. This skill is essential for applying trained FIDDLE models to new MS/MS spectra or batch predictions.

When to use

When you have MS/MS spectra from GNPS or other libraries and need to apply a pre-trained FIDDLE model (TCN formula predictor or Siamese rescore architecture) without training from scratch. Use this skill before running inference on new samples or benchmarks.

When NOT to use

• Input checkpoints are from different FIDDLE versions with incompatible architectures (e.g., v1.x with pre-Siamese rescore vs. v2.0.0 Siamese rescore) without retesting on reference data.
• You are training a new model from scratch—use training scripts instead; checkpoint loading assumes weights are already optimized.
• Instrument type (Orbitrap vs. Q-TOF) does not match your spectra—load the corresponding instrument-specific checkpoint or retraining will be needed.

Inputs

• Trained PyTorch checkpoint file (.pt) for TCN formula prediction model
• Trained PyTorch checkpoint file (.pt) for rescore model (Siamese architecture)
• YAML configuration file specifying model architecture parameters
• MS/MS spectrum data in MGF format with required fields: TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY

Outputs

• Loaded PyTorch model object in memory ready for inference
• CSV file with scored formula candidates per spectrum (columns: ID, Mass, Pred Formula, Refined Formula (0..4), Rescore (0..4))
• JSON/structured output with ranked formula candidates and confidence scores

How to apply

Download pre-trained checkpoint files (e.g., fiddle_tcn_orbitrap.pt and fiddle_rescore_orbitrap.pt) from the FIDDLE release page or Zenodo deposit (DOI 10.5281/zenodo.19181279) and place them in the ./check_point/ directory. For CLI workflows, run msfiddle-download-models to fetch checkpoints to the default location (~/.msfiddle/check_point). Specify checkpoint paths explicitly using --resume_path (TCN model) and --rescore_resume_path (rescore model) flags, or pass them programmatically to the MsFiddlePredictor constructor. The rescore model in v2.0.0 uses a redesigned Siamese architecture that rescores initial formula predictions; ensure your checkpoint version matches your expected architecture. Validate the loaded model by running on a known reference sample (e.g., caffeine from GNPS) and checking that output CSV/JSON contains scored formula candidates.

Related tools

• msfiddle (Command-line and Python API wrapper for FIDDLE inference; provides download-models subcommand and high-level predict functions that handle checkpoint loading internally) — https://github.com/josiehong/msfiddle
• FIDDLE (Deep learning method research codebase; contains lower-level training and evaluation scripts; reference implementation for checkpoint loading via config and resume_path arguments) — https://github.com/JosieHong/FIDDLE

Examples

msfiddle --test_data ./demo/input_msms.mgf --config_path ./config/fiddle_tcn_orbitrap.yml --resume_path ./check_point/fiddle_tcn_orbitrap.pt --rescore_resume_path ./check_point/fiddle_rescore_orbitrap.pt --result_path ./demo/output_fiddle.csv --device 0

Evaluation signals

• Loaded model successfully initializes without shape mismatch or device errors; checkpoint file size and modification date match expected release.
• Running inference on reference caffeine Orbitrap spectrum from GNPS produces output CSV with caffeine formula (C8H10N4O2) ranked in top-5 candidates with non-zero rescore confidence.
• Output CSV schema matches specification: contains ID, Mass, Pred Formula, Refined Formula (0..4), Refined Mass (0..4), Rescore (0..4) columns with numeric scores in valid range [0, 1].
• Model inference latency and GPU/CPU utilization are consistent with documented expectations (checkpoint loaded once, reused across batch predictions).
• Results on external benchmark (CASMI 2016/2017, EMBL-MCF 2.0, NIST23) match published FIDDLE accuracy metrics within sampling variance.

Limitations

• Checkpoint must match the installed PyTorch and Python versions; mismatched CUDA/ROCm builds may cause silent inference errors or degraded performance. Test on a small reference set first.
• Siamese rescore architecture in v2.0.0 is a breaking change from v1.x; old v1.x checkpoints will not load without explicit version alignment or retraining.
• Instrument-specific checkpoints (Orbitrap vs. Q-TOF) are not interchangeable; applying Orbitrap-trained weights to Q-TOF spectra or vice versa will produce inaccurate predictions.
• No explicit discussion section in source documents; reproducibility gaps and failure modes (e.g., behavior on spectra from unlisted collision energies, extreme m/z ranges) are not fully documented.

Evidence

• [readme] To use the pre-trained models, please use the following scripts to download the weights from the release page and place them in the ./check_point/ directory: "To use the pre-trained models, please use the following scripts to download the weights from the release page and place them in the"
• [readme] The rescore model has been redesigned with a Siamese architecture in version 2.0.0: "The rescore model has been redesigned (Siamese architecture), see details in CHANGELOG.md"
• [readme] Download the pre-trained checkpoints before running predictions using msfiddle-download-models command: "Download the pre-trained checkpoints before running predictions: msfiddle-download-models"
• [readme] Loaded models can be reused for efficient batched prediction in Python applications: "Reuse loaded models for efficient batched prediction in Python applications"
• [other] The rescore model in FIDDLE v2.0.0 has been redesigned with a Siamese architecture, which is the operative inference architecture for the test: "The rescore model in FIDDLE v2.0.0 has been redesigned with a Siamese architecture, which is the operative inference architecture for the test"