proxai-ms 0.1.0

Mass spectrometry machine learning utilities derived from ProXAI notebooks.

ProXAI-MS

Transforming MS1 Data into Learnable Representations
via Gradient-Based Pseudo-MS1 Spectra

---

🚀 Overview

ProXAI-MS is a machine learning framework that converts MS1 data into interpretable pseudo-MS1 spectra using gradient-based saliency mapping.

It enables:

• Binary classification (control vs experiment)
• Gradient-based feature attribution
• Reconstruction of spectra from learned signal importance

---

🔥 Key Features

• Train ML models on binned MS1 data
• Gradient-based explainability
• Separate positive vs negative gradients
• Convert gradients → pseudo-MS1 spectra
• Supports flexible dataset formats (long or wide)
• CLI + Python API

---

📦 Installation

From TestPyPI

pip install -i https://test.pypi.org/simple/ proxai-ms==0.1.0

From source

git clone https://github.com//proxai-ms.git cd proxai-ms pip install -e .

---

⚙️ CLI Usage

Run the full pipeline:

proxai-ms run ^ --csv "F:\20251110\dataset_rt.csv" ^ --label-column target ^ --bin-column bin ^ --bin-values 15 ^ --control-labels 0 1 2 ^ --experiment-labels 3 4 ^ --out-prefix "F:\20261110\proxai_test"

---

🔹 Arguments

• --csv → Input dataset
• --label-column → Label column
• --bin-column → Column for bin grouping
• --bin-values → Number of bins per sample
• --control-labels → Control group labels
• --experiment-labels → Experiment group labels
• --out-prefix → Output prefix

---

📤 Outputs

• _pseudo_ms1_positive.csv
• _pseudo_ms1_negative.csv
• _pseudo_ms1_plot.png

---

🧪 Python API

from proxai_ms import run_pipeline

result = run_pipeline( csv_path="dataset.csv", label_column="target", bin_column="bin", bin_values=15, control_labels=[0,1,2], experiment_labels=[3,4], )

---

📊 Input Format

Supports:

Wide format

Rows = samples, columns = m/z bins

Long format

• bin column (grouping index)
• intensity values
• label column

---

🔬 Core Concept

ProXAI learns signal importance via gradients:

• Positive gradients → experiment signal
• Negative gradients → control signal

These are mapped back to spectral space to form:

Pseudo-MS1 = learned biochemical representation

Unlike traditional pipelines:

• No peak picking required
• No manual feature engineering
• Fully data-driven representation learning

---

🧱 Project Structure

proxai-ms/

├── assets/
├── src/proxai_ms/
│ ├── training.py
│ ├── explain.py
│ ├── pipeline.py
│ └── cli.py
├── notebooks/
├── docs/
├── scripts/
└── pyproject.toml

---

⚠️ Important Notes

• Disable normalization if gradients collapse to zero
• Avoid averaging gradients across samples incorrectly
• Always separate positive and negative gradients before aggregation

---

🛣️ Roadmap

• Deep learning models (CNN / Transformer)
• Multi-class classification
• UniDec integration
• mzML export
• GUI (ProXAI Desktop)

---

👨‍🔬 Author

Benjamin Nouri Nigjeh
Proteomics • Machine Learning • Mass Spectrometry

---

📜 License

MIT License