Workflow reconstruction

Workflow Reconstruction

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Reconstruct and validate a complete computational workflow for mass spectrometry prediction by downloading source datasets, preprocessing molecular conformations, training or loading pretrained neural network models, and generating predicted MS/MS spectra in standard formats (MGF, CSV). This skill enables practitioners to reproduce published results or adapt the workflow to new datasets.

When to use

You have molecular structures (SMILES, SDF, or CSV with InChI) and want to predict tandem mass spectra (MS/MS) for those compounds. Specifically: when you need to generate a reference library of small molecule MS/MS spectra for spectral matching, or when you want to fine-tune the 3DMolMS model on your own experimental MS/MS data (QTOF or Orbitrap instruments), or when you need to apply the learned molecular representation to predict retention times or collision cross sections.

When NOT to use

• Input molecules contain atom types outside {'C','O','N','H','P','S','F','Cl','B','Br','I','Na'} — these are automatically filtered and skipped.
• Input molecules have >300 atoms — exceed the model's design capacity and will be dropped.
• Precursor ion type is not in {'[M+H]+','[M-H]-','[M+H-H2O]+','[M+Na]+'} — model has not been trained on other adducts and predictions will be unreliable.
• You have already-measured experimental MS/MS spectra and only need spectral library querying, not generation — use a spectral matching tool instead.

Inputs

• Molecular structure input (CSV with SMILES/InChI, MGF, or PKL file)
• Reference datasets: HMDB SDF, RefMet CSV, QM9 XYZ archive, or custom MS/MS spectra (MoNA SDF, NIST20 SDF)
• Pretrained checkpoint file (.pt, auto-downloaded from GitHub release or checkpoint URL)
• Configuration YAML file (e.g., preprocess_etkdgv3.yml for conformation settings)

Outputs

• Predicted MS/MS spectra in MGF format (instrument-specific, QTOF or Orbitrap)
• Prediction dataframe with molecule identifiers and peak m/z–intensity pairs
• Preprocessed molecule pickle (.pkl) file with 3D conformations and metadata
• Evaluation results CSV (cosine similarity, spectral match count per molecule)
• Trained model checkpoint (.pt file) if training/fine-tuning was performed

How to apply

Begin by downloading and preprocessing one or more source datasets (HMDB, RefMet, QM9, or custom) using the ETKDGv3 conformation generation protocol with Python and RDKit to produce .pkl files. Load the pretrained checkpoint (molnet_qtof_etkdgv3.pt or molnet_orbitrap_etkdgv3.pt, downloaded automatically by MolNet) via the molnetpack Python API or CLI. If fine-tuning, call molnet_engine.train() with train/valid .pkl files and transfer=True to retain the pretrained encoder. Finally, invoke molnet_engine.pred_msms(instrument='qtof' or 'orbitrap') to predict spectra and save as MGF. Filter inputs automatically: atom count ≤300, atom types in {'C','O','N','H','P','S','F','Cl','B','Br','I','Na'}, precursor types in {'[M+H]+','[M-H]-','[M+H-H2O]+','[M+Na]+'}. Validate output by comparing predicted peaks to reference spectra (cosine similarity) or evaluating with molnet_engine.evaluate().

Related tools

• molnetpack (Python package providing MolNet class for loading data, predicting MS/MS/RT/CCS, training, and evaluating; handles checkpoint download, tensor conversion, and output serialization) — https://pypi.org/project/molnetpack/
• 3DMolMS (Deep neural network model core; encapsulates the learned representation from 3D conformations; deployed via molnetpack API and also available as standalone GitHub repository with CLI scripts) — https://github.com/JosieHong/3DMolMS
• PyTorch (Deep learning framework underlying MolNet; must be installed separately; handles GPU acceleration (CUDA) for prediction and training)
• RDKit (Cheminformatics library for parsing molecule structures (SMILES, SDF), generating 3D conformations via ETKDGv3, computing molecular properties, and validating atom types and atom counts)
• NumPy, Pandas (Numerical and tabular data handling: NumPy for tensor operations, Pandas for reading/writing CSV and managing prediction result tables)
• Koina (Web service exposing 3DMolMS MS/MS prediction as a REST API endpoint for inference without local installation; alternative to local molnetpack setup) — https://koina.wilhelmlab.org/docs#post-/3dmolms_qtof/infer

Examples

molnet_engine = MolNet(device=torch.device('cpu'), seed=42); molnet_engine.load_data('./examples/demo_input.csv'); pred_df = molnet_engine.pred_msms(path_to_results='./output_msms.mgf', instrument='qtof')

Evaluation signals

• Output MGF file is valid and parseable; contains PRECURSORMZ, MSLEVEL=2, and peak entries for all input molecules (excluding filtered inputs).
• Predicted peak m/z values fall within the expected range for the precursor ion and instrument (e.g., 0 to [M+H]+ for fragment ions).
• Cosine similarity between predicted and reference spectra (computed via evaluate()) is ≥0.5 for well-matched compounds; median similarity across test set reflects model adequacy.
• For fine-tuned models: training and validation loss curves converge; final validation loss is lower than random baseline.
• Input filtering statistics are logged: count of molecules retained vs. filtered (atom count, atom type, precursor type violations); filtering matches declared thresholds.

Limitations

• Model is trained only on QTOF and Orbitrap instruments; predictions for other MS/MS instrument types (e.g. TOF-TOF, triple-quad) are out-of-distribution.
• Only four precursor ion types are supported: [M+H]+, [M-H]−, [M+H−H2O]+, [M+Na]+; other adducts (e.g., [M+NH4]+, [M+Cl]−) are not handled.
• Molecules with >300 atoms or containing elements outside the supported set are automatically dropped; no partial prediction or approximation.
• 3D conformation generation via RDKit/ETKDGv3 may fail or produce suboptimal geometries for complex/strained molecules; preprocessing logs will indicate failures.
• Pretrained checkpoints assume ETKDGv3 conformation protocol; using non-ETKDGv3 conformations without retraining will degrade predictions.
• Model accuracy decreases for rare or out-of-distribution molecular scaffolds not well-represented in training datasets (HMDB, QM9, MoNA).

Evidence

• [readme] 3D Molecular Network for Mass Spectra Prediction (3DMolMS) is a deep neural network model to predict the MS/MS spectra of compounds from their 3D conformations.: "3D Molecular Network for Mass Spectra Prediction (3DMolMS) is a deep neural network model to predict the MS/MS spectra of compounds from their 3D conformations."
• [readme] Supports CSV, MGF, and PKL input; Predict and save to MGF (checkpoints are downloaded automatically): "Supports CSV, MGF, and PKL input; Predict and save to MGF (checkpoints are downloaded automatically)"
• [readme] Fine-tune from a pretrained checkpoint; transfer=True: "Fine-tune from a pretrained checkpoint; transfer=True, checkpoint_path, resume_path='./check_point/molnet_pre_etkdgv3.pt'"
• [methods] Download the HMDB molecules dataset from HMDB Downloads. The expected data directory structure is: |- data |- hmdb |- structures.sdf: "Download the HMDB molecules dataset from HMDB Downloads. The expected data directory structure is: |- data |- hmdb |- structures.sdf"
• [methods] python scripts/hmdb2pkl.py --data_config_path ./molnetpack/config/preprocess_etkdgv3.yml: "python scripts/hmdb2pkl.py --data_config_path ./molnetpack/config/preprocess_etkdgv3.yml"
• [methods] python scripts/predict.py --task msms --test_data ./data/hmdb/hmdb_etkdgv3_$i.pkl: "python scripts/predict.py --task msms --test_data ./data/hmdb/hmdb_etkdgv3_$i.pkl"
• [methods] Atom number ≤300; Atom types: 'C', 'O', 'N', 'H', 'P', 'S', 'F', 'Cl', 'B', 'Br', 'I', 'Na'; Precursor types: '[M+H]+', '[M-H]-', '[M+H-H2O]+', '[M+Na]+': "Atom number ≤300; Atom types: 'C', 'O', 'N', 'H', 'P', 'S', 'F', 'Cl', 'B', 'Br', 'I', 'Na'; Precursor types: '[M+H]+', '[M-H]-', '[M+H-H2O]+', '[M+Na]+'"
• [readme] This model's molecular representation, learned through MS/MS prediction tasks, can be further applied to enhance performance in other molecular-related tasks, such as predicting retention times (RT) and collision cross sections (CCS).: "This model's molecular representation, learned through MS/MS prediction tasks, can be further applied to enhance performance in other molecular-related tasks, such as predicting retention times (RT)"
• [methods] The unsupported input will be filtered out automatically when loading the dataset: "The unsupported input will be filtered out automatically when loading the dataset"