@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/pkpd-modeling/references/pbpk.md

@@ -0,0 +1,103 @@
+# Physiologically based pharmacokinetics: when it earns its cost
+
+PBPK divides the body into anatomical compartments with literature blood flows and volumes, and
+represents the drug through physicochemical and in vitro properties. Nothing about the *system* is
+fitted; the drug parameters are.
+
+## When PBPK is the right tool
+
+It earns its cost where the question requires extrapolating **outside** the observed data in a way
+a population model cannot:
+
+- **Drug interactions** — the most common regulatory use by a wide margin. Predicting an
+  untested combination, an untested dose of a perpetrator, or a staggered dosing schedule. ICH M12
+  points to PBPK when a basic model signals a possible interaction and a refined estimate is needed.
+- **Paediatric first-dose selection**, where enzyme ontogeny and organ maturation are represented
+  mechanistically instead of by an empirical maturation function.
+- **Organ impairment** — predicting exposure in hepatic or renal impairment without a dedicated
+  study.
+- **Food effect and formulation**, using absorption models (ACAT, ADAM) that represent transit,
+  dissolution and regional permeability.
+- **Tissue concentrations** that cannot be measured — brain, tumour, lung.
+
+It is the wrong tool when the question is "what is the exposure in the population I studied" — a
+population PK model answers that better, with the variability estimated rather than assumed.
+
+## Platforms
+
+| Platform | Nature | Notes |
+| --- | --- | --- |
+| **Simcyp** | Commercial (Certara) | The de facto regulatory standard for DDI; extensive validated population libraries |
+| **GastroPlus** | Commercial (Simulations Plus) | Strong oral absorption modelling (ACAT) |
+| **PK-Sim / MoBi** | **Open source** (Open Systems Pharmacology Suite, v12) | Free, credible, scriptable. `ospsuite` R package requires .NET 8 and Windows or Ubuntu |
+| **Certara PBPK / Phoenix** | Commercial | |
+
+There is no mature open-source PBPK library in Python. PK-Sim/MoBi with the R toolchain is the
+realistic open route; the Python ecosystem is limited to building the ODE system yourself.
+
+## Structure
+
+Perfusion-limited tissue (the default for most tissues and small molecules):
+
+```
+V_t * dC_t/dt = Q_t * (C_arterial - C_t / Kp_t)
+```
+
+Permeability-limited tissue splits into vascular and extravascular subcompartments and adds a
+permeability-surface-area product. Use it for tissues with tight barriers (brain), for large
+molecules, and for transporter-mediated distribution.
+
+**Tissue-to-plasma partition coefficients (Kp)** are predicted from physicochemistry rather than
+measured, most often via:
+
+- **Rodgers & Rowland** — accounts for ionisation and binding to acidic phospholipids; the usual
+  choice for bases
+- **Poulin & Theil** — lipophilicity- and composition-based; better for neutrals and acids
+- **Berezhkovskiy** — a correction to Poulin & Theil's volume terms
+- **Schmitt**
+
+Different methods can give Kp values differing several-fold, which propagates directly into Vss.
+Choosing the method that reproduces the observed Vss is a legitimate calibration step, but it must
+be reported as such.
+
+## In vitro to in vivo extrapolation
+
+Hepatic clearance is built up from intrinsic clearance measured in microsomes or hepatocytes:
+
+```
+CLint,in vivo = CLint,in vitro * MPPGL (or HPGL) * liver weight
+CL_hepatic    = Q_h * fu_b * CLint / (Q_h + fu_b * CLint)      (well-stirred model)
+```
+
+Scaling factors: microsomal protein per gram of liver ≈ 40 mg/g; hepatocytes ≈ 99-120 × 10⁶ cells/g;
+liver weight ≈ 1500-1800 g in an adult. The well-stirred model is standard; parallel-tube and
+dispersion models give different answers for high-extraction drugs.
+
+**IVIVE routinely under-predicts clearance**, often 2-5 fold, especially for low-clearance
+compounds. Empirical scaling factors are widely applied and must be declared. This is the weakest
+link in a PBPK model and the first place to look when predictions are off.
+
+## Verification and credibility
+
+A PBPK model used for a regulatory decision must be *verified* against observed clinical data
+before being applied to the untested scenario, and the standard of verification scales with how
+much the decision rests on it:
+
+- **Predict the observed data first.** A model that cannot reproduce single-dose and multiple-dose
+  plasma profiles in healthy adults should not be used to predict a DDI.
+- **Verify the perpetrator model independently** using a known index substrate before predicting a
+  novel victim, and vice versa.
+- Acceptance is usually judged on predicted-to-observed AUC and Cmax ratios within 2-fold, with a
+  tighter criterion where the decision is more consequential.
+- **Sensitivity analysis** on the uncertain inputs — fu, fm, Ki, CLint, Kp method — is expected,
+  not optional. Report the range of predictions, not a single number.
+- Software version, model file, and every parameter with its source must be reportable. Regulators
+  ask for the model files.
+
+## Reporting
+
+State: the platform and version, the population library used, every drug-specific parameter with
+its source (measured, predicted, or optimised — and if optimised, against what), the Kp prediction
+method, the absorption model, the verification datasets and their outcome, and the sensitivity
+analysis. A PBPK prediction whose inputs are not individually traceable cannot be evaluated by
+anyone else, and will not be accepted.

package/skills/pkpd-modeling/references/pd-and-exposure-response.md

@@ -0,0 +1,149 @@
+# Pharmacodynamics and exposure-response
+
+## Direct effect models
+
+```
+Linear          E = E0 + S*C
+Log-linear      E = E0 + S*ln(C)                 no plateau; only valid over a narrow range
+Emax            E = E0 + Emax*C/(EC50 + C)
+Sigmoid Emax    E = E0 + Emax*C^h/(EC50^h + C^h)
+Inhibitory      E = E0 * (1 - Imax*C^h/(IC50^h + C^h))
+```
+
+The Hill coefficient `h` controls steepness. `h = 1` is simple hyperbolic binding; `h > 1` implies
+cooperativity or an amplification step; `h` between 2 and 4 is common for a downstream clinical
+endpoint even when the receptor binding itself is 1:1.
+
+**The single most important diagnostic is how far up the curve the data reach.** If the highest
+observed exposure produces less than half of the estimated Emax:
+
+- Emax and EC50 are extrapolations, not estimates;
+- they are strongly correlated with each other — the data determine their *ratio* (the slope of the
+  low-concentration limb, `Emax/EC50`) but not either one;
+- a "linear exposure-response" is that same limb. Linear and Emax are not competing models; linear
+  is the limit of Emax below EC50.
+
+`exposure_response.py --emax` reports `fraction_of_emax_reached` and raises a finding below 0.5.
+When you are in this regime, report the slope, not Emax and EC50.
+
+`Imax` is bounded by 1 for a model that can achieve complete inhibition; estimating `Imax > 1` means
+the model is being used outside its structure.
+
+## Indirect response models (Dayneka & Jusko)
+
+Response `R` has its own turnover: production `kin`, first-order loss `kout`, baseline
+`R0 = kin/kout`. The drug perturbs one of the two.
+
+| Type | Equation | Drug acts on | Example |
+| --- | --- | --- | --- |
+| I | `dR/dt = kin*(1 - I) - kout*R` | Inhibits production | Statins on cholesterol synthesis |
+| II | `dR/dt = kin - kout*(1 - I)*R` | Inhibits loss | Diuretic effects on sodium |
+| III | `dR/dt = kin*(1 + S) - kout*R` | Stimulates production | Erythropoietin on reticulocytes |
+| IV | `dR/dt = kin - kout*(1 + S)*R` | Stimulates loss | |
+
+where `I = Imax*C^h/(IC50^h + C^h)` and `S = Emax*C^h/(EC50^h + C^h)`.
+
+Key properties that distinguish IDR from a direct model with an effect compartment:
+
+- **The delay is dose-dependent.** Higher doses reach maximum effect sooner. An effect compartment's
+  `ke0` gives a delay that does not change with dose. This is the cleanest way to tell them apart,
+  and it requires more than one dose level to see.
+- **Return to baseline is governed by `kout`**, not by the drug's half-life. A drug can be
+  eliminated completely while the biomarker takes days to recover.
+- `kin` and `kout` are not both identifiable from a single-dose experiment with an observed
+  baseline: the baseline gives you their ratio, and only the time course of recovery gives you
+  `kout` separately.
+
+## Effect compartment (Sheiner link model)
+
+```
+dCe/dt = ke0 * (C - Ce),      E = f(Ce)
+```
+
+A hypothetical compartment with no mass that collapses counter-clockwise hysteresis. `ke0` sets the
+equilibration half-life, `ln(2)/ke0`. Use it when the hysteresis is a distribution delay
+(anaesthetics, neuromuscular blockers). Use IDR when the delay is turnover of the measured
+response.
+
+`_models.effect_compartment()` solves each interval exactly under a linear interpolation of plasma
+concentration, so the result does not depend on grid density; the usual explicit-Euler
+implementation understates Ce peaks on sparse grids.
+
+## Tolerance and rebound
+
+- **Counter-regulation**: a second, slower indirect response opposing the first. Produces tolerance
+  during dosing and rebound above baseline afterwards.
+- **Precursor pool**: a depletable pool feeding the response, giving tolerance that recovers only
+  as the pool refills.
+- **Down-regulation of receptors**: an effect compartment whose Emax declines with cumulative
+  exposure.
+
+If the response drifts back towards baseline during constant exposure, no direct or simple IDR
+model will fit, and adding compartments to the PK will not help.
+
+## Disease progression
+
+For a chronic endpoint the placebo/natural-history trajectory must be modelled, or the drug effect
+absorbs it:
+
+```
+Linear progression      S(t) = S0 + alpha*t
+Asymptotic              S(t) = S_ss + (S0 - S_ss)*exp(-k*t)
+```
+
+with the drug entering as **symptomatic** (an offset that disappears on withdrawal) or
+**disease-modifying** (a change in `alpha` that persists). Distinguishing these requires a
+randomised-withdrawal or delayed-start design; no amount of modelling of a parallel-group trial
+will separate them.
+
+## Exposure-response analysis for dose selection
+
+The three metrics, and when each is the right one:
+
+| Metric | Right for |
+| --- | --- |
+| AUC or Cavg | Effects driven by total exposure over time |
+| Cmax | Concentration-driven toxicity; some cardiovascular effects |
+| Cmin / Ctrough | Effects requiring continuous target coverage; antivirals, antibiotics |
+
+Choose on mechanism before fitting, not by comparing fits. The three are highly correlated within a
+single regimen, so the data will rarely discriminate; different regimens (same daily dose, different
+interval) are what separate them.
+
+**The confounding problem.** Patients are randomised to dose, not to exposure. Within a dose group,
+exposure varies because of clearance, and clearance varies with the same factors that drive outcome
+— renal function, hepatic function, albumin, body size, inflammatory status, disease severity. In
+oncology this produces a well-documented artefact: an apparent efficacy benefit of higher exposure
+that is partly a marker of better baseline health. Mitigations: include the confounders as
+covariates in the E-R model, use case-matching, or compare across randomised dose groups rather
+than across exposure quantiles.
+
+**Safety and efficacy E-R must both be modelled.** A dose optimal for efficacy alone is not
+optimal. FDA's Project Optimus dose-optimisation guidance (final, August 2024) makes this explicit
+for oncology: identify a dosage that maximises benefit-risk rather than the maximum tolerated dose,
+support it with PK/PD and exposure-response, and use randomised comparison of more than one dosage.
+The PK sampling and analysis plan should be in each protocol and sufficient to support population
+PK and dose/exposure-response analyses.
+
+## Concentration-QTc
+
+The framework in ICH E14 and its Q&A documents, and ICH S7B:
+
+- The threshold of regulatory concern is an effect on QTc **above 10 ms**, judged by the **upper
+  bound of the two-sided 90% confidence interval** of placebo-corrected change from baseline
+  (ΔΔQTc) at the clinically relevant exposure.
+- A prospective C-QTc analysis on Phase I data can substitute for a dedicated thorough QT study.
+  This is now the routine path rather than the exception.
+- The 2022 E14/S7B Q&A additions allow an integrated nonclinical risk assessment — a
+  "double negative" of a negative hERG assay and a negative in vivo QTc study — as supplementary
+  evidence, which relaxes the requirement to attain a high multiple of clinical exposure.
+- Correction method matters: **QTcF** (Fridericia) is standard; QTcB (Bazett) over-corrects at high
+  heart rates and should not be the primary method. A study-specific correction is preferred when
+  heart rate changes substantially.
+- The regulatory-grade model is a **linear mixed-effects** model with random intercept and slope per
+  subject and a treatment-specific intercept, on time-matched ΔQTc against concentration. The
+  linear model in `exposure_response.py --cqtc` is for screening only.
+
+Check the model assumption of linearity and of a zero intercept: a non-zero intercept suggests the
+placebo correction or the baseline is wrong, and a nonlinear concentration-effect relationship
+invalidates the extrapolation to supratherapeutic exposure.

package/skills/pkpd-modeling/references/population-pk.md

@@ -0,0 +1,133 @@
+# Population PK: estimation, covariates, BLQ, and diagnostics
+
+## The model has three layers, and they are diagnosed separately
+
+```
+Structural:   C_ij = f(theta_i, dose_i, t_ij)
+Individual:   theta_i = theta_pop * exp(eta_i),   eta_i ~ N(0, Omega)
+Residual:     y_ij = C_ij * (1 + eps_prop) + eps_add,   eps ~ N(0, Sigma)
+```
+
+Almost every difficult population model problem is a layer confusion: an extra compartment added to
+absorb between-occasion variability, a covariate added to fix a misspecified absorption model, a
+proportional error inflated to cover a structural bias at low concentrations. Identify the layer
+before changing anything.
+
+Exponential (log-normal) inter-individual variability is the default because clearances and volumes
+are positive and right-skewed. `omega` is reported as an approximate CV: `CV ≈ sqrt(exp(omega²)−1)`,
+which is close to `omega` itself below about 30%.
+
+## Estimation methods
+
+| Method | Character | When |
+| --- | --- | --- |
+| FO | First-order linearisation about eta = 0 | Obsolete for final models; biased with large IIV. Still useful for initial estimates |
+| FOCE | Linearises about the individual eta | The workhorse |
+| FOCE-I (`INTERACTION`) | FOCE with eta-epsilon interaction | **Required whenever the residual error is proportional or combined.** Omitting `INTERACTION` with a proportional error model is a common and consequential mistake |
+| Laplace | Second-order expansion | Needed for non-continuous data (categorical, count, time-to-event) and for `LIKELIHOOD`/`-2LL` models |
+| SAEM | Stochastic approximation EM | Robust to poor initial estimates and to complex models; less prone to local minima; does not itself give an objective function for comparison — follow with an IMP evaluation |
+| Importance sampling (IMP) | Monte Carlo integration | Accurate objective function; usually run after SAEM |
+| MCMC / NUTS | Full Bayesian | NONMEM 7.6 adds NUTS; also Stan, Torsten, nlmixr2 |
+
+Compare objective functions only between models fitted with the **same** method on the **same**
+records. An OFV drop obtained by switching from FOCE to IMP is not evidence about the model.
+
+## Below the limit of quantification
+
+Beal's methods, and what they actually do:
+
+| Method | Treatment | Verdict |
+| --- | --- | --- |
+| M1 | Discard all BLQ observations | Biased upward whenever a meaningful fraction is BLQ; acceptable only when that fraction is small |
+| M2 | Discard BLQ, condition the likelihood on being above LLOQ | Better than M1, rarely used |
+| M3 | **Maximum likelihood: BLQ contributes the probability that the observation is below LLOQ** | The reference method. Needs `F_FLAG=1` and the Laplace method |
+| M4 | M3 conditioned on the concentration being positive | Marginal improvement over M3 |
+| M5 | Substitute LLOQ/2 | Biased; still common; at least state it |
+| M6 | Substitute LLOQ/2 for the first BLQ in a run, discard the rest | Ad hoc |
+| M7 | Substitute 0 | Worst; badly biases the terminal phase |
+
+Rule of thumb: below roughly 10% BLQ, M1 is defensible; above that, use M3. The bias from M1 falls
+on the terminal phase, so it propagates directly into half-life, Vz and accumulation predictions.
+
+## Covariate model building
+
+Order of operations that avoids the usual traps:
+
+1. **Get the structural and variability models right first.** A covariate added to a misspecified
+   structural model can absorb the misspecification and look significant.
+2. **Include size and maturation on mechanistic grounds, not on statistical ones.** Allometric
+   weight scaling on clearance and volume is a prior, not a hypothesis to test. Fixing the
+   exponents at 0.75/1.0 is standard and usually preferable to estimating them.
+3. **Screen on eta-covariate plots**, not on the objective function, to generate candidates.
+4. **Forward inclusion at p < 0.05 (ΔOFV > 3.84, 1 df), backward elimination at p < 0.001
+   (ΔOFV > 10.83).** The asymmetry exists because forward selection on the same data inflates the
+   false-positive rate.
+5. Prefer full-model or full random-effects approaches when the goal is to *quantify* a covariate
+   effect and its uncertainty rather than to *select* covariates. Stepwise selection produces
+   biased effect sizes (selection bias towards large effects) and confidence intervals that are too
+   narrow.
+
+The likelihood-ratio test relies on the ΔOFV being chi-square distributed, which is only
+approximately true, and is **not** true on the boundary — testing whether a variance component is
+zero puts the null on the edge of the parameter space, and the nominal p-value is conservative.
+
+Correlated covariates (weight and BMI; age and renal function) cannot both be included informatively.
+Collinearity shows up as an inflated condition number and unstable estimates rather than as a
+failure.
+
+## Diagnostics
+
+**Goodness-of-fit plots.** DV vs PRED and DV vs IPRED; CWRES vs time and vs PRED; |IWRES| vs IPRED.
+Use CWRES, not WRES — WRES is computed under the FO approximation and is misleading for a
+FOCE-estimated model. Trends in CWRES against time indicate structural misspecification; a fan
+shape against PRED indicates the residual error model.
+
+**Shrinkage.** `eta shrinkage = 1 − SD(eta_i)/omega`. Above roughly 20-30%, individual estimates
+have collapsed towards the population mean, and:
+
+- eta-covariate plots become uninformative and can show spurious relationships;
+- IPRED-based diagnostics look artificially good, because IPRED is being pulled towards the data;
+- individual parameter estimates should not be used for secondary analysis.
+
+Epsilon shrinkage above ~30% makes IWRES-based diagnostics unreliable for the same reason. **FDA's
+2022 population pharmacokinetics guidance states that model selection based on shrinkage is not
+necessary** — shrinkage is a caveat on how you may interpret diagnostics, not a selection criterion.
+
+**Visual predictive check.** Simulate many replicates of the study design; plot observed percentiles
+against the simulated prediction intervals for those percentiles. Use **prediction-corrected VPC**
+whenever doses or covariates differ across subjects, otherwise the between-subject spread in
+predictions swamps the comparison. A VPC evaluates the whole model — structural, variability and
+residual — and is the single most informative diagnostic.
+
+**NPDE** are the recommended numerical counterpart: decorrelated, and should be N(0,1) under a
+correct model. Test mean, variance, and normality, and plot against time and predictions.
+
+**Parameter uncertainty.** The `$COVARIANCE` sandwich estimator is standard but fails on
+overparameterised models. Alternatives: nonparametric bootstrap (expensive; also fails when the
+model is unstable, which is informative in itself), log-likelihood profiling (best for a single
+poorly determined parameter), and sampling importance resampling (SIR), which is much cheaper than
+bootstrap and works when the covariance step fails.
+
+**Condition number** — the ratio of largest to smallest eigenvalue of the correlation matrix of the
+estimates. Above about 1000 indicates ill-conditioning and unreliable standard errors.
+`fit_compartmental.py` reports this quantity using the same definition, so the familiar threshold
+applies.
+
+## Model evaluation checklist
+
+- Minimisation successful, and the covariance step completed
+- Parameter RSEs: fixed effects below ~30%, variance components below ~50%
+- No parameter at a bound
+- Condition number below 1000
+- Eta shrinkage below 30% for any eta used in a covariate plot
+- CWRES without trend against time or PRED
+- pcVPC with observed percentiles inside the simulated intervals
+- The model reproduces the quantity the analysis exists to predict — not just the observations
+
+## What a population analysis has to report
+
+FDA's 2022 guidance expects the analysis plan to be prospective and the report to state: the data
+(including exclusions and how BLQ was handled), the structural and statistical models with
+justification, the covariate strategy defined *before* analysis, the estimation method and software
+version, the diagnostics, and the model's intended use. Deviations from the plan are documented,
+not silently absorbed.

package/skills/pkpd-modeling/references/regulatory-guidance.md

@@ -0,0 +1,82 @@
+# Regulatory guidance for PK/PD analyses
+
+Status verified 2026-07-27. ICH guidelines are published openly and their requirements are
+summarised directly; always work from the authoritative copy for a submission.
+
+## ICH
+
+| Guideline | Subject | Status |
+| --- | --- | --- |
+| **M12** | Drug interaction studies | Step 4 in 2024. FDA adopted **2 August 2024** with a Questions & Answers document; effective in the **EU 30 November 2024**; **China 29 October 2024**. First harmonised DDI guidance |
+| **M13A** | Bioequivalence for immediate-release solid oral dosage forms | Step 4 **July 2024**, effective **25 January 2025** |
+| **M13B** | Additional strengths and additional-strength biowaivers | Endorsed **13 March 2025**, Step 2b; consultation **9 April – 9 July 2025** |
+| **M13C** | BE data analysis for highly variable drugs, narrow therapeutic index drugs, and complex designs | Begins after M13B reaches Step 2. **Reference-scaling remains regional until this lands** |
+| **E11A** | Pediatric extrapolation | Step 4 **21 August 2024**, effective **25 January 2025** |
+| **M10** | Bioanalytical method validation | The assay behind every concentration; see the `analytical-method-validation` skill |
+| **E14** | Clinical evaluation of QT/QTc prolongation | With Q&A revisions; the **2022 Q&As** added the double-negative nonclinical pathway |
+| **S7B** | Nonclinical evaluation of QT prolongation | Paired with E14 through the joint Q&As |
+| **E4** | Dose-response information to support registration | Foundational for exposure-response |
+| **E7** | Studies in support of special populations: geriatrics | |
+
+## FDA
+
+| Guidance | Date | What it requires that gets missed |
+| --- | --- | --- |
+| **Population Pharmacokinetics** | Final, **February 2022** | A prospective analysis plan; explicit BLQ handling; simulation-based diagnostics (VPC, pcVPC, NPC, NPDE). Notably states that **model selection based on parameter shrinkage is not necessary** |
+| **Optimizing the Dosage of Human Prescription Drugs and Biological Products for the Treatment of Oncologic Diseases** (Project Optimus) | Final, **August 2024** | Identify a dosage maximising benefit-risk rather than the MTD; compare more than one dosage, randomised; a PK sampling and analysis plan in **each** protocol, sufficient for population PK and dose/exposure-response for safety and efficacy; early evaluation of intrinsic factors and DDIs |
+| **Exposure-Response Relationships** | 2003 | Still the reference for E-R study design and analysis |
+| **Estimating the Maximum Safe Starting Dose in Initial Clinical Trials for Therapeutics in Adult Healthy Volunteers** | 2005 | The body-surface-area HED conversion table (Km factors) used by `allometry_and_fih.py` |
+| **Physiologically Based Pharmacokinetic Analyses — Format and Content** | 2018 | What a PBPK submission must contain |
+| **Clinical Pharmacology Considerations for Human Radiolabeled Mass Balance Studies** | | |
+| Renal and hepatic impairment guidances | | Study design, including the reduced/staged design |
+
+## EMA
+
+| Guideline | Subject |
+| --- | --- |
+| Reporting the results of population pharmacokinetic analyses (EMA/CHMP/EWP/185990/2006) | Structure and content of a popPK report |
+| Investigation of bioequivalence | Being superseded in scope by ICH M13A; EMA has published implementation considerations |
+| Use of PBPK modelling and simulation | Qualification and reporting of PBPK |
+| Reporting of physiologically based pharmacokinetic modelling and simulation | |
+| Evaluation of anticancer medicinal products | Dose optimisation expectations parallel to Project Optimus |
+
+## What each analysis type has to state
+
+**Non-compartmental analysis.** Trapezoidal rule; BLQ rule at leading, embedded and trailing
+positions; the lambda_z selection rule with the window and point count per subject; whether AUCinf
+is observed- or predicted-based; exclusion criteria fixed before unblinding; software and version.
+
+**Population PK.** A prospective analysis plan. Data assembly with exclusions and BLQ handling.
+Structural, statistical and covariate models with justification. Estimation method and software
+version. Diagnostics including a pcVPC. Parameter estimates with uncertainty. The model's intended
+use, and its qualification for that use. Deviations from the plan documented rather than absorbed.
+
+**Exposure-response.** The exposure metric and why it is the mechanistically right one. Both
+efficacy and safety relationships. Explicit treatment of confounding between exposure and
+prognosis. The dose or exposure range covered by the data, and what is extrapolation.
+
+**Bioequivalence.** Design and justification; log-transformed analysis; the 90% CI against
+pre-specified limits; the criterion (ABE, ABEL or RSABE) fixed in the protocol; the handling of
+dropouts and pre-dose concentrations; sample-size justification with its assumed GMR and CV.
+
+**PBPK.** Platform and version; every drug parameter with its source and whether it was measured,
+predicted or optimised; the Kp prediction method; verification against observed clinical data before
+the untested application; sensitivity analysis on uncertain inputs; the model files.
+
+**DDI.** The stepwise assessment with the basic-model results and cut-offs; what triggered further
+work; the mechanistic static or PBPK refinement with its verification; the clinical studies with
+index perpetrators and substrates; the labelling conclusion.
+
+## Model-informed drug development
+
+Both FDA and EMA operate programmes for discussing model-based evidence before submission — FDA's
+MIDD Paired Meeting Program and EMA's Qualification of Novel Methodologies. Where a model is
+intended to *replace* a study rather than support one, engaging early is what determines whether the
+model is accepted. The level of rigour expected scales with what the model is being asked to carry.
+
+## The general principle
+
+Regulators evaluate a model against its **intended use**, not in the abstract. A model adequate for
+choosing a Phase II dose is not automatically adequate for waiving a paediatric study or supporting
+a labelling claim. State the intended use first; the required evidence, verification and
+documentation follow from it.

package/skills/pkpd-modeling/references/software-ecosystem.md

@@ -0,0 +1,123 @@
+# The PK/PD software ecosystem
+
+Versions verified 2026-07-27 against PyPI, CRAN, vendor documentation and a live install; see
+`source-ledger.md`. Check again before relying on a version-specific claim.
+
+## The honest summary for Python users
+
+**Python has no mature, regulatory-standing NCA or NLME package.** Pharmacometrics remains an
+R, NONMEM and commercial-tool field. Python's role is orchestration, data preparation, simulation
+and analysis around those tools — which is what Pharmpy does well. This is why this skill ships its
+own validated NCA and compartmental-fitting implementations instead of wrapping a package.
+
+## Nonlinear mixed-effects estimation
+
+| Tool | Licence | Notes |
+| --- | --- | --- |
+| **NONMEM 7.6** | Commercial (ICON) | The regulatory default. Fortran control streams. New in 7.6: **ADVAN16** (RADAR5 implicit Runge-Kutta for stiff delay differential equations), **ADVAN17** (stiff delay differential-algebraic), NUTS Bayesian sampling, SAEM storage of individual parameter samples, and optimal-design evaluation. User guides dated November 2025 |
+| **Monolix** (Lixoft/Simulations Plus) | Commercial | SAEM-based, strong GUI, good diagnostics |
+| **nlmixr2** | Open source (R, CRAN) | The credible open alternative. Requires **rxode2 ≥ 5.0.0**. FOCEi, SAEM, and more. `babelmixr2` and `monolix2rx` translate models to and from NONMEM and Monolix |
+| **Pumas** | Commercial (Julia) | Fast; growing regulatory use |
+| **Phoenix NLME** (Certara) | Commercial | Paired with WinNonlin |
+| **Stan / Torsten** | Open source | Full Bayesian; Torsten adds PK/PD event handling to Stan |
+| **saemix** | Open source (R) | SAEM in R |
+
+## Pharmpy — the Python entry point
+
+`pharmpy-core`, from the Uppsala Pharmacometrics group. Model-agnostic: it reads and writes NONMEM,
+nlmixr2 and rxode2 models and runs tools against whichever estimation engine is installed.
+
+**Current version 2.1.1 (2026-05-19), requires Python ≥ 3.11.** Two recent breaking changes:
+
+- **2.0.0 (2026-02-12): dataset row indices now start at 1, not 0.** Any code indexing into a
+  model's dataset by row breaks silently, off by one.
+- **2.1.0 (2026-05-08): `modeling.add_placebo_model` renamed to `modeling.set_placebo_model`**;
+  numpy ≥ 2 now required; `modeling.get_observations` now includes all DVIDs by default. Also added
+  `convert_unit`, `set_unit`, `get_unit_of`, `add_output_variable`, dataset `Provenance` tracking,
+  an exhaustive stepwise algorithm for `pdsearch`, and pure-PD support in `add_indirect_effect`.
+
+The 19 tools available as `pharmpy.tools.run_*`:
+
+```
+run_allometry   run_amd        run_bootstrap   run_covsearch   run_estmethod
+run_iivsearch   run_iovsearch  run_linearize   run_modelfit    run_modelrank
+run_modelsearch run_pdsearch   run_qa          run_retries     run_ruvsearch
+run_simulation  run_structsearch  run_tool     run_vpc
+```
+
+`run_amd` is the automatic model development pipeline; `run_structsearch` covers PKPD, drug
+metabolite and TMDD structures; `run_pdsearch` takes `type='pd'` or `'kpd'`.
+
+Model transformations worth knowing (all verified present in 2.1.1):
+
+```python
+import pharmpy.modeling as m
+
+m.set_tmdd(model, type="qss")     # 'full' | 'ib' | 'cr' | 'crib' | 'qss' | 'wagner' | 'mmapp'
+m.add_indirect_effect(model, expr="emax", prod=True)   # 'linear' | 'emax' | 'sigmoid'
+m.set_direct_effect(model, expr="sigmoid")
+m.add_effect_compartment(model, expr="emax")
+m.add_allometry(model, allometric_variable="WT", reference_value=70)
+m.set_transit_compartments(model, n=3, keep_depot=True)
+m.set_michaelis_menten_elimination(model)
+m.calculate_eta_shrinkage(model, ...)
+```
+
+## Non-compartmental analysis
+
+| Tool | Licence | Notes |
+| --- | --- | --- |
+| **Phoenix WinNonlin** (Certara) | Commercial | The de facto standard for regulatory NCA |
+| **PKNCA** | Open source (R) | Mature, well tested, widely used |
+| **aNCA** | Open source (R) | Newer; Roche with Appsilon and Human Predictions, in the pharmaverse |
+| **`nca.py` in this skill** | MIT | Validated against analytical profiles; explicit about all four conventions |
+
+**PKPy** (PeerJ, 2025) is a Python framework combining NCA with population modelling, but it is
+**GitHub-only and not published on PyPI** — `uv pip install pkpy` fails. Install from source if you
+want it.
+
+## Simulation and trial design
+
+| Tool | Licence | Notes |
+| --- | --- | --- |
+| **mrgsolve** | Open source (R) | Fast C++ ODE simulation; the standard for large trial simulations |
+| **rxode2** | Open source (R) | Simulation engine underneath nlmixr2 |
+| **Simulx** (Lixoft) | Commercial | Monolix's simulation companion |
+| **`simulate_regimen.py`** | MIT | Analytical linear models plus integrated Michaelis-Menten; PTA out of the box |
+
+## PBPK
+
+| Tool | Licence |
+| --- | --- |
+| **Simcyp** (Certara) | Commercial; the DDI regulatory standard |
+| **GastroPlus** (Simulations Plus) | Commercial; strongest oral absorption modelling |
+| **PK-Sim / MoBi** — Open Systems Pharmacology Suite **v12** | **Open source.** `ospsuite` R package needs R 4.x, .NET 8, Windows or Ubuntu |
+
+## Bioequivalence
+
+| Tool | Licence | Notes |
+| --- | --- | --- |
+| **PowerTOST** | Open source (R) | The reference for BE power and sample size. `bioequivalence.py --power` reproduces its 2×2 tables exactly |
+| **replicateBE** | Open source (R) | ABEL and RSABE evaluation |
+| **`bioequivalence.py`** | MIT | ABE, ABEL, RSABE via Hyslop, and exact TOST power |
+
+## Python packages that are genuinely useful here
+
+| Package | Version checked | Role |
+| --- | --- | --- |
+| `numpy` | 2.5.1 | Everything |
+| `scipy` | 1.18.0 (**requires Python ≥ 3.12**) | Optimisation, ODE integration, distributions |
+| `pharmpy-core` | 2.1.1 | Model manipulation and tool orchestration |
+| `chi-drm` | 1.0.3 | Bayesian PK/PD modelling built on PINTS |
+| `pints` | 0.6.1 | Inference for ODE models |
+| `lmfit` | 1.3.4 | Convenient nonlinear least squares with bounded parameters |
+
+## Choosing
+
+- **Regulatory population PK submission** → NONMEM (or Monolix), orchestrated with Pharmpy, or
+  nlmixr2 if an open toolchain is required.
+- **Regulatory NCA** → Phoenix WinNonlin, or PKNCA with a documented validation.
+- **Exploratory analysis, teaching, prototyping, CI** → the scripts in this skill.
+- **DDI prediction beyond the static models** → Simcyp, or PK-Sim if the budget is zero.
+- **Trial simulation at scale** → mrgsolve.
+- **Bioequivalence planning** → PowerTOST, or `bioequivalence.py --power`.