Neural Network Architecture Design

---
name: neural-network-architecture-design
description: Use when you have raw mzML files and feature tables (CSV from mzMine
  or XCMS) for LCMS data, have generated training/validation/test batches with known
  class imbalance, and need to train a CNN model from scratch to achieve AUC ROC >
  0.9 for distinguishing true from false positive MS1 peaks.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_0337
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3373
  - http://edamontology.org/topic_0602
  - http://edamontology.org/topic_3372
  - http://edamontology.org/topic_3473
  tools:
  - NeatMS
  - Python
  - TensorFlow
  - Keras
  - scikit-learn
  - pandas
  - NumPy
  - Jupyter Notebook
  - RDKit
  - PyTorch
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1021/acs.analchem.1c02220
  title: neatms
- doi: 10.1038/s42004-023-00932-3
  title: ''
evidence_spans:
- NeatMS provides the necessary functions to do that, all we will have to do is create
  a `Neural network handler` object
- Calling the method `get_threshold()` will compute and return the optimal threshold
- After installation, you should be able to import NeatMS
- Import the required libraries first
- calling the training method (1000 by default). NeatMS does not currently provides
  callback functions to automatically stop the training. Calling the training method
  will simply resume the training
- from keras.optimizers import SGD, Adam
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_neatms
    doi: 10.1021/acs.analchem.1c02220
    title: neatms
  - build: coll_spec2mol_cq
    doi: 10.1038/s42004-023-00932-3
    title: Spec2Mol
  dedup_kept_from: coll_neatms
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/acs.analchem.1c02220
  all_source_dois:
  - 10.1021/acs.analchem.1c02220
  - 10.1038/s42004-023-00932-3
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# neural-network-architecture-design

## Summary

Design and instantiate a CNN architecture for automated LCMS false positive peak classification, tuned with specific hyperparameters to balance training convergence and validation generalization. This skill is essential when building a fresh neural network model for MS1 peak filtering tasks where domain-specific parameters (matrix size, margin, scan count thresholds) and optimizer settings directly impact classification performance.

## When to use

You have raw mzML files and feature tables (CSV from mzMine or XCMS) for LCMS data, have generated training/validation/test batches with known class imbalance, and need to train a CNN model from scratch to achieve AUC ROC > 0.9 for distinguishing true from false positive MS1 peaks. Use this skill when full model training is preferred over transfer learning (i.e., you have ≥500 peaks per class available).

## When NOT to use

- Input dataset has fewer than 500 labeled peaks in the smallest class — transfer learning is recommended instead.
- Feature table is not in CSV format or was not generated by mzMine/XCMS — data import must be handled separately first.
- You have a pre-trained model suitable for your task and only need to tune final layers — use transfer learning workflow instead.

## Inputs

- Raw mzML files (LC-MS data)
- Feature table in CSV format (mzMine or XCMS output)
- Training/validation/test batches (80:10:10 split) from Neural Network Handler
- Keras/TensorFlow training logs

## Outputs

- Trained CNN model (Keras/TensorFlow object)
- Training and validation accuracy curves
- ROC curve and AUC ROC score
- True vs. false positive classification DataFrame

## How to apply

Initialize a Neural Network Handler with domain-specific parameters: matrice_size=120 (image patch dimensions), margin=1 (pixel padding around detected peaks), and min_scan_num=5 (minimum spectral points per peak). Call create_batches(validation_split=0.1, normalise_class=False) to generate 80:10:10 training/test/validation splits. Create a fresh CNN model via create_model(lr=0.00001, optimizer='Adam') — the learning rate of 1e-5 is critical to prevent gradient instability on normalized batch inputs. Train via train_model(1000) starting with 1000 epochs, monitoring returned Keras/TensorFlow logs for training and validation accuracy convergence. If no plateau is observed after initial training, resume training by calling train_model() again with additional epochs. Halt training when validation accuracy plateaus or training accuracy reaches ~100% while validation lags significantly (indicating overfitting). Compute final ROC-AUC using get_true_vs_false_positive_df() paired with scikit-learn's auc() function on False Positive Rate vs. True Positive Rate.

## Related tools

- **NeatMS** (Provides Neural Network Handler class, batch creation, model initialization (create_model), training orchestration (train_model), and evaluation utilities (get_true_vs_false_positive_df) for LCMS peak classification) — https://github.com/bihealth/NeatMS
- **TensorFlow** (Backend computational engine for CNN model construction and training; manages gradient computation and optimization)
- **Keras** (High-level API layer for defining CNN architecture, optimizer selection (Adam), and learning rate specification)
- **scikit-learn** (Computes ROC curve and AUC metric from true vs. predicted classification labels)
- **NumPy** (Numerical array operations for batch data manipulation and feature preprocessing)
- **pandas** (Loads and manipulates feature tables (CSV) and classification results DataFrames)

## Examples

```
from neatms import NeatMSExperiment, NeuralNetworkHandler
handler = NeuralNetworkHandler()
handler.create_batches(validation_split=0.1, normalise_class=False)
model = handler.create_model(lr=0.00001, optimizer='Adam')
handler.train_model(1000)
df = handler.get_true_vs_false_positive_df()
from sklearn.metrics import auc
auc_score = auc(df['fpr'], df['tpr'])
```

## Evaluation signals

- Training and validation accuracy curves are parallel and both plateau by final epoch (no gap > 5–10% indicates no overfitting).
- Final AUC ROC score is ≥ 0.9 on the held-out test set, computed via scikit-learn.metrics.auc(fpr, tpr).
- Validation accuracy is within 2–5% of training accuracy at convergence; training accuracy does not reach ~100% while validation stagnates.
- get_true_vs_false_positive_df() DataFrame contains predictions for all test samples with no NaN values in predicted class column.
- Model weights file is saved and can be reloaded; training can be resumed via train_model() without reinitializing parameters.

## Limitations

- NeatMS does not provide automatic early stopping callbacks; manual monitoring and halting of training is required to avoid overfitting.
- Requires ≥500 labeled peaks per class for reliable full model training; smaller datasets will underperform and likely overfit.
- The fixed matrice_size=120 and margin=1 parameters assume consistent peak shape and isotope pattern width in input mzML files; non-standard peak geometries may require retuning.
- No changelog is available; version compatibility between NeatMS, TensorFlow, and Keras must be verified independently.
- The learning rate of 0.00001 is optimized for the provided example dataset; other LCMS instruments or preprocessing pipelines may require empirical re-tuning.

## Evidence

- [other] Create a Neural Network Handler with default parameters (matrice_size=120, margin=1, min_scan_num=5): "Create a Neural Network Handler with default parameters (matrice_size=120, margin=1, min_scan_num=5) and call create_batches(validation_split=0.1, normalise_class=False) to generate training, test,"
- [other] Initialize a fresh CNN model using create_model(lr=0.00001, optimizer='Adam') with default hyperparameters and train via train_model(1000): "Initialize a fresh CNN model using create_model(lr=0.00001, optimizer='Adam') with default hyperparameters and train via train_model(1000) for an initial epoch count."
- [other] Monitor training and validation accuracy on the returned Keras/TensorFlow logs; if no plateau is observed, resume training by calling train_model() again: "Monitor training and validation accuracy on the returned Keras/TensorFlow logs; if no plateau is observed, resume training by calling train_model() again with additional epochs."
- [other] Inspect training and validation accuracy curves to confirm no overfitting (training accuracy ≈ validation accuracy); if training reaches ~100% while validation lags significantly, halt training.: "Inspect training and validation accuracy curves to confirm no overfitting (training accuracy ≈ validation accuracy); if training reaches ~100% while validation lags significantly, halt training."
- [intro] NeatMS relies on neural network based classification to enable automated filtering of false positive MS1 peaks reported by commonly used LCMS data processing pipelines.: "NeatMS relies on neural network based classification to enable automated filtering of false positive MS1 peaks reported by commonly used LCMS data processing pipelines."
- [other] Compute ROC curve and AUC using get_true_vs_false_positive_df() data with scikit-learn's auc() function on False Positive Rate vs. True Positive Rate.: "Compute ROC curve and AUC using get_true_vs_false_positive_df() data with scikit-learn's auc() function on False Positive Rate vs. True Positive Rate."
- [methods] When choosing this option, we recommend that you have at the very least 500 peaks for each class (or 500 peaks in the smallest class).: "When choosing this option, we recommend that you have at the very least 500 peaks for each class (or 500 peaks in the smallest class)."
- [methods] NeatMS does not currently provides callback functions to automatically stop the training. Calling the training method will simply resume the training.: "NeatMS does not currently provides callback functions to automatically stop the training. Calling the training method will simply resume the training."