@pikaa-ai/pikaa 0.3.1 → 0.3.4

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

@@ -1,103 +0,0 @@
-# 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

@@ -1,149 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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`.