@pikaa-ai/pikaa 0.3.1 → 0.3.4

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

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

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

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

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

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