Scientific task formulation

scientific_task_formulation

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

Summary

Formulate a concrete computational task for predicting MS/MS spectra, retention time, or collision cross sections from molecular structure by defining input data format, preprocessing constraints, model architecture parameters, and evaluation metrics. This skill bridges between raw molecular datasets and trainable neural network objectives.

When to use

You have a collection of molecules (HMDB, RefMet, METLIN, or proprietary library) with known MS/MS spectra, retention times, or CCS values, and you need to frame this as a supervised learning problem suitable for 3DMolMS training or transfer learning. Use this skill when you have parsed molecular structures (SMILES or SDF) and corresponding experimental mass spectrometry or chromatographic annotations that must be aligned, filtered, and formatted into training data splits.

When NOT to use

• Input molecules exceed 300 atoms or contain unsupported element types (e.g., metals, rare halogens not in {F, Cl, Br, I})
• Experimental MS/MS spectra are unavailable or poorly annotated (missing precursor m/z, low spectral quality, or ambiguous peak assignments)
• Task is inference only on a pretrained model; formulation is for defining new training objectives, not applying existing checkpoints

Inputs

• CSV or SDF file containing SMILES/InChI strings and molecular identifiers
• MS/MS spectrum library (MGF, SDF format) or retention time / CCS ground-truth values
• YAML configuration file specifying preprocessing parameters (conformation method, atom filters, precursor types)
• Pretrained checkpoint (optional; downloaded automatically or user-provided for transfer learning)

Outputs

• Preprocessed PKL dataset file(s) containing 3D molecular structures and aligned experimental annotations
• Train/validation/test splits as separate PKL files
• Task definition manifest (YAML or JSON) documenting filter thresholds, class imbalance, and data statistics

How to apply

First, filter the molecular dataset by atom count (≤300 atoms), allowed atom types (C, O, N, H, P, S, F, Cl, B, Br, I, Na), and supported precursor types ([M+H]+, [M-H]−, [M+H−H2O]+, [M+Na]+). Second, generate 3D conformations using ETKDGv3 conformation generation and serialize into PKL files via preprocessing scripts (e.g., hmdb2pkl.py). Third, define task type (msms, rt, or ccs) and establish train/validation/test splits, optionally specifying a pretrained checkpoint for transfer learning. Fourth, configure model hyperparameters (instrument type: qtof or orbitrap; loss function; learning rate; epochs) in a YAML configuration file. Finally, validate that the preprocessed PKL files contain the required fields (SMILES, InChI, 3D conformations, experimental spectra or values) before initiating training.

Related tools

• molnetpack (Python package providing MolNet class with train(), evaluate(), and preprocessing methods to load data, apply filters, and serialize PKL datasets) — https://pypi.org/project/molnetpack/
• RDKit (Generates 3D molecular conformations via ETKDGv3 algorithm; validates molecular structures and atom types during preprocessing)
• PyYAML (Parses task configuration files specifying conformation parameters, filter thresholds, and model hyperparameters)
• PyTorch (Underlying deep learning framework for defining loss functions, model architecture, and training loops in task formulation) — https://pytorch.org/
• Pandas (Loads and aligns CSV/SDF input files with ground-truth annotations before serialization)

Examples

from molnetpack import MolNet; molnet = MolNet(device='cuda:0'); molnet.train(task='msms', train_data='./data/hmdb_etkdgv3_train.pkl', valid_data='./data/hmdb_etkdgv3_test.pkl', checkpoint_path='./model.pt', resume_path='./check_point/molnet_pre_etkdgv3.pt', transfer=True)

Evaluation signals

• Preprocessed PKL files are non-empty, contain expected keys (SMILES, 3D_coords, experimental_spectrum or rt/ccs), and match row counts between input and output
• Atom count distribution in preprocessed data is ≤300; atom type set is a subset of {C, O, N, H, P, S, F, Cl, B, Br, I, Na}
• Precursor type frequency distribution matches allowed types; no unexpected ionization modes in training data
• Train/validation/test splits are non-overlapping (no molecule appears in multiple splits) and preserve class balance if applicable
• YAML configuration is valid YAML syntax and all specified keys (task, instrument, conformation method, atom filters) are recognized by MolNet.train()

Limitations

• 3D conformation generation is deterministic but can yield multiple valid conformers; the formulation uses only the primary conformer (ETKDGv3), potentially losing structural diversity
• Unsupported ion types or atom types are silently filtered; no warning is issued if >10% of input molecules are discarded, risking unintended data loss
• Task formulation assumes experimental spectra are noise-filtered and peak-picked; raw instrument output or spectra with m/z errors >10 ppm may degrade model learning
• Transfer learning task formulation requires a compatible pretrained checkpoint; no validation is performed during formulation to ensure checkpoint–task compatibility

Evidence

• [methods] Supported precursor ion types are limited to four common ionization modes: "Precursor types: '[M+H]+', '[M-H]-', '[M+H-H2O]+', '[M+Na]+'"
• [methods] 3D conformation generation uses ETKDGv3 algorithm via RDKit: "python scripts/hmdb2pkl.py --data_config_path ./molnetpack/config/preprocess_etkdgv3.yml"
• [methods] Training requires preprocessed PKL files with aligned experimental data: "python scripts/predict.py --task msms --test_data ./data/hmdb/hmdb_etkdgv3_$i.pkl"
• [readme] Transfer learning is enabled by specifying a pretrained encoder checkpoint: "Fine-tune from a pretrained checkpoint"
• [readme] Task formulation supports multiple prediction objectives: MS/MS, retention time, and CCS: "task="msms", or "rt" / "ccs""