metabolite-peak-assignment-from-nmr
Summary
Apply a Transformer-based deep learning model (NMRformer) to assign chemical peaks in 1D ¹H NMR spectra to their corresponding metabolites. This skill automates the challenging task of peak-to-metabolite mapping by processing filtered spectral data through a learned neural network, producing probability-ranked metabolite identifications.
When to use
You have a 1D ¹H NMR spectrum (as chemical shift vs. intensity) and a corresponding peak list (chemical shift values), and you need to identify which metabolites are responsible for each detected peak. Use this skill when manual peak assignment is infeasible or when you want to leverage learned patterns from large NMR training data to improve assignment accuracy and consistency.
When NOT to use
- Input peak list is already known to contain many unfiltered, noisy, or artifact peaks—preprocess with domain expertise or signal-processing filters before invoking this skill.
- You are analyzing a different NMR experiment type (e.g., 2D COSY, HSQC, or ¹³C NMR)—NMRformer is trained on 1D ¹H NMR only.
- Your spectral data is in a non-standard format (e.g., raw instrument binary, netCDF, Bruker FID) and has not been converted to the required CSV/TXT format.
Inputs
- CSV file with two columns: chemical shift (ppm) and ¹H NMR spectral intensity
- TXT file with one peak chemical shift (ppm) per row
- Pre-trained NMRformer PyTorch model checkpoint
Outputs
- output.csv file containing metabolite identifications, chemical shift assignments, and probability scores for each input peak
How to apply
Load the pre-trained NMRformer PyTorch model from the repository. Import your spectrum as a CSV file (first column: chemical shift, second column: intensity) and peak list as a TXT file (one chemical shift per row). Before passing data to the model, filter the peak list to remove unrecognized or noisy peaks—the model's output is sensitive to spurious peaks, so this curation step is critical. Pass the cleaned spectrum and peak data through the NMRformer Transformer encoder to generate peak-to-metabolite assignments with associated probabilities. Export the results to output.csv, which will contain metabolite names and confidence scores for each input peak.
Related tools
- NMRformer (Transformer-based neural network model that encodes filtered peak and spectrum data to predict metabolite assignments) — https://github.com/zza1211/NMRformer
- PyTorch (Deep learning framework for loading and executing the pre-trained NMRformer model)
- Pandas (Data import and manipulation for reading CSV spectrum files and structuring output results)
- NumPy (Numerical computation and array operations on spectral intensity and peak data)
- SciPy (Signal processing utilities for optional peak filtering and noise detection)
Examples
# In NMRformer.ipynb: load model, import spectrum from example_data/spectrum.csv and peaks from example_data/peaks.txt, filter peaks, pass through model, export output.csv
Evaluation signals
- output.csv contains one row per input peak with non-null metabolite identifications and probability scores between 0 and 1
- Metabolite assignments match known reference standards or prior manual curation for a subset of test peaks (e.g., validation accuracy > 80%)
- No rows in output.csv have missing or NaN metabolite names or probability values
- Peak chemical shifts in output.csv match the input peak list within floating-point precision (±1e-6 ppm)
- Probability scores are sorted or ranked consistently (e.g., highest-confidence metabolite listed first per peak)
Limitations
- Model performance degrades significantly when input peak lists contain unrecognized or noisy peaks; manual pre-filtering is essential.
- NMRformer is trained exclusively on 1D ¹H NMR spectra; applicability to other modalities (2D, ¹³C, DEPT) is unknown.
- Output probabilities reflect model confidence, not ground-truth accuracy; results should be validated against experimental standards or orthogonal methods.
- No changelog or version history is provided, making it unclear how model performance may vary across updates or different checkpoint versions.
- Performance on metabolites outside the training set or in complex biological matrices with many co-eluting compounds is not characterized.
Evidence
- [readme] Metabolite identification from 1D 1H NMR spectra is a major challenge in NMR-based metabolomics.: "Metabolite identification from 1D 1H NMR spectra is a major challenge in NMR-based metabolomics"
- [readme] NMRformer is a Transformer-based deep learning framework for accurate peak assignment and metabolite identification in 1D 1H NMR spectroscopy.: "NMRformer, a Transformer-based deep learning framework for accurate peak assignment and metabolite identification in 1D 1H NMR spectroscopy"
- [readme] When you input peaks that cannot be recognized or noisy peaks into the model, it will affect the output of the model, so please try to filter the peaks in the input spectral peak list as much as possible.: "When you input peaks that cannot be recognized or noisy peaks into the model, it will affect the output of the model, so please try to filter the peaks in the input spectral peak list as much as"
- [readme] In NMRformer.ipynb, you can load the model and input data, resulting in an output.csv file that contains the corresponding metabolites and probabilities for each peak.: "In NMRformer.ipynb, you can load the model and input data, resulting in an output.csv file that contains the corresponding metabolites and probabilities for each peak"
- [readme] The uploaded files include: 1. csv file, the first column is the chemical shift, and the second column is the 1H NMR spectrum. 2. txt file, one data per row, representing the chemical shift of the peak in the spectrum.: "csv file, the first column is the chemical shift, and the second column is the 1H NMR spectrum. 2. txt file, one data per row, representing the chemical shift of the peak"
1---2name: metabolite-peak-assignment-from-nmr3description: Use when you have a 1D ¹H NMR spectrum (as chemical shift vs. intensity) and a corresponding peak list (chemical shift values), and you need to identify which metabolites are responsible for each detected peak.4license: CC-BY-4.05---67# metabolite-peak-assignment-from-nmr89## Summary1011Apply a Transformer-based deep learning model (NMRformer) to assign chemical peaks in 1D ¹H NMR spectra to their corresponding metabolites. This skill automates the challenging task of peak-to-metabolite mapping by processing filtered spectral data through a learned neural network, producing probability-ranked metabolite identifications.1213## When to use1415You have a 1D ¹H NMR spectrum (as chemical shift vs. intensity) and a corresponding peak list (chemical shift values), and you need to identify which metabolites are responsible for each detected peak. Use this skill when manual peak assignment is infeasible or when you want to leverage learned patterns from large NMR training data to improve assignment accuracy and consistency.1617## When NOT to use1819- Input peak list is already known to contain many unfiltered, noisy, or artifact peaks—preprocess with domain expertise or signal-processing filters before invoking this skill.20- You are analyzing a different NMR experiment type (e.g., 2D COSY, HSQC, or ¹³C NMR)—NMRformer is trained on 1D ¹H NMR only.21- Your spectral data is in a non-standard format (e.g., raw instrument binary, netCDF, Bruker FID) and has not been converted to the required CSV/TXT format.2223## Inputs2425- CSV file with two columns: chemical shift (ppm) and ¹H NMR spectral intensity26- TXT file with one peak chemical shift (ppm) per row27- Pre-trained NMRformer PyTorch model checkpoint2829## Outputs3031- output.csv file containing metabolite identifications, chemical shift assignments, and probability scores for each input peak3233## How to apply3435Load the pre-trained NMRformer PyTorch model from the repository. Import your spectrum as a CSV file (first column: chemical shift, second column: intensity) and peak list as a TXT file (one chemical shift per row). Before passing data to the model, filter the peak list to remove unrecognized or noisy peaks—the model's output is sensitive to spurious peaks, so this curation step is critical. Pass the cleaned spectrum and peak data through the NMRformer Transformer encoder to generate peak-to-metabolite assignments with associated probabilities. Export the results to output.csv, which will contain metabolite names and confidence scores for each input peak.3637## Related tools3839- **NMRformer** (Transformer-based neural network model that encodes filtered peak and spectrum data to predict metabolite assignments) — https://github.com/zza1211/NMRformer40- **PyTorch** (Deep learning framework for loading and executing the pre-trained NMRformer model)41- **Pandas** (Data import and manipulation for reading CSV spectrum files and structuring output results)42- **NumPy** (Numerical computation and array operations on spectral intensity and peak data)43- **SciPy** (Signal processing utilities for optional peak filtering and noise detection)4445## Examples4647```48# In NMRformer.ipynb: load model, import spectrum from example_data/spectrum.csv and peaks from example_data/peaks.txt, filter peaks, pass through model, export output.csv49```5051## Evaluation signals5253- output.csv contains one row per input peak with non-null metabolite identifications and probability scores between 0 and 154- Metabolite assignments match known reference standards or prior manual curation for a subset of test peaks (e.g., validation accuracy > 80%)55- No rows in output.csv have missing or NaN metabolite names or probability values56- Peak chemical shifts in output.csv match the input peak list within floating-point precision (±1e-6 ppm)57- Probability scores are sorted or ranked consistently (e.g., highest-confidence metabolite listed first per peak)5859## Limitations6061- Model performance degrades significantly when input peak lists contain unrecognized or noisy peaks; manual pre-filtering is essential.62- NMRformer is trained exclusively on 1D ¹H NMR spectra; applicability to other modalities (2D, ¹³C, DEPT) is unknown.63- Output probabilities reflect model confidence, not ground-truth accuracy; results should be validated against experimental standards or orthogonal methods.64- No changelog or version history is provided, making it unclear how model performance may vary across updates or different checkpoint versions.65- Performance on metabolites outside the training set or in complex biological matrices with many co-eluting compounds is not characterized.6667## Evidence6869- [readme] Metabolite identification from 1D 1H NMR spectra is a major challenge in NMR-based metabolomics.: "Metabolite identification from 1D 1H NMR spectra is a major challenge in NMR-based metabolomics"70- [readme] NMRformer is a Transformer-based deep learning framework for accurate peak assignment and metabolite identification in 1D 1H NMR spectroscopy.: "NMRformer, a Transformer-based deep learning framework for accurate peak assignment and metabolite identification in 1D 1H NMR spectroscopy"71- [readme] When you input peaks that cannot be recognized or noisy peaks into the model, it will affect the output of the model, so please try to filter the peaks in the input spectral peak list as much as possible.: "When you input peaks that cannot be recognized or noisy peaks into the model, it will affect the output of the model, so please try to filter the peaks in the input spectral peak list as much as"72- [readme] In NMRformer.ipynb, you can load the model and input data, resulting in an output.csv file that contains the corresponding metabolites and probabilities for each peak.: "In NMRformer.ipynb, you can load the model and input data, resulting in an output.csv file that contains the corresponding metabolites and probabilities for each peak"73- [readme] The uploaded files include: 1. csv file, the first column is the chemical shift, and the second column is the 1H NMR spectrum. 2. txt file, one data per row, representing the chemical shift of the peak in the spectrum.: "csv file, the first column is the chemical shift, and the second column is the 1H NMR spectrum. 2. txt file, one data per row, representing the chemical shift of the peak"
HolobiomicsLab 