@pikaa-ai/pikaa 0.2.5 → 0.3.1

package/skills/pkpd-modeling/references/antimicrobial-and-tdm.md

@@ -0,0 +1,110 @@
+# Antimicrobial PK/PD and therapeutic drug monitoring
+
+## PK/PD indices
+
+Antimicrobial efficacy correlates with one of three exposure indices, determined by whether killing
+is concentration-dependent or time-dependent. The index is a property of the drug class, and using
+the wrong one leads to the wrong dosing strategy.
+
+| Index | Killing pattern | Classes | Dosing strategy |
+| --- | --- | --- | --- |
+| **fT>MIC** — fraction of the interval with free concentration above MIC | Time-dependent, minimal persistent effect | Beta-lactams (penicillins, cephalosporins, carbapenems) | More frequent dosing, or extended/continuous infusion |
+| **fAUC/MIC** | Time-dependent with persistent effect | Vancomycin, fluoroquinolones, linezolid, azithromycin, tetracyclines | Total daily dose matters; interval matters less |
+| **fCmax/MIC** | Concentration-dependent | Aminoglycosides, daptomycin, colistin, metronidazole | Once-daily, high peak |
+
+Targets commonly cited from preclinical and clinical work — targets, not regulation, and they vary
+by organism and endpoint:
+
+| Drug or class | Target |
+| --- | --- |
+| Penicillins | fT>MIC ≥ 50% (stasis to 1-log kill) |
+| Cephalosporins | fT>MIC ≥ 60-70% |
+| Carbapenems | fT>MIC ≥ 40% |
+| Vancomycin | **AUC₂₄/MIC 400-600** (MIC = 1 mg/L by broth microdilution) |
+| Fluoroquinolones | fAUC/MIC ≥ 100-125 for Gram-negatives; ≥ 30-40 for *S. pneumoniae* |
+| Aminoglycosides | Cmax/MIC ≥ 8-10 |
+| Daptomycin | fAUC/MIC ~ 666 (*S. aureus*) |
+| Linezolid | fAUC/MIC 80-120 |
+
+**The free (unbound) fraction is what matters.** For a highly bound agent such as ceftriaxone or
+daptomycin, total concentrations overstate the active exposure substantially.
+
+## Probability of target attainment and cumulative fraction of response
+
+- **PTA** — for a *fixed* MIC, the fraction of a simulated population reaching the PK/PD target at
+  a given regimen. Plotted against MIC, the PTA curve gives the **PK/PD breakpoint**: the highest
+  MIC at which the regimen achieves (conventionally) ≥ 90% attainment.
+- **CFR** — PTA integrated over the MIC distribution of the actual pathogen population, giving a
+  single expected success probability for empirical therapy against that organism.
+
+Both need a population PK model with realistic variability. `simulate_regimen.py --simulate` with
+`--target-auc` or `--target-trough` gives the machinery; note it includes between-subject
+variability only, so real attainment is lower once residual and between-occasion variability are
+added.
+
+Critically ill patients are the population where this matters most and where standard models fail:
+augmented renal clearance (creatinine clearance above 130 mL/min, common in young trauma and
+sepsis patients) can put a standard beta-lactam regimen well below target, while acute kidney
+injury and renal replacement therapy move it the other way.
+
+## Vancomycin: AUC-guided dosing
+
+The 2020 consensus guideline (ASHP/IDSA/PIDS/SIDP) moved the target from trough-guided to
+**AUC₂₄/MIC of 400-600**, assuming an MIC of 1 mg/L, for serious MRSA infections.
+
+Why troughs were abandoned: trough concentration is a poor surrogate for AUC. Achieving the
+historical 15-20 mg/L trough target frequently produces AUC₂₄ well above 600 and is associated with
+more nephrotoxicity, without better efficacy. Two patients with the same trough can have AUCs
+differing by 50% depending on their volume and interval.
+
+Two accepted methods for estimating AUC:
+
+1. **Bayesian estimation** from one or two levels against a population model. Works with a single
+   level, tolerates levels drawn at imprecise times, and is the preferred approach.
+2. **First-order equations** from a peak and a trough within the same interval, both drawn at
+   steady state, with the peak at least 1-2 hours after the end of the infusion so that
+   distribution is complete.
+
+`tdm_bayes.py --model vancomycin-adult` implements method 1. Its bundled parameterisation is
+explicitly illustrative — substitute a model validated in your population, because vancomycin
+population models differ substantially between general ward, ICU, obese, paediatric and dialysis
+populations.
+
+## Model-informed precision dosing
+
+MAP Bayesian forecasting combines a population prior with a patient's measured concentrations:
+
+```
+minimise   sum_j (obs_j - pred_j)^2 / var_j  +  sum_k (eta_k / omega_k)^2
+```
+
+The second term is the prior penalty. Its consequences:
+
+- **A single level is enough to be useful** but cannot separate clearance from volume. Whichever
+  parameter the sample is uninformative about returns essentially its population value; the
+  reported "individual" estimate for it is the prior.
+- **Sample timing determines what is learned.** Troughs are informative about clearance; a peak
+  (after distribution) is informative about volume. All-trough sampling leaves volume weakly
+  identified.
+- **A large eta is a data-quality signal first.** An individual clearance three-fold the population
+  value is more often a mis-recorded sampling or infusion time than a genuinely unusual patient.
+  Check the times before acting on the estimate.
+- The prior must be **appropriate to the patient**. A model built in general medical inpatients
+  applied to a patient on continuous renal replacement therapy will shrink towards the wrong place,
+  and the fit statistics will not reveal it.
+
+Other drug classes where MIPD is established: aminoglycosides, busulfan (AUC-targeted
+conditioning), methotrexate rescue, immunosuppressants (tacrolimus, ciclosporin, mycophenolate),
+antiepileptics, infliximab and other anti-TNF biologics, and increasingly beta-lactams in
+critical care.
+
+## Reporting a TDM calculation
+
+State the population model and its source, the assay and matrix, the actual (not scheduled) dose
+and sampling times, whether steady state was reached, the estimated individual parameters with the
+etas, the predicted exposure metric, and the target with its justification. Without the actual
+times, the calculation cannot be reproduced or audited.
+
+Any change to a patient's regimen is a clinical decision that depends on the organism, the site of
+infection, renal trajectory, concomitant nephrotoxins and local protocol. The model provides an
+exposure estimate; it does not provide the decision.

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

@@ -0,0 +1,132 @@
+# Bioequivalence
+
+## The ICH M13 series
+
+M13 is the first globally harmonised bioequivalence guidance, replacing a patchwork of regional
+requirements.
+
+| Guideline | Scope | Status |
+| --- | --- | --- |
+| **M13A** | BE for immediate-release solid oral dosage forms: study design and data analysis | Step 4 July 2024; came into effect 25 January 2025 |
+| **M13B** | Additional strengths, including additional-strength biowaivers | Endorsed 13 March 2025; Step 2b, public consultation opened 9 April 2025, comments closed 9 July 2025 |
+| **M13C** | Data analysis for highly variable drugs, narrow therapeutic index drugs, and complex BE study designs | Follows M13B; **this is where reference-scaling will finally be harmonised** |
+
+Until M13C is adopted, reference-scaled approaches remain **regional and mutually incompatible**.
+That is the single most important practical fact about scaled BE: FDA and EMA do not accept each
+other's method, and a study must be designed for the criterion of the agency it is going to.
+
+## Average bioequivalence
+
+The default criterion everywhere:
+
+> The 90% confidence interval for the geometric mean ratio (test/reference) of AUC and Cmax must
+> lie entirely within **80.00% to 125.00%**.
+
+Computed on **log-transformed** data — the interval is symmetric on the log scale and asymmetric
+back-transformed, which is why the limits are 0.80 and 1.25 rather than ±20%.
+
+Narrow therapeutic index drugs are tightened to **90.00-111.11%** in several regions, and the FDA
+additionally requires a comparison of within-subject variability between test and reference.
+
+## Designs
+
+| Design | Periods | Gives you |
+| --- | --- | --- |
+| 2×2 crossover (RT/TR) | 2 | Average BE. Cannot estimate within-subject variability of the reference separately |
+| Parallel | 1 | For long half-life drugs; much larger N; only total variability |
+| Partial replicate (RRT/RTR/TRR) | 3 | CVwR, so reference-scaling becomes possible |
+| Full replicate (RTRT/TRTR or RTR/TRT) | 3-4 | CVwR **and** CVwT; required for the FDA NTI approach |
+| Williams design | ≥3 treatments | Balanced for first-order carryover |
+
+A crossover removes between-subject variability, which is why it needs far fewer subjects than a
+parallel design. It requires an adequate washout — at least 5 terminal half-lives — and pre-dose
+concentrations in later periods should be below 5% of Cmax, or the subject is excluded.
+
+## Reference-scaled approaches for highly variable drugs
+
+A highly variable drug is one with CVwR > 30%. Both approaches require a **replicate design**;
+neither can be applied to a 2×2 study however high the observed variability, because without
+repeated reference administrations there is no CVwR to scale to.
+
+### EMA: average bioequivalence with expanding limits (ABEL)
+
+```
+limits = exp(± 0.760 * swR)      capped at CVwR = 50%  ->  69.84% - 143.19%
+```
+
+Conditions: replicate design; the widening must be pre-specified in the protocol with clinical
+justification; the point estimate must still fall within 80.00-125.00%; and widening is applied to
+Cmax (and for some products AUC, though EMA generally does not permit AUC widening).
+
+### FDA: reference-scaled average bioequivalence (RSABE)
+
+Not an interval criterion at all. The criterion is
+
+```
+(mu_T - mu_R)^2 - theta^2 * s2wR  <=  0        with theta = ln(1.25)/0.25 = 0.8926
+```
+
+evaluated as a **95% upper confidence bound** using Hyslop's linearised method:
+
+```
+E  = (Ybar_T - Ybar_R)^2                    Eh = (|Ybar_T - Ybar_R| + t(0.95,df)*SE)^2
+H  = -theta^2 * s2wR                        Hh = -theta^2 * s2wR * df / chi2(0.05, df)
+upper bound = E + H + sqrt((Eh-E)^2 + (Hh-H)^2)
+```
+
+Pass requires the upper bound ≤ 0 **and** the point estimate within 80-125%. Applied when
+CVwR ≥ 30%; below that, unscaled ABE applies. `bioequivalence.py --scaling rsabe` implements this.
+
+The two criteria can disagree on the same dataset. Which applies is a regulatory fact, not a
+statistical choice, and must be pre-specified.
+
+## Sample size
+
+Driven by three things, in order of influence: the assumed true GMR, the within-subject CV, and the
+target power.
+
+Published values for a 2×2 crossover, GMR 0.95, 80% power, 80-125% limits — reproduced exactly by
+`bioequivalence.py --power`:
+
+| CVw | N |
+| --- | --- |
+| 15% | 12 |
+| 20% | 20 |
+| 25% | 28 |
+| 30% | 40 |
+| 35% | 52 |
+| 40% | 66 |
+
+**Assuming a GMR of 1.00 rather than 0.95 roughly halves the calculated N**, and is the most common
+reason a bioequivalence study comes in underpowered. A GMR of exactly 1.00 is not a realistic
+planning assumption for two different formulations.
+
+Power must be computed by integrating over the sampling distribution of the estimated standard
+deviation (equivalently, Owen's Q). Treating the standard error as known overstates power at these
+sample sizes.
+
+## Common errors
+
+1. **Using a t test.** "p > 0.05, therefore the formulations are equivalent" inverts the hypothesis.
+   Failing to detect a difference is not evidence of equivalence, and on a small BE dataset that
+   outcome is nearly guaranteed. The 90% CI (equivalently, two one-sided tests at α = 0.05) is the
+   test.
+2. **Analysing untransformed data.** AUC and Cmax are log-normal; the criterion is defined on the
+   log scale.
+3. **Scaling from a 2×2 design.** Refused by `bioequivalence.py`, and by regulators.
+4. **Post hoc scaling.** Deciding to widen limits after seeing high variability is not
+   pre-specification.
+5. **Dropping subjects after unblinding** for reasons not defined in the protocol.
+6. **Reporting only AUC.** Cmax must meet the criterion too, and it is the more variable of the two.
+7. **Ignoring the period effect** by analysing as a paired comparison. `bioequivalence.py` labels
+   this explicitly when the sequence column is missing.
+
+## Endogenous compounds and other special cases
+
+- **Endogenous substances** (potassium, iron, hormones) require baseline correction, and the
+  baseline-correction method changes the answer. Pre-specify it.
+- **Long half-life drugs**: AUC(0-72h) is accepted in place of AUC(0-inf) under M13A for immediate
+  release products, avoiding a very long sampling schedule.
+- **Highly variable Cmax with acceptable AUC** is the usual pattern that pushes a programme towards
+  a replicate design.
+- **Fed versus fasted**: both usually required; the food effect study is separate from BE.

package/skills/pkpd-modeling/references/dataset-standards.md

@@ -0,0 +1,103 @@
+# PK dataset standards: CDISC, NONMEM data items, and the defects that survive review
+
+## The two worlds
+
+Regulatory submission data is CDISC. Modelling data is NONMEM-format. They are different shapes and
+converting between them is where most defects are introduced.
+
+| Layer | Domain / dataset | Contents |
+| --- | --- | --- |
+| SDTM | **PC** | Pharmacokinetic concentrations, as collected |
+| SDTM | **PP** | Pharmacokinetic parameters (NCA output) |
+| SDTM | **EX** | Exposure — what was actually administered |
+| ADaM | **ADPC** | Analysis-ready concentrations |
+| ADaM | **ADPP** | Analysis-ready parameters |
+| — | NONMEM dataset | One row per event, wide covariates, numeric only |
+
+Useful SDTM PC variables: `PCTESTCD`/`PCTEST` (analyte), `PCORRES`/`PCSTRESN` (result as collected
+and standardised), `PCSTRESU`, `PCLLOQ`, `PCTPT`/`PCTPTNUM` (nominal time), `PCDTC` (actual
+date/time), `PCSPEC` (matrix). PP parameters use the CDISC `PKPARM`/`PKUNIT` controlled
+terminology — `AUCALL`, `AUCIFO`, `AUCIFP`, `CMAX`, `TMAX`, `LAMZ`, `LAMZHL`, `CLFO`, `VZFO`.
+
+**Nominal versus actual time is the single most consequential conversion decision.** NCA and
+population modelling should use **actual** elapsed time from the most recent dose. Using nominal
+time flattens the absorption phase, biases Cmax and Tmax, and inflates residual error. Nominal time
+is for grouping and presentation only.
+
+## NONMEM data items
+
+| Item | Meaning | Traps |
+| --- | --- | --- |
+| `ID` | Subject | Must be numeric and contiguous per subject; records for one subject must be together |
+| `TIME` | Elapsed time | Must be non-decreasing within a subject. Use one unit consistently |
+| `DV` | Dependent variable | **Must be numeric.** See below |
+| `AMT` | Dose amount | On a dose record only; units must match the model's |
+| `EVID` | Event ID | 0 observation, 1 dose, 2 other, 3 reset, 4 reset+dose |
+| `MDV` | Missing DV | 1 means the record contributes nothing to the objective function |
+| `CMT` | Compartment | Which compartment is dosed or observed |
+| `RATE` | Infusion rate | `>0` a rate; `-1` model-estimated duration; `-2` model-estimated rate |
+| `SS` | Steady state | 1 = achieve steady state before this dose; **requires `II`** |
+| `II` | Interdose interval | Required by both `SS` and `ADDL` |
+| `ADDL` | Additional doses | `n` further doses every `II`; **silently does nothing without `II`** |
+
+## The defects that do not stop a run
+
+These are the reason `check_popk_dataset.py` exists. None of them raises an error in NM-TRAN.
+
+1. **Non-numeric `DV`.** `BLQ`, `<LLOQ`, `ND` are read as **0** and fitted as genuine zero
+   concentrations. This is the most damaging defect in the list, and it is invisible.
+2. **Missing covariate read as 0.** A blank or `.` in a `WT` column becomes a 0 kg patient in the
+   covariate model. Missing covariates must be imputed explicitly and the imputation documented, or
+   the subject excluded.
+3. **`ADDL` without `II`.** No additional doses are placed. Exposure is understated by the whole
+   accumulation.
+4. **`SS` without `II`.** Same class of failure.
+5. **Duplicate timestamps.** A dose and an observation at the same `TIME` are applied in file
+   order, so whether the sample is pre- or post-dose depends on row order. Order dose records
+   before observations at the same time, or offset the observation by a small negative amount.
+6. **Unsorted `TIME` within a subject.** NONMEM does not sort for you.
+7. **A subject with doses but no observations.** They contribute no information but appear in the
+   N of the analysis and their etas come entirely from the prior.
+8. **A subject with observations but no dose.** Their predictions are zero and their residuals are
+   the whole observation.
+9. **Time-varying covariate declared as baseline.** The model uses whichever value is on the record
+   being evaluated, which is rarely what was intended.
+10. **Units.** Dose in mg with concentrations in ng/mL gives a volume off by 10⁶. Nothing checks
+    this; the fit will converge on a nonsense volume.
+11. **`RATE` left on an oral record**, turning first-order absorption into a zero-order infusion.
+12. **Mixed time origins** — some subjects timed from first dose, others from screening.
+
+## Handling BLQ properly
+
+Keep the numeric `DV` and add a separate flag:
+
+```
+ID,TIME,DV,AMT,EVID,MDV,BLQ,LLOQ
+1,0,.,100,1,1,0,0.5
+1,1,4.21,.,0,0,0,0.5
+1,24,0.5,.,0,0,1,0.5     <- DV set to LLOQ, BLQ flag set, method chosen in the control stream
+```
+
+Then implement the chosen method (usually M3) in the model rather than by editing the data. See
+`population-pk.md` for the M1-M7 comparison.
+
+## Structuring covariates
+
+- **Baseline covariates** appear once per subject and are repeated on every record.
+- **Time-varying covariates** change between records and must be declared as such. Last-observation
+  carried forward is the usual interpolation, and it is an assumption worth stating.
+- Categorical covariates need a numeric coding and a documented reference level. Never leave a
+  category blank to mean "reference".
+- Derived covariates (creatinine clearance, BSA, lean body weight) should be computed once,
+  documented with the formula used, and stored — not recomputed in the control stream where the
+  formula is invisible to a reviewer.
+
+## Dataset specification
+
+Every population analysis dataset should ship with a specification listing, per column: name,
+label, type, units, derivation (including the source SDTM/ADaM variable), permissible values, and
+the missing-data rule. This is the document a reviewer reads first, and producing it usually
+surfaces at least one defect on its own.
+
+A reproducible derivation script from the ADaM datasets to the modelling dataset is worth more than
+the dataset itself: it is what makes a re-run possible after a database lock update.

package/skills/pkpd-modeling/references/ddi-and-qt.md

@@ -0,0 +1,132 @@
+# Drug interactions (ICH M12) and QT assessment (ICH E14/S7B)
+
+## ICH M12 status
+
+The first globally harmonised guidance on pharmacokinetic drug interactions mediated by metabolic
+enzymes and transporters. Step 4 in 2024, then:
+
+| Region | Adoption |
+| --- | --- |
+| FDA | Adopted 2 August 2024, with an accompanying *M12 Drug Interaction Studies: Questions & Answers* |
+| EMA / EU | Effective 30 November 2024 |
+| NMPA (China) | Implemented 29 October 2024 |
+
+It replaces the previous FDA in vitro and clinical DDI guidances and EMA's DDI guideline as the
+operative framework.
+
+## The stepwise, risk-based approach
+
+1. **In vitro characterisation** — is the drug a substrate, inhibitor or inducer of the major
+   enzymes and transporters?
+2. **Basic models** with conservative cut-offs — do the in vitro data rule the interaction out?
+3. **Mechanistic static or PBPK modelling** — refine a positive basic-model signal.
+4. **Clinical study** — where modelling cannot rule it out or the interaction is decision-relevant.
+5. **Labelling** — dose adjustment, contraindication, or monitoring.
+
+The basic models are deliberately conservative: they are built to over-predict, so a **negative
+result is meaningful** and a positive one is a trigger for further work, never an estimate of
+clinical magnitude.
+
+## Basic model cut-offs
+
+| Mechanism | Model | Cut-off |
+| --- | --- | --- |
+| Reversible inhibition, hepatic | `R1 = 1 + Imax,u / Ki` | R1 ≥ 1.02 |
+| Reversible inhibition, intestinal (CYP3A4) | `R1,gut = 1 + Igut / Ki`, `Igut = dose / 250 mL` | R1,gut ≥ 11 |
+| Time-dependent inhibition | `R2 = (kobs + kdeg) / kdeg`, `kobs = kinact·I / (KI + I)` at 50 × Imax,u | R2 ≥ 1.25 |
+| Induction (basic) | `R3 = 1 / (1 + d·Emax·I / (EC50 + I))` at 10 × Imax,u | R3 ≤ 0.80 |
+| Hepatic uptake transporters (OATP1B1/1B3) | `1 + fu·Iin,max / Ki,u` | ≥ 1.1 |
+| Intestinal transporters (P-gp, BCRP) | `Igut / IC50` | ≥ 10 |
+| Renal transporters (OAT, OCT, MATE) | `Imax,u / Ki` | ≥ 0.1 |
+
+The hepatic inlet concentration for uptake transporters is
+
+```
+Iu,inlet,max = fu * (Imax + Fa*Fg*ka*Dose / (Qh * RB))
+```
+
+which is higher than systemic Imax and is what the liver actually sees during absorption.
+
+An alternative induction assessment is the **correlation / relative induction score** approach,
+calibrated against known inducers, which is less conservative than the basic R3 model.
+
+## Mechanistic static model
+
+```
+AUCR = 1 / (Ag·Bg·Cg·(1 - Fg) + Fg)  ×  1 / (Ah·Bh·Ch·fm + (1 - fm))
+```
+
+with, at each site,
+
+```
+A = 1 / (1 + I/Ki)                                    reversible inhibition
+B = kdeg / (kdeg + kinact·I/(KI + I))                 time-dependent inhibition
+C = 1 + d·Emax·I/(EC50 + I)                           induction
+```
+
+**`fm` and `Fg` dominate the result.** The ceiling on any inhibition of a single pathway is
+`1/(1 - fm)`: with `fm = 0.9` no inhibitor can raise AUC more than 10-fold, and with `fm = 0.7`, no
+more than 3.3-fold. These two fractions are usually the least well established inputs, and a
+sensitivity analysis across their plausible range is more informative than the point prediction.
+`ddi_static.py --msm` prints the ceiling alongside the prediction.
+
+## Perpetrator classification
+
+| Class | AUC ratio |
+| --- | --- |
+| Strong inhibitor | ≥ 5 |
+| Moderate inhibitor | ≥ 2 and < 5 |
+| Weak inhibitor | ≥ 1.25 and < 2 |
+| No relevant effect | > 0.8 and < 1.25 |
+| Weak inducer | > 0.5 and ≤ 0.8 |
+| Moderate inducer | > 0.2 and ≤ 0.5 |
+| Strong inducer | ≤ 0.2 |
+
+## Clinical study design points
+
+- Use **index perpetrators** (itraconazole or clarithromycin for strong CYP3A4 inhibition,
+  rifampicin for strong induction, and the corresponding index substrates) so the result is
+  interpretable against the classification bands.
+- Worst-case first: a study with a strong index perpetrator that shows no interaction removes the
+  need for weaker ones.
+- Induction requires **multiple-dose** administration of the perpetrator; a single dose can even
+  show inhibition from the same compound.
+- Timing matters for time-dependent inhibition and for induction, both of which take days to
+  develop and days to reverse.
+- A **cocktail study** can assess several pathways at once, provided the probes are validated as
+  non-interacting.
+
+---
+
+# QT assessment: ICH E14 and S7B
+
+## The framework
+
+- The threshold of regulatory concern is a **QTc effect above 10 ms**, assessed as the **upper bound
+  of the two-sided 90% confidence interval** for placebo-corrected change-from-baseline QTc (ΔΔQTc)
+  at the clinically relevant high exposure.
+- A prospective **concentration-QTc analysis** on Phase I data can substitute for a dedicated
+  thorough QT study, and this is now the routine path.
+- The **2022 E14/S7B Q&As** introduced the "double negative" integrated nonclinical risk
+  assessment — a negative hERG assay plus a negative in vivo QTc study — as supplementary evidence.
+  This allows a submission to cover high clinical exposure without attaining a high multiple of
+  clinically relevant exposure, and its uptake in FDA reviews rose sharply after 2022.
+
+## Getting a C-QTc analysis right
+
+- **Correction method**: QTcF (Fridericia) is the standard. QTcB (Bazett) over-corrects at high
+  heart rates and should not be primary. Where heart rate changes materially with treatment, a
+  study-specific or individual correction is preferable.
+- **Model**: linear mixed effects on time-matched ΔQTc against plasma concentration, with a random
+  intercept and slope per subject and a treatment-specific intercept. Assess the intercept — a
+  non-zero one suggests the baseline or the placebo correction is wrong.
+- **Linearity**: the extrapolation to supratherapeutic exposure depends on it. Check for curvature,
+  and check that the highest observed concentrations actually cover the exposure of interest.
+- **Hysteresis**: if the QTc effect lags concentration, a direct model is misspecified and an effect
+  compartment is needed. Plot ΔQTc against concentration coloured by time to see it.
+- Sample size is driven by the number of subjects **and** the spread of concentrations achieved;
+  a study where everyone has similar exposure estimates the slope poorly regardless of N.
+
+`exposure_response.py --cqtc` implements the ordinary linear version for screening and flags
+extrapolation beyond the observed concentration range. It is not a substitute for the mixed model
+in a submission.

package/skills/pkpd-modeling/references/nca-conventions.md

@@ -0,0 +1,128 @@
+# Non-compartmental analysis: conventions that change the answer
+
+NCA is arithmetic on a concentration-time curve. What makes two analyses of the same data disagree
+is never the arithmetic — it is the four conventions below, which are frequently left unstated.
+
+## 1. Which trapezoidal rule
+
+| Rule | Segment AUC | When |
+| --- | --- | --- |
+| Linear | `(C1+C2)/2 * dt` | Rising phase; sparse data; regulatory default for some agencies on ascending segments |
+| Linear-up / log-down | linear while rising, log while falling | The usual default for a drug with log-linear decline |
+| Log-linear | `(C1-C2)/k`, `k = ln(C1/C2)/dt` | Whole curve; fails on any rising or flat segment |
+
+Linear trapezoid **overestimates** AUC on a convex declining curve, because the chord lies above
+the exponential. The error grows with the sampling interval, so a sparse late-phase schedule biases
+AUC upward under the linear rule and the two rules can differ by several percent.
+
+Under log-down, the AUMC segment is
+
+```
+AUMC = (t1*C1 - t2*C2)/k + (C1 - C2)/k^2      with k = ln(C1/C2)/(t2 - t1)
+```
+
+which is not what you get by applying the AUC substitution naively.
+
+## 2. How lambda_z was selected
+
+The dominant convention: fit `ln C` on time over the last three quantifiable points, extend the
+window backwards one point at a time, and keep the longer window only when **adjusted** r-squared
+improves by more than 0.0001.
+
+- Plain r-squared is monotone in the number of points, so it always selects the longest window.
+  Adjusted r-squared is the only version of this rule that discriminates.
+- Points at or before Tmax are never eligible. Including Tmax fits the tail of absorption, which
+  biases lambda_z upward and therefore half-life, Vz and AUCinf downward.
+- Trailing BLQ samples are excluded from the regression, not set to zero — a zero cannot be
+  log-transformed and a half-LLOQ substitution in the tail flattens the slope.
+
+Reportability criteria, all conventions rather than regulation, and all worth pre-specifying:
+
+| Diagnostic | Usual threshold | What it means when it fails |
+| --- | --- | --- |
+| Points in the window | ≥ 3 | The slope is an interpolation between two points |
+| Adjusted r-squared | ≥ 0.80 (sometimes 0.85) | The terminal phase is not log-linear, or is noise |
+| Span ratio: window duration / t½ | ≥ 2 | The true terminal phase may not have been reached |
+| % AUC extrapolated | ≤ 20% | AUCinf is driven by the fit, not by data |
+
+A profile can pass all four and still be wrong if sampling stopped during a distribution phase: the
+"terminal" slope is then the beta phase of a drug whose gamma phase was never observed, and Vz and
+t½ are both underestimated. Only the sampling duration relative to the true terminal half-life
+fixes this, and NCA cannot detect it.
+
+## 3. What happened to BLQ values
+
+| Rule | Effect |
+| --- | --- |
+| Set to zero | Standard for leading BLQ before the first quantifiable sample |
+| LLOQ/2 | Common for embedded BLQ; biases AUC upward slightly and t½ downward |
+| Treated as missing | Standard for trailing BLQ; avoids fabricating a tail |
+
+The usual regulatory-acceptable combination is: leading BLQ = 0, embedded BLQ = 0 or LLOQ/2 with
+the choice stated, trailing BLQ excluded. Whatever you choose, apply it identically to every
+profile and to every treatment arm — a rule applied to the test formulation and not the reference
+biases the ratio directly.
+
+## 4. Observed or predicted Clast
+
+```
+AUCinf_obs  = AUClast + Clast_observed  / lambda_z
+AUCinf_pred = AUClast + Clast_predicted / lambda_z     (Clast_predicted from the lambda_z fit)
+```
+
+They differ whenever the last observation sits off the fitted line, which is exactly when the last
+observation is noisy. `_pred` is more stable; `_obs` is more common. Report which.
+
+## Parameter definitions
+
+| Parameter | Definition | Notes |
+| --- | --- | --- |
+| Cmax, Tmax | Highest observed concentration and its time | **Observed values, never interpolated.** Tmax is summarised as median and range, not mean and SD |
+| AUClast | AUC to the last quantifiable concentration | The only exposure metric that involves no extrapolation |
+| AUCinf | AUClast + Clast/lambda_z | |
+| AUMCinf | AUMClast + tlast·Clast/λz + Clast/λz² | |
+| MRT | AUMCinf/AUCinf | Subtract Tinf/2 for a zero-order infusion |
+| CL or CL/F | Dose/AUCinf | Apparent (`/F`) for any extravascular route |
+| Vz or Vz/F | Dose/(λz · AUCinf) | Terminal-phase volume; depends on λz and inherits its error |
+| Vss | CL · MRT | **Intravenous only.** Vss from extravascular data is not defined, because MRT then includes mean absorption time |
+| AUC(0-tau) | AUC over one dosing interval at steady state | The reportable exposure metric at steady state |
+| Cavg | AUC(0-tau)/tau | |
+| PTF% | 100·(Cmax − Cmin)/Cavg | Peak-trough fluctuation |
+| Swing | (Cmax − Cmin)/Cmin | More sensitive than PTF to a low trough |
+| Rac | AUC(0-tau),ss / AUC(0-tau),first dose | Observed accumulation; compare with 1/(1 − e^(−λz·tau)) |
+
+**Vz versus Vss.** Vz is a terminal-phase parameter and is systematically larger than Vss for a
+multi-compartment drug. They are not alternative estimates of the same thing, and a covariate model
+built on one does not transfer to the other.
+
+## Steady state
+
+Do not compute AUCinf from a truncated steady-state profile. The `nca.py` extrapolation finding
+fires on exactly this, because the tail beyond tau is not observed and the extrapolated area is a
+fiction. Report AUC(0-tau).
+
+Attainment of steady state should be demonstrated, not assumed — by trough concentrations across at
+least three consecutive intervals showing no trend, not by counting half-lives, because the half
+life you would count with is the one you are trying to estimate.
+
+## Urinary data
+
+- `Ae` — cumulative amount excreted unchanged; `fe = Ae(0-inf)/Dose`
+- `CLr = Ae(0-t)/AUC(0-t)` over the **same** interval; mismatching the intervals is the standard error
+- `CLnr = CL − CLr`
+
+Incomplete collection biases `fe` and `CLr` downward and is not detectable from the data alone.
+
+## Sparse sampling
+
+With one or two samples per subject, per-subject NCA is not possible. The Bailer method and its
+Nedelman-Jia extension estimate a mean AUC and its standard error across a batch design. Do not
+average per-subject AUCs computed from single points; do not run the destructive-sampling data
+through an individual NCA and summarise the result.
+
+## Reporting
+
+State, for every NCA: the trapezoidal rule; the BLQ rule at each position; the lambda_z selection
+rule with the window and number of points per subject; whether AUCinf is observed- or
+predicted-based; and the exclusion criteria applied, decided before unblinding. Summarise exposure
+metrics as geometric mean with geometric CV%, and Tmax as median with range.