Expert review preparation

expert_review_preparation

Summary

Prepare molecular structure and MS/MS spectral data for expert human review and validation by filtering inputs to supported atom types and precursor forms, then generating predicted spectra that can be compared against ground truth. This skill is applied when outputs from 3DMolMS or related predictive models require quality assurance before publication or integration into reference libraries.

When to use

When you have a set of molecular structures (from HMDB, RefMet, MoNA, NIST, or custom sources) with associated MS/MS spectra or retention time data, and need to identify which molecules and spectra are suitable for expert human review—either to validate model predictions, flag edge cases for manual inspection, or prepare a curated reference library. This skill is especially relevant when integrating predictions from deep neural network models into reference databases used by downstream analyses.

When NOT to use

• Input molecules contain unsupported atom types (e.g., Si, P-containing heterocycles not in the supported list); filtering will remove them, potentially biasing results.
• Precursor ion type is unknown or not in the supported set ([M+H]+, [M-H]−, [M+H-H2O]+, [M+Na]+); predictions will be unreliable or absent.
• Input structures already have been manually curated and validated by experts; this skill adds filtering steps that may exclude valid data without adding new information.

Inputs

• Molecular structure file (CSV, SDF, or PKL format)
• Ground truth MS/MS spectrum dataset (MGF, SDF, or PKL with experimental spectra)
• 3D molecular conformations (e.g., generated via ETKDGv3)
• Precursor ion annotations (adduct type)

Outputs

• Filtered molecule list (CSV or PKL) meeting atom count and type constraints
• Predicted MS/MS spectra in MGF format
• Spectral similarity scores (CSV) comparing predicted vs. experimental spectra
• Ranked review queue (CSV) sorted by confidence or match score for expert triage

How to apply

First, filter the input structures by applying three sequential constraints: (1) atom count ≤300 atoms; (2) atom types limited to C, O, N, H, P, S, F, Cl, B, Br, I, Na; (3) precursor types in the supported set ([M+H]+, [M-H]−, [M+H-H2O]+, [M+Na]+). Unsupported inputs are automatically filtered during dataset loading. Second, generate predicted MS/MS spectra using the 3DMolMS model (or equivalent) on the filtered molecules, saving predictions in MGF format. Third, compute similarity metrics (e.g., cosine similarity or spectral matching scores) between predicted spectra and experimental spectra from the reference database. Finally, rank molecules and spectra by prediction confidence, filtering uncertainty, or match score, and export the filtered set with metadata for expert review. Molecules failing atom-type or precursor-type constraints should not proceed to prediction, avoiding wasted computation and reducing false-positive predictions.

Related tools

• molnetpack (Python library providing the MolNet engine to load molecular data, predict MS/MS spectra, and evaluate predictions; handles CSV, MGF, and PKL input formats and wraps filtering logic.) — https://pypi.org/project/molnetpack/
• 3DMolMS (Deep neural network model that predicts MS/MS spectra from 3D molecular conformations; serves as the core prediction engine for generating candidate spectra for expert review.) — https://github.com/JosieHong/3DMolMS
• RDKit (Cheminformatics toolkit used to validate and manipulate molecular structures; filters by atom type and count before prediction.)
• PyTorch (Deep learning framework required to load and run the 3DMolMS neural network model.) — https://pytorch.org/get-started/locally/
• Koina (Web service providing no-installation access to 3DMolMS predictions via API; enables scalable expert review preparation without local GPU requirements.) — https://koina.wilhelmlab.org/docs#post-/3dmolms_qtof/infer

Examples

from molnetpack import MolNet
import torch
device = torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')
molnet_engine = MolNet(device, seed=42)
molnet_engine.load_data('./data/molecules.csv')
pred_df = molnet_engine.pred_msms(path_to_results='./output_msms.mgf', instrument='qtof')
results_df = molnet_engine.evaluate(test_pkl='./data/test_etkdgv3.pkl', pred_mgf='./output_msms.mgf', result_path='./eval_results.csv')

Evaluation signals

• All molecules in the filtered output have atom count ≤300 and contain only supported atom types (C, O, N, H, P, S, F, Cl, B, Br, I, Na); validate by parsing structure file and checking element types.
• All retained molecules carry precursor ion annotations from the supported set ([M+H]+, [M-H]−, [M+H-H2O]+, [M+Na]+); verify presence in input metadata.
• Predicted MGF output contains peaks with m/z and intensity values matching expected mass-spec format; check for valid peak lists and absence of NaN/inf values.
• Spectral similarity scores (e.g., cosine similarity or normalized dot product) fall in the range [0, 1] and correlate positively with expert manual validation ratings where ground truth is available.
• Review queue is sortable by confidence and does not contain duplicate molecule–spectrum pairs; sample rows to verify uniqueness and score ordering.

Limitations

• Molecules with >300 atoms are filtered out, potentially excluding large natural products or synthetic compounds relevant to some applications.
• Only four precursor ion types are supported; other adducts (e.g., [M+NH4]+, [M+K]+, [M+2H]2+) will be excluded or misclassified.
• Atom type filtering uses a fixed allowlist; uncommon but valid elements (Si, Se, Te, etc.) are not supported and will be silently dropped.
• Predictions are based on 3D conformations generated via ETKDGv3; if the true bioactive conformation differs significantly from the predicted conformation, spectral predictions may be inaccurate.
• The filtering process is deterministic and non-interactive; edge-case molecules (e.g., those with charge >1 or multiple disconnected components) may not be handled as intended.

Evidence

• [other] Atom number ≤300: "Atom number filtering [section=methods; evidence='Atom number ≤300']"
• [other] Supported atom types: "Atom types: 'C', 'O', 'N', 'H', 'P', 'S', 'F', 'Cl', 'B', 'Br', 'I', 'Na'"
• [other] Supported precursor types: "Precursor types: '[M+H]+', '[M-H]-', '[M+H-H2O]+', '[M+Na]+'"
• [other] Automatic filtering during loading: "The unsupported input will be filtered out automatically when loading the dataset"
• [intro] Deep neural network prediction from 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."
• [intro] Molecular representation for downstream tasks: "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)"
• [readme] Python API for prediction and evaluation: "# Evaluate against ground truth results_df = molnet_engine.evaluate( test_pkl="./data/qtof_etkdgv3_test.pkl", pred_mgf="./output_msms.mgf", result_path="./eval_results.csv","
• [readme] Support for multiple input formats: "# Supports CSV, MGF, and PKL input molnet_engine.load_data("./examples/demo_input.csv")"