/pkpd-modeling

name: pkpd-modeling
description: Pharmacokinetic and pharmacodynamic modelling and simulation - non-compartmental analysis, compartmental and population PK, PK/PD and exposure-response, TMDD, PBPK orientation, bioequivalence, allometric scaling and first-in-human dose, drug interaction prediction, and Bayesian therapeutic drug monitoring. Use when analysing concentration-time data, deriving exposure metrics, fitting PK or PD models, or evaluating dosing regimens. Triggers include "pharmacokinetics", "pharmacodynamics", "PK/PD", "NCA", "non-compartmental", "AUC", "Cmax", "lambda z", "half-life", "clearance", "volume of distribution", "compartmental model", "population PK", "popPK", "NONMEM", "nlmixr2", "Pharmpy", "Monolix", "exposure-response", "Emax", "EC50", "indirect response", "effect compartment", "TMDD", "PBPK", "bioequivalence", "RSABE", "ABEL", "allometric scaling", "first-in-human", "MABEL", "drug-drug interaction", "DDI", "ICH M12", "concentration-QTc", "therapeutic drug monitoring", "MIPD", and "dosing regimen".
license: MIT
compatibility: Requires Python 3.11+ with numpy and scipy. No network access and no proprietary software. The estimation tools this skill orients you towards (NONMEM, Monolix, Phoenix, Simcyp, GastroPlus) are licensed separately and are never invoked by these scripts.
allowed-tools: Read Write Edit Bash
metadata:
  version: "1.2"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-27"

Pharmacokinetic and Pharmacodynamic Modelling

When to use

Any question about what the body does to a drug or what the drug does to the body: deriving exposure metrics from concentration-time data, fitting a structural model, building or checking a population analysis, choosing a dose or a regimen, relating exposure to effect, comparing formulations, or scaling to a new population.

The three rules

**1. Fix the exposure metric and the analysis population before computing anything.** AUC(0-t), AUC(0-inf), AUC(0-tau) at steady state, and Cavg are different quantities and answer different questions. So do AUCinf based on observed versus predicted Clast. Choosing after seeing the numbers is how a negative study becomes positive.

**2. Structural model, variability model, and covariate model are three separate decisions.** They get conflated constantly — an extra compartment added to absorb what is really unmodelled between-occasion variability, a covariate added to fix what is really a misspecified absorption model. Diagnose which one is wrong before changing any of them.

**3. Convergence is not identifiability.** A fit that converges with 200% relative standard error on a parameter, or a correlation of 0.99 between two, has told you the data cannot separate them. Every fitting script here reports both and flags them, because the parameter table alone looks fine in exactly this situation.

Scope

This skill computes, diagnoses, and structures. It does **not** decide that a formulation is bioequivalent, select a dose for a trial, recommend a dose for a patient, conclude that a drug has no QT liability, or replace a qualified pharmacometrician, clinical pharmacologist, or the regulatory review. The scripts report; none of them concludes. `tdm_bayes.py` in particular is a modelling aid — any change to a patient's regimen is the treating clinician's decision.

Scripts

cd skills/pkpd-modeling/scripts

| Script | Question answered | | --- | --- | | `nca.py` | What are the exposure metrics, and is the terminal phase good enough to report them? | | `fit_compartmental.py` | Which structural model do these data support, and are its parameters identifiable? | | `simulate_regimen.py` | What does this regimen do at steady state, and to what fraction of the population? | | `check_popk_dataset.py` | Will NONMEM read this dataset the way I think it will? | | `exposure_response.py` | Is there an exposure-response relationship, and is the plateau in the data? | | `bioequivalence.py` | Does the 90% CI meet the criterion, and which criterion applies? | | `allometry_and_fih.py` | What is the starting dose, or the dose in a smaller/younger population? | | `ddi_static.py` | Does the in vitro data trigger a clinical DDI study under ICH M12? | | `tdm_bayes.py` | What are this patient's individual parameters from their measured levels? |

All take `--format table|tsv|json`. Data goes to stdout, provenance and findings to stderr, so `> out.tsv` keeps them separate. Exit code is `0` for no findings, `1` when findings were raised, `2` for bad input, so any of them can gate a workflow.

Two private modules carry the shared machinery: `_models.py` (analytical solutions for linear mammillary models, plus integrated Michaelis-Menten, TMDD and indirect-response structures) and `_common.py` (I/O and reporting). Import them rather than re-deriving a Bateman function.

Workflow

1. Non-compartmental analysis

python3 nca.py -i profile.csv --dose 100 --route extravascular --partial-auc 0-24

Four choices decide the answer and are usually left implicit. This script makes all four explicit: `--auc-method` (default `linup-logdown`), `--blq-rule`, `--lambda-z-points` or an explicit `--lambda-z-window`, and whether you report `auc_inf_obs` or `auc_inf_pred`.

Lambda_z selection uses the standard rule: start from the last three quantifiable points, extend backwards, keep the longer window only if **adjusted** r-squared improves by more than 0.0001. Plain r-squared can only rise as points are added, so it would always pick the longest window. Points at or before Tmax are never eligible — including Tmax fits the tail of absorption and biases half-life, Vz and AUCinf downward.

On a noiseless simulated one-compartment oral profile with CL/F = 5, V/F = 20, ka = 1.2:

id  cmax     tmax  auc_last  lambda_z  t_half   r2_adj  auc_inf_obs  pct_auc_extrap  cl_f     vz_f
1   3.29678  1.5   19.8737   0.25      2.77259  1       19.8739      0.000781037     5.03173  20.1269