Pharmacokinetic and Pharmacodynamic Modelling

When to use

Use for concentration-time analysis, structural and population PK workflows, exposure-response, regimen simulation, bioequivalence planning, DDI screening, and research TDM calculations. Version 2.0 rejects unsupported replicate/scaled BE and oral/infusion closed-form summaries; model-target dose and lowest-HED output labels replace clinical recommendation labels. This skill computes exploratory quantities and documents assumptions; it does not establish clinical safety, recommend a patient dose, or certify a regulatory submission.

Fix the question and conventions first

1. Record the analyte (free/total drug, metabolite or complex), matrix, dose history, actual times, units, population, and assay/LLOQ. With dose in mg, volume in L and time in h, concentrations are mg/L and CL is L/h. Convert before fitting; mg/L equals micrograms/mL, not ng/mL.
2. Pre-specify the exposure metric: AUC(0-t), AUC(0-inf), and steady-state AUC(0-tau) differ. State BLQ handling, missing-data rules, terminal selection and observed/predicted Clast.
3. Separate structural, residual-variability and covariate models. Convergence and a small residual sum of squares do not establish identifiability. Inspect sensitivity rank, local uncertainty, correlations, plausible bounds, multiple starts and profile likelihoods when needed.
4. Match validation to intended use. Analytical recovery and synthetic tests verify numerical behavior; they do not validate a model in a patient population or establish clinical evidence.

Environment and output

The bundled scripts were exercised with NumPy 2.5.3 and SciPy 1.18.1 on Python 3.13. Use an isolated environment; no network, credentials or proprietary engine is needed at runtime.

cd skills/pkpd-modeling/scripts

All scripts accept --format table|tsv|json. Table/TSV data go to stdout and notes/findings to stderr; JSON includes all four components on stdout and uses null for unavailable diagnostics. Exit 0 means no findings, 1 means findings, and 2 means invalid input. Dataset validation defaults to failing on errors; --strict also fails on warnings. Inspect findings even when exit 0.

Commands below using CSV inputs are invocation templates; supply the indicated columns and a suitable study design. Tests under tests/pkpd-modeling/ execute the numerical paths with small synthetic fixtures. Do not copy the illustrative doses or targets into clinical care.

Workflow

1. Non-compartmental analysis

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

Input: id,time,conc (id optional), plus optional dose,tau,tinf,blq. Times must be non-negative and distinct per profile. BLQ, <LLOQ, a blank concentration, or blq=1 invokes the chosen BLQ convention; blanks are therefore not a general missing-sample code. Preprocess missing samples separately. --blq-rule zero|half-lloq|missing applies globally, not separately by position.

Choose --auc-method linear|linup-logdown|log. The log rule accepts positive increasing or decreasing endpoints, with linear fallback for zeros/equal values. AUC starts at the first retained sample; no dose-time extrapolation is added. Late first draws therefore bias reported CL/volume; inspect the finding. Partial AUC boundaries must be within the sampled range.

The helper's automatic lambda_z selection extends backwards from at least three positive, non-BLQ points strictly after Tmax, keeping a larger window only when adjusted R² improves by more than 0.0001. This is not Phoenix Best Fit, which favors longer windows within its 0.0001 tolerance. Manual windows also require at least three post-Tmax points and a declining slope. An IV bolus C0 could be eligible in other software; this helper deliberately excludes Tmax.

Inspect the selected time range, span in half-lives, residuals and percent extrapolation. The 20% extrapolation, 0.8 adjusted R² and two-half-life flags are screening conventions, not universal acceptance rules. For a manual tail ending early, predicted Clast is evaluated at the actual last quantifiable time. Report AUCinf_obs or AUCinf_pred explicitly.

--tau requires a sampled single interval [0,tau] and assumes demonstrated steady state. It reports AUCtau, Cavg and CLss(/F), withholds single-dose AUCinf/CL/Vz/Vss, and emits a finding

…