🧬 Protein Stability Prediction Pipeline

A production-grade machine learning pipeline for predicting and optimizing protein thermal stability through rational mutation design. Combines biophysical feature engineering, multi-engine mutation generation (RAG, TRIZ-LLM, MSA consensus), and evolutionary multi-objective optimization.

Note: This repository includes a Lite Mode optimized for 16GB RAM devices. The full pipeline is designed for HPC/cloud environments with significantly larger datasets and computation.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              ORCHESTRATOR (run_all.py)                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
    ┌──────────────┬───────────────────┴────┬──────────────────────┬─────────────┐
    ▼              ▼                        ▼                      ▼             ▼
┌────────┐    ┌───────────┐    ┌──────────────────────────┐    ┌─────────┐   ┌────────┐
│Phase 1 │    │ Phase 2   │    │        Phase 3           │    │ Phase 4 │   │Phase 5 │
│ Data   │──▶│ Feature   │ ──▶│ ┌───────┬───────┬──────┐ │──▶│ NSGA-II │──▶│Validate│
│Ingest  │    │Engineering│    │ │Engine │Engine │Engine│ │    │Optimize │   │& SHAP  │
└────────┘    └───────────┘    │ │A: RAG │B: TRIZ│C: MSA│ │    └─────────┘   └────────┘
                               │ └───────┴───────┴──────┘ │
                               └──────────────────────────┘

Pipeline Components

Phase	Component	Description
1	Data Ingestion	FireProtDB loader + Saboteur synthetic data generator
2	Feature Engineering	14D biophysical vectors (RSA, B-factor, BLOSUM, ΔVolume, etc.)
3A	Engine A: RAG	Literature mining via ChromaDB + sentence-transformers
3B	Engine B: TRIZ	Inventive problem-solving + local LLM (Ollama)
3C	Engine C: MSA	Consensus mutations from multiple sequence alignments
4	Optimization	XGBoost surrogate + NSGA-II multi-objective evolution
5	Validation	Steric clash filter, Domain of Applicability, SHAP explainability

---

⚡ Full Mode vs Lite Mode

Parameter	Full Mode	Lite Mode	Impact
PDB structures	50+	20	Dataset size
Mutants/protein	10	5	Training data
NSGA-II generations	50	20	Optimization depth
Population size	100	30	Search space
Engine B (TRIZ)	LLM-based	Skipped / Mocked	Resource usage
Typical runtime	2-4 hours	~2 minutes	-
RAM required	32GB+	16GB	-

The Lite Mode demonstrates the full pipeline architecture on reduced data. For production use with novel proteins, run Full Mode on appropriate hardware.

---

📊 Sample Results (Lite Mode Demo)

Pipeline output for Lipase A (PDB: 1ISP) target:

Rank	Mutations	Stability Score	Conservation	Confidence
1	G14P; G30P; G111P; G158P; G13A; G176P; G45V; G145P; G67P; A132I	12.16	0.72	HIGH
2	G111P; G14P; G158P; A132I; G67P; G30A; G176P; G145P	11.48	0.73	HIGH
3	G176A; G145P; G13P; G30A; G111P; G158P; G14P; G67P; A132I	11.15	0.73	HIGH

Key insight: Pipeline correctly identifies glycine→proline substitutions for rigidifying flexible loops, a well-established thermostabilization strategy.

---

💻 Requirements

• OS: Windows 10/11, Linux, macOS
• Python: 3.11+
• RAM: 16GB (Lite) / 32GB+ (Full)
• Optional: Ollama for Phase 3B LLM features

---

🚀 Quick Start

1. Setup Environment

Windows:

setup_env.bat

Linux/macOS:

chmod +x setup_env.sh && ./setup_env.sh

Manual:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. (Optional) Enable LLM Features

# Install Ollama from https://ollama.ai, then:
ollama pull qwen3:4b

3. Run Pipeline

python run_all.py

Or run individual phases:

python main_phase1.py   # Data ingestion
python main_phase2.py   # Feature engineering
python main_phase3_a.py # RAG engine
python main_phase3_b.py # TRIZ engine (requires Ollama)
python main_phase3_c.py # Consensus engine
python main_phase4.py   # Evolutionary optimization
python main_phase5.py   # Validation & explainability

---

📁 Project Structure

├── config_lite.py          # 16GB RAM settings (edit for Full Mode)
├── run_all.py              # Master orchestrator
├── main_phase*.py          # Phase entry points
├── src/
│   ├── ingestion.py        # FireProtDB + PDB fetching
│   ├── saboteur.py         # Synthetic destabilizing mutations
│   ├── physics_engine.py   # SASA/RSA calculations
│   ├── features/           # Biophysical feature extractors
│   ├── engines/            # 3 mutation generation engines
│   │   ├── engine_a/       # RAG (ChromaDB)
│   │   ├── engine_b/       # TRIZ + LLM
│   │   └── engine_c/       # MSA consensus
│   ├── optimization/       # XGBoost + NSGA-II
│   └── validation/         # Steric checks + SHAP
├── data/                   # Input data (auto-populated)
├── results/                # Output candidates + visualizations
└── docs/                   # Additional documentation

---

📤 Output Files

File	Description
results/FINAL_CANDIDATES_VALIDATED.csv	Top mutation candidates with confidence scores
results/phase4_candidates.csv	All Pareto-optimal candidates
results/viz/*.pml	PyMOL visualization scripts
results/plots/*.png	SHAP explanation plots
results/pipeline.log	Full execution log

---

⚙️ Configuration

Edit config_lite.py to customize:

# Target protein
TARGET_PDB_ID = "1isp"
TARGET_CHAIN_ID = "A"
PROTECTED_RESIDUES = [57, 102, 195]  # Active site - never mutate

# Scale up for Full Mode
MAX_PDB_DOWNLOADS = 50      # Lite: 20
NSGA2_GENERATIONS = 50      # Lite: 20
XGBOOST_ESTIMATORS = 500    # Lite: 200

---

📜 License

MIT License - See LICENSE

🤝 Contributing

See CONTRIBUTING.md for guidelines.

🔒 Security

See SECURITY.md for security policy.

📚 References

• FireProtDB - Protein stability database
• RCSB PDB - Protein structure database
• Biopython - Computational biology toolkit
• DEAP - Evolutionary algorithms