Metadata-Version: 2.4
Name: TrojanHorses
Version: 0.1.7
Summary: Mechanism-Aware Deep Learning model for antioxidant activity prediction
Author: Shiva Satija, Saveena Solanki
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ChemicalDice==0.8.4
Requires-Dist: rdkit==2023.9.6
Requires-Dist: scikit-learn==1.5.0
Requires-Dist: requests
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: torch<3.0,>=2.0
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas>=1.5
Requires-Dist: xgboost==2.0.3
Requires-Dist: joblib>=1.3

# ♞ Trojan-Horses

**Trojan-Horses** is a **Mechanism-Aware Deep Learning framework for antioxidant activity prediction**, designed to deliver both **quantitative screening performance** and **biological interpretability**.

The framework integrates two synergistic components:

- **MA-AOS (Mechanism-Aware Antioxidant Scoring)** — a **Mechanism-Informed Hierarchical Multitask Learning (MI-HMTL)** deep neural network that models antioxidant activity via engagement of key oxidative-stress signaling pathways.
- **BioChem-AOS** — a classical machine-learning classifier that complements the MI-HMTL framework by providing a global antioxidant probability score.

Both models leverages **ChemicalDice molecular embeddings generated from SMILES strings**.

---

## ✨ Key Features

- ✅ **Mechanism-aware deep learning model for antioxidant activity prediction**
- ✅ **Target- and pathway-level interpretability**
- ✅ **Dual scoring system**
  - **MA-AOS** (Mechanistic Deep-Learning score)
  - **BioChem-AOS** Antioxidant probability score

---

## 📦 Installation

Install from TestPyPI:

```bash
pip install -i https://test.pypi.org/simple/ TrojanHorses
```


## 🔑 ChemicalDice API Key

Trojan-Horses relies on **ChemicalDice** to generate molecular embeddings directly from SMILES strings.  
Therefore, a valid **ChemicalDice API key is required** to run predictions.

API keys can be obtained by filling out the access request form with your details and IP address at the following link:

**[Request ChemicalDice API Access](https://forms.gle/gPtd8Wqw4akd9Awt5)**

---

## 🧪 Usage

```python
from trojan_horses import trojan_horses

API_KEY = "YOUR_CHEMICALDICE_API_KEY"

smiles = [
    "CCO",
    "CCN(CC)CCO"
]

df = trojan_horses.predict(
    smiles=smiles,
    api_key=API_KEY
)

```

---

## 📊 Example Output

| SMILES    | BioChem-AOS | BioChem-AOS Prediction | MA-AOS | HIF_prob | KEAP-1_prob | NFkB_prob | NOX_prob | NRF2_prob | XDH_prob |
|------------|----------------|--------------------|---------------------|-----------|---------------|-------------|------------|-------------|-------------------------------|
| CCO        | 0.41 | 0 | 0.38 | 0.22 | 0.14 | 0.28 | 0.40 | 0.51 | 0.31 |
| CCN(CC)CCO | 0.78 | 1 | 0.69 | 0.65 | 0.72 | 0.58 | 0.67 | 0.81 | 0.56 |

---

### 🔬 Pathway Probability Interpretation

The following columns report **engagement probabilities predicted by the Mechanism-Aware Deep Learning model (MA-AOS)**, representing the likelihood that a compound perturbs or interacts with specific antioxidant-related pathways:

- **`HIF_prob`** – Engagement probability of the **HIF (Hypoxia-Inducible Factor)** signaling pathway.
- **`KEAP-1_prob-1`** – Engagement probability of the **KEAP-1 (Kelch-like ECH-associated protein 1)** pathway regulating NRF2 stability.
- **`NFkB_prob`** – Engagement probability of the **NF-κB** inflammatory and stress-response signaling pathway.
- **`NOX_prob`** – Engagement probability of the **NOX (NADPH oxidase)** oxidative radical–generating pathway.
- **`NRF2_prob`** – Engagement probability of the **NRF2 (Nuclear factor erythroid 2–related factor 2)** antioxidant defense pathway.
- **`XDH_prob`** – Engagement probability of the **XDH (Xanthine Dehydrogenase/Oxidase)** oxidative metabolism pathway.

Higher probabilities indicate stronger predicted pathway involvement, providing **mechanistic interpretability** alongside overall antioxidant activity scores.
