bio-admet-prediction

What this skill does

## Version Compatibility

Reference examples tested with: RDKit 2024.09+, requests 2.31+, DeepChem 2.8+, chemprop 2.0+ (note major API change from 1.x), admet-ai 1.3+, pandas 2.2+.

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# ADMET Prediction

Predict absorption, distribution, metabolism, excretion, and toxicity properties of drug candidates. ADMET prediction underpins lead selection and de-risking; calibrated, applicability-domain-aware predictions distinguish a working filter from a costly false-confidence rejection. Modern best practice combines online services (ADMETlab 3.0 with uncertainty estimates), open-source models (chemprop D-MPNN), and rule-based filters (Lipinski / Veber / BBB heuristics) -- each with known failure modes.

For PAINS / Brenk / structural alerts, see `chemoinformatics/substructure-search`. For QSAR model building from in-house data, see `chemoinformatics/qsar-modeling`.

## ADMET Model Taxonomy

| Tool | Endpoints | Architecture | Uncertainty | Access | Fails when |
|------|-----------|--------------|-------------|--------|------------|
| ADMETlab 3.0 | 119 (A,D,M,E,T + physchem + medchem) | Multi-task DMPNN + descriptors | Per-prediction | REST API (free, no auth) | Outside training distribution; metals; macrocycles |
| ADMET-AI (NVIDIA) | ~50 (focus on safety) | chemprop D-MPNN | Ensemble variance | Python package | Limited endpoints vs ADMETlab |
| DeepChem MolNet | ~30 (tox21, ToxCast, ClinTox) | Various GCN/GAT | Per-task variance | Python package | Models trained on small datasets |
| pkCSM | ~30 (absorption, distribution, toxicity) | Graph signatures + RF | None | Web service | Smaller training data |
| SwissADME | ~30 (filters + physchem) | Hand-curated rules | None | Web service (NO API) | Cannot batch programmatically |
| ProTox-3.0 | ~46 (toxicity end-points) | DT + descriptors | None | Web service | Toxicity only; LD50 categorical |
| ADMETpredictor (Simulations Plus) | ~140 | Proprietary | Per-prediction | Commercial | License cost |
| FAF-Drugs4 | filters | Rule-based | None | Web | Static rules |
| chemprop (in-house) | User-defined | D-MPNN ± descriptors | Bayesian ensemble | Python package | Requires training data |

**Decision:** For batch screening of <10k compounds with no in-house data, **ADMETlab 3.0** (free API, 119 endpoints, calibrated uncertainty) is the modern standard. For in-house QSAR on a specific endpoint with >500 measurements, train a **chemprop D-MPNN + Morgan + MOE descriptors** model (Liu et al. 2024 achieved AUC 0.956 on hERG with this combo).

## Decision Tree by Scenario

| Scenario | Workflow | Reasoning |
|----------|----------|-----------|
| Library triage, no in-house data | ADMETlab 3.0 API batch | Calibrated 119 endpoints |
| Single target, large in-house data (>500 datapoints) | chemprop D-MPNN ensemble | Beats generic models on target-specific data |
| Need calibrated probabilities | chemprop with ensemble + Platt | Native deep learning rarely calibrated |
| FDA / regulatory submission | OECD-compliant QSAR with AD | See OECD principles below |
| Quick filter for VS | Lipinski + Veber + QED >= 0.5 | Rule-based, no model needed |
| BBB penetration | TPSA <= 90, MW <= 500, HBD <= 3 (Pfizer CNS) | Wager 2010 |
| Cardiotox liability | hERG model (ADMETlab + ProTox + literature lit-check) | Triangulate; hERG critical |
| Drug-drug interaction (CYP) | CYP1A2/2C9/2C19/2D6/3A4 inhibitor + substrate | Standard set of 5 CYPs |

## OECD QSAR Principles (5 Pillars)

For regulatory-grade ADMET QSAR (REACH, ECHA, FDA submissions), models must satisfy:

1. **Defined endpoint** -- specific bioassay, units, conditions
2. **Unambiguous algorithm** -- reproducible model + code
3. **Defined applicability domain (AD)** -- where the model is valid
4. **Appropriate statistical validation** -- external test set, cross-validation
5. **Mechanistic interpretation** -- biological / chemical rationale

For non-regulatory work, AD assessment is still critical. The OECD's *applicability domain* is the workhorse: predictions outside the AD are unreliable, but operational AD measures (leverage, kNN, conformal prediction) often disagree.

## Applicability Domain Methods

| Method | Definition | Flags out-of-AD when |
|--------|-----------|----------------------|
| kNN distance | Mean distance to k nearest neighbors in training set | > training-set distribution P95 |
| Leverage (Williams) | Hat-matrix diagonal | > 3p/n (p = features, n = compounds) |
| Density (KDE on PCA) | Density in feature space | < density of training set P5 |
| Conformal prediction | Per-prediction confidence interval | Interval > tolerance |
| Bayesian variance | Ensemble or MC-dropout variance | > training-set variance P95 |

For deep-learning ADMET, **conformal prediction** (Bostrom et al. 2024) is becoming the standard.

## ADMETlab 3.0 API

The current standard for free ADMET prediction. 119 endpoints across 6 categories; per-prediction uncertainty.

**Goal:** Predict 119 ADMET endpoints with uncertainty for a batch of SMILES using a hosted API.

**Approach:** POST batches of <=500 SMILES to ADMETlab 3.0 REST endpoint and parse the returned JSON into a per-compound endpoint DataFrame.

```python
import requests
import pandas as pd

# ADMETlab 3.0 API base: https://admetlab3.scbdd.com
# Endpoints: /api/admet (full 119-endpoint batch), /api/wash (standardization),
# /api/single/admet (single SMILES), /api/render (visualization)
# See https://admetlab3.scbdd.com/apis/ for current API spec.
def admetlab_predict(smiles_list, endpoint='admet'):
    url = f'https://admetlab3.scbdd.com/api/{endpoint}'
    payload = {'smiles': smiles_list}
    response = requests.post(url, json=payload, timeout=120)
    response.raise_for_status()
    return pd.DataFrame(response.json())

smiles = ['CCO', 'c1ccc(C(=O)O)cc1', 'CC(=O)Oc1ccccc1C(=O)O']
results = admetlab_predict(smiles)  # POST batches of <=500 SMILES at a time
```

ADMETlab 3.0 endpoints (sample):
- Absorption: Caco-2 permeability (logPapp), HIA (%), Pgp inhibitor/substrate, MDCK
- Distribution: BBB+, PPB (%), VDss (L/kg), Fu (fraction unbound)
- Metabolism: CYP1A2/2C9/2C19/2D6/3A4 inhibitor / substrate
- Excretion: CL (mL/min/kg), T1/2 (h)
- Toxicity: hERG, AMES, hepatotoxicity (DILI), carcinogenicity, immunotoxicity, mutagenicity, respiratory, skin, eye, cardiotoxicity, mitochondrial, NR-AR, NR-ER, SR-MMP
- Drug-likeness: Lipinski, Veber, Ghose, Egan, Muegge, QED, SAscore

## chemprop D-MPNN for Custom Endpoints

When in-house data is available, train a target-specific model. chemprop's D-MPNN architecture + atom/bond features + optional Morgan / MOE descriptors is the modern open-source SOTA.

**Goal:** Train a target-specific ADMET classifier or regressor on in-house bioassay data.

**Approach:** Use chemprop 2.x CLI with rdkit_2d_normalized descriptor features, 5-fold scaffold-balanced split, and 5-model ensemble for uncertainty estimation.

```python
# chemprop 2.x CLI (current; 'chemprop train' with space + dashed args)
# chemprop train --data-path data.csv --task-type classification \
#                --save-dir model_dir --molecule-featurizers rdkit_2d_normalized \
#                --num-folds 5 --ensemble-size 5

# Or chemprop 2.x programmatic API (full programmatic API documented at chemprop.readthedocs.io)
# See chemoinformatics/qsar-modeling for the full chemprop 2.x training pipeline.
```

**Key:** 5-fold ensemble for calibrated uncertainty; D-MPNN + rdkit_2d_normalized typically outperforms either alone.

## hERG Cardiotoxicity (Gold Standard Endpoint)

hERG (KCNH2) blockade causes QT prolongation, Torsades de Pointes, and is the #1 reason for late-stage drug attrition. ICH S7B and FDA require non-cli