proxai-ms 0.1.3

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 PyPI

pip install proxai-ms

From source

git clone https://github.com/benjaminnigjeh/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

- <prefix>_pseudo_ms1_positive.csv  
- <prefix>_pseudo_ms1_negative.csv  
- <prefix>_pseudo_ms1_plot.png  

---

## 🧪 Python API

Run the full ProXAI pipeline directly in Python:

```python
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