PIPK-Net

The repository provides the PIPK-Net package (model architecture, molecular featurisation, the training engine with nested cross-validation, and a command-line and Python inference interface), the pre-trained five-fold ensemble weights for all three model variants (A_baseline, B_ion, and the physiology-informed C_physio/ PIPK-Net), and a dedicated reproduce module that regenerates every figure and table reported in the manuscript and Supplementary Information from the supplied artefacts. A worked tutorial and a quick-start script are also included.

---

Overview

PIPK-Net is a deep learning framework designed to address the parameterisation needs of Physiologically Based Pharmacokinetic (PBPK) models for orally administered small-molecule drugs.

Accurate systemic PK prediction is often challenging due to the complexity of absorption, distribution, and elimination. PIPK-Net addresses this by integrating two novel components:

1. Learnable Ionisation Embeddings: Rather than treating ionisation as a fixed descriptor, the model encodes physiological state at pH 7.4 as a learnable embedding, capturing how charge influences drug fate (e.g., albumin binding for anions vs. tissue accumulation for cations).
2. Mechanistic Loss Constraints: The architecture embeds a mass-balance constraint (t_1/2 = ln 2 · V_d / CL) directly into the training objective, ensuring that interdependent parameters remain consistent—a property often lacking in purely data-driven models.

Figure 1. Overview of the PIPK-Net methodology and dataset characterisation. (A) Scaffold-split dataset diagnostics. (1) Example Bemis-Murcko generic scaffolds and drugs from the cross-validation (CV) (blue) and independent test (red) sets across a range of scaffold sizes (N = drugs sharing each scaffold). (2) Tanimoto similarity between independent-test compounds and their nearest cross-validation neighbour; vertical lines mark 0.4 (distinct scaffolds) and 0.8 (near-duplicate threshold). The median is 0.33, and >98% of test compounds remain below 0.7. (3) Physicochemical space (LogP vs. molecular weight), indicating comparable coverage between sets. (4) Distributions of the 7 PK endpoints, also comparable between sets. (B) Scaffold-based data partition and nested cross-validation. The 1167 oral drugs span 609 Bemis-Murcko scaffolds; 484 scaffolds (n = 904 drugs) form the cross-validation set, and the remaining 123 scaffolds (n = 263 drugs) form the held-out independent test set. Within the CV set, 5-fold outer cross-validation provides ensemble performance estimation, with inner-fold hyperparameter optimisation per outer fold. (C) Model overview. Each input SMILES string is converted to a molecular graph and passed through a Graph Convolutional Neural Network (GCNN) to produce a structural embedding (h_struct); an ionisation-state embedding h_ion (16- or 32-dimensional, tuned via inner CV) is concatenated to produce the final molecular representation. This is fed into a multi-layer perceptron, predicting the 7 PK endpoints. The total loss combines a task-weighted MSE term and a physiology-informed constraint enforcing the mass-balance relationship t_1/2 = ln(2)·V_d/CL; λ is a tunable weight. Selumetinib is shown as an example, with predictions averaged across the PIPK-Net ensemble. Scaffold-based partitioning assigns all 5 drugs sharing its benzimidazole-derived scaffold to the independent test set (panel A (1), far right), preventing data leakage.

---

Project Structure

• pipknet/: Core package — architecture (models.py), featurisers, training engine, nested-CV training.py, CSV loader data.py, high-level inference.py (PIPKNetPredictor), and CLI.
• examples/: tutorial.ipynb walkthrough and quickstart.py.
• checkpoints/: Pre-trained ensemble weights (5-fold CV).
  • A_baseline: Baseline model variant
  • B_ion: Model variant incorporating ionisation embeddings
  • C_physio: The recommended Physiology-Informed variant (ionisation embeddings and physiological loss constraint)
• reproduce/: Scripts that regenerate every manuscript/supplementary figure and table from the checkpoints (see reproduce/README.md).
• data/: Clinical reference table for oral drugs (from eDrug3D dataset, downloaded August 2025), data splits, frozen predictions, and the benchmark results.
• tests/: Smoke tests (pytest).
• environment.yml: Conda environment definition for reproducibility.
• pyproject.toml: Python package configuration.

---

Installation

1. Set Up Environment

Recreate the exact research environment using the provided .yml file:

conda env create -f environment.yml
conda activate pk_project

2. Install PIPK-Net

Install the package in editable mode from the root directory:

pip install -e .

Usage

Tutorial

A worked, runnable walkthrough (single-molecule + batch prediction, the effect of ionisation state, mass-balance consistency, and variant comparison) is in examples/tutorial.ipynb. A script version is examples/quickstart.py:

python examples/quickstart.py

Python API

Load the 5-fold ensemble once, then predict single molecules or batches:

from pipknet import PIPKNetPredictor

predictor = PIPKNetPredictor("checkpoints/C_physio")

# single molecule -> mean +/- std table (physical units)
predictor.predict("CN1C=NC2=C1C=C(C(=C2F)NC3=C(C=C(C=C3)Br)Cl)C(=O)NOCCO", ion_type="neutral")

# batch from a DataFrame, list of dicts, or a CSV with SMILES[, IonType, Name]
predictor.predict_batch("example_drugs.csv")

Command-line interface

PIPK-Net also provides a CLI for single-molecule analysis and batch screening.

Single molecule prediction

Provide a SMILES string to get an ensemble prediction with uncertainty:

python -m pipknet.cli predict --smiles "CC1([C@@H](N2[C@H](S1)[C@@H](C2=O)NC(=O)COC3=CC=CC=C3)C(=O)O)C" --ion anionic --weights ./checkpoints/C_physio

Batch screening

python -m pipknet.cli predict --file example_drugs.csv --weights ./checkpoints/C_physio --output results.csv

Training

Train a variant from scratch with nested 5-fold scaffold cross-validation. The input CSV needs a SMILES column, an optional IonType column, and the raw physical-unit PK columns (t1/2(hour), VD(liter), Cl(liter/hour), F(percentage), PPB(percentage), Cmax_uM, Tmax):

python -m pipknet.cli train --data e_drug3d_oral.csv --variant C_physio --out checkpoints

Each outer fold writes best_outer_model.pt, config.json, scaler.json, predictions.csv and metrics.csv. Add --quick for a fast smoke run with a reduced hyperparameter grid (not for publication). The full grid search is compute-intensive; a GPU is recommended.

Reproducing the paper

The reproduce/ package regenerates every manuscript and supplementary figure and table from the checkpoints:

python -m reproduce.predictions   # freeze per-model predictions (one-time)
python -m reproduce.run_all        # figures -> outputs/figures, tables -> outputs/tables

See reproduce/README.md for the figure/table mapping.

Tests

pip install -e ".[test]"
pytest tests/          # or: python tests/test_smoke.py

Output Parameters

The model provides the Mean ± Standard Deviation across the 5-fold ensemble for seven parameters:

Parameter	Unit	Description
t_half	h	Elimination half-life
Vd	L	Volume of distribution
CL	L/h	Systemic body clearance
F	%	Oral bioavailability
PPB	%	Plasma protein binding
Cmax	μM	Peak plasma concentration
Tmax	h	Time to reach peak concentration

---

Citation

If you use PIPK-Net in your research, please cite our manuscript:

PIPK-Net: Physiology-Informed Graph Neural Network for the Multitask Prediction of Systemic Pharmacokinetic Properties from Oral Drugs
T. Pham, M. Ghafoor, J. Delgado-San Martin, J. Chiong, S. Khoo, D. Wang, M. Siccardi