@pikaa-ai/pikaa 0.3.0 → 0.3.4

package/skills/analytical-method-validation/references/source-ledger.md

@@ -1,125 +0,0 @@
-# Official Source Ledger
-
-**Research date: 2026-07-27.** Every framework claim in this skill traces to an entry below.
-Re-check each source before operational use — guidelines are revised, editions change, and regional
-implementation dates differ from adoption dates.
-
-This ledger is a version baseline. It is not legal advice, an applicability determination, or a
-substitute for a controlled copy held under the laboratory's document control.
-
-## Documents read directly
-
-These were downloaded and read as full text on the research date, so the requirements encoded in
-`scripts/_catalog.py` and summarised in `references/ich-q2r2.md` and
-`references/ich-m10-bioanalytical.md` come from the primary source rather than from secondary
-summaries.
-
-### ICH Q2(R2) Validation of Analytical Procedures
-
-- Source read: <https://database.ich.org/sites/default/files/ICH_Q2%28R2%29_Guideline_2023_1130.pdf>
-- Verified metadata: Final Version, adopted by the ICH Assembly Regulatory Members under Step 4 on
-  **1 November 2023**. Step 2 endorsement 24 March 2022. Supersedes Q2(R1) (November 2005).
-- Verified detail: an **error correction dated 30 November 2023** covers Table 5 (dissolution with
-  HPLC, reportable range linearity formulae, page 25) and Tables 6–11 (pages 26–32).
-- Content taken: section structure; Table 1 (tests by measured attribute); Table 2 (reportable range
-  examples); recommended data for specificity, response, lower range limits, accuracy, precision,
-  and robustness; sections 2.1–2.5; Annex 1 and Annex 2 table inventory; the relative response factor
-  0.8–1.2 rule from Annex 2 Table 3.
-- Licence: ICH permits use, reproduction, adaptation and distribution under a public licence provided
-  ICH's copyright is acknowledged. Acknowledged here and in `scripts/_catalog.py`.
-- Limitation: **adoption is not implementation.** Confirm the date from which your regional regulator
-  expects Q2(R2) with that regulator.
-
-### ICH M10 Bioanalytical Method Validation and Study Sample Analysis
-
-- Source read: <https://database.ich.org/sites/default/files/M10_Guideline_Step4_2022_0524.pdf>
-- Verified metadata: Step 4, dated **24 May 2022**.
-- Content taken: chromatographic criteria (section 3) — calibration levels and tolerances, QC
-  placement at four levels with the low/medium/high definitions, within-run and between-run accuracy
-  and precision design and criteria, routine-run QC pass rules, carry-over, selectivity source count,
-  dilution integrity, stability; ligand binding assay criteria (section 4) — calibration tolerances
-  including anchor point exclusion, five QC levels, run and replicate structure, accuracy and
-  precision criteria at LLOQ and ULOQ, and the total error criterion; incurred sample reanalysis
-  (section 5) including the percent-difference basis and the pass fractions.
-- Verified distinction: the **total error criterion (≤30%, ≤40% at LLOQ and ULOQ) appears for ligand
-  binding assays**. No equivalent criterion was found for chromatographic assays.
-- Licence: as for Q2(R2).
-- Limitation: regional implementation dates differ. Confirm with the regional regulator.
-
-### ICH Q14 Analytical Procedure Development
-
-- Source read: <https://database.ich.org/sites/default/files/ICH_Q14_Guideline_2023_1116.pdf>
-- Content taken: section structure; the minimal versus enhanced approaches (section 2.1); the
-  analytical target profile (section 3) and that its formal documentation and submission is
-  **optional**; robustness and parameter ranges (section 5); established conditions (section 6.1);
-  lifecycle management and post-approval change (section 7); multivariate procedures (section 8).
-- Adopted alongside Q2(R2) by the ICH Assembly in the same session.
-- Licence: as for Q2(R2).
-
-## Documents identified but not read (paywalled)
-
-Designation, title, and scope only. **No requirement, threshold, or study design from any of these is
-reproduced anywhere in this skill.** Where a numeric criterion is needed, read it from an authorised
-copy.
-
-### USP–NF general chapters
-
-- Official pages: `<1220>` <https://doi.usp.org/USPNF/USPNF_M10975_02_01.html>;
-  `<1225>` <https://doi.usp.org/USPNF/USPNF_M99945_40101_01.html>;
-  `<1226>` <https://doi.usp.org/USPNF/USPNF_M870_03_01.html>
-- Verified metadata for `<1220>`: incorporated into USP–NF 2022 Issue 1 on **1 November 2021**,
-  **official 1 May 2022**. It brings the concepts of `<1224>`, `<1225>` and `<1226>` into a single
-  three-stage lifecycle. `<1225>` covers validation, particularly Stage 2 activities under `<1220>`;
-  `<1226>` covers verification of compendial procedures.
-- Provenance limitation: this metadata came from **secondary sources** (publisher notices and trade
-  press) rather than from the USP–NF text, which is behind subscription. Marked
-  **[confirm in USP–NF]**. Confirm the current official text, revision, and any subsequent change.
-- Chapters referenced by designation only, not read: `<1224>`, `<1010>`, `<621>`, `<711>`, `<1092>`.
-
-### CLSI EP series
-
-- Publisher: <https://clsi.org/standards/products/method-evaluation/>
-- Designations and subjects recorded in `references/compendial-and-clsi.md`: EP05, EP06, EP07, EP09,
-  EP15, EP17, EP25, EP28 (formerly C28), plus the EP17IG and EP28IG implementation guides.
-- Provenance limitation: designations, titles and edition numbers were taken from **clsi.org product
-  listings and secondary sources** on the research date, not read from the documents. Every edition
-  number carries **[confirm edition]** in the reference file. Editions change; verify on clsi.org
-  before designing a study.
-
-### ISO standards
-
-- ISO/IEC 17025:2017 — <https://www.iso.org/standard/66912.html>. Edition 3; supersedes the 2005
-  edition. Relevant clauses: 7.2 (selection, verification and validation of methods), 7.6
-  (measurement uncertainty). Not read; identified by catalogue metadata.
-- ISO 15189, ISO 21748, ISO 5725 series — referenced by designation and scope only.
-- Provenance limitation: ISO catalogue pages have historically refused automated access. Confirm
-  edition and status on iso.org or with a national member body. **[confirm on iso.org]**
-- See this repository's `iso-standards-readiness` skill and its own source ledger for the
-  accreditation-level treatment of these standards.
-
-## Statistical methods
-
-The statistical procedures in `references/statistics.md` and `scripts/_common.py` are standard
-published methods, not requirements of any framework:
-
-- Incomplete beta and gamma function implementations follow the standard continued-fraction and series
-  algorithms; the t, chi-square and F distributions are derived from them.
-- Lack-of-fit F test against pure error: standard regression ANOVA.
-- Wald–Wolfowitz runs test: standard non-parametric test of randomness in a sequence of signs.
-- One-way random-effects variance components with the standard unbalanced expected-mean-square
-  coefficient; Satterthwaite approximation for effective degrees of freedom of the total.
-- Deming regression with jackknife standard errors; Passing–Bablok with the rank-based slope interval.
-- Bland–Altman bias and limits of agreement.
-- Two one-sided tests (TOST) for equivalence.
-
-Implementations are verified against published quantiles and hand-checkable cases in
-`tests/analytical-method-validation/test_scripts.py`. Where a framework prescribes a specific
-statistical treatment, the framework governs — these are the general-purpose tools.
-
-## What is deliberately absent
-
-- No numeric acceptance criteria are supplied for ICH Q2(R2) work. The guideline does not set them and
-  neither does this skill; they come from the specification, the analytical target profile, or
-  development data.
-- No text, table, threshold, or study design from any USP, CLSI, or ISO document.
-- No claim that a procedure is validated, a run acceptable, or an investigation closed.

package/skills/analytical-method-validation/references/statistics.md

@@ -1,209 +0,0 @@
-# The Statistics, and Why Each One
-
-Every method in this file is implemented in `scripts/_common.py` using only the standard library.
-Distribution functions are computed from the regularised incomplete beta and gamma functions, and the
-implementations are checked against published quantiles in `tests/analytical-method-validation/`.
-
-## Calibration response
-
-### r² is not evidence of linearity
-
-The coefficient of determination measures how much of the variance in response the model explains. It
-rises with the width of the calibration range and is nearly insensitive to curvature. A quadratic
-response measured over a decade of concentration routinely gives r² > 0.99 while the back-calculated
-result at the bottom of the range is 10% wrong.
-
-ICH Q2(R2) 3.2.2.1 asks for r or r², the slope, the intercept, the plot, **and an analysis of the
-deviation of the actual data points from the regression line**. The last item is the one that
-detects a bad model. Report r² because the guideline asks for it, not because it demonstrates
-anything.
-
-### Lack-of-fit F test
-
-The correct test of a linear calibration model, and it requires replicates at some levels.
-
-Partition the residual sum of squares into **pure error** (scatter among replicates at the same
-level, which no model can explain) and **lack of fit** (systematic deviation of level means from the
-line):
-
-```
-F = MS_lack-of-fit / MS_pure-error,   df = (k - 2, n - k)
-```
-
-for `k` distinct levels and `n` total points. A significant F says the straight line fails to
-describe the data beyond what replicate scatter explains. Without replicates the partition is
-impossible and no linearity test exists — which is a good reason to replicate at least one level, and
-a reason `check_response.py` says so explicitly when it cannot run the test.
-
-### Residual pattern: runs test
-
-Curvature makes residual signs cluster: all negative at the ends and positive in the middle, or the
-reverse. The Wald–Wolfowitz runs test counts sign changes and compares against the number expected
-if signs were random. Too few runs is evidence of systematic misfit. It complements the F test and
-works when replicates are absent, though it needs at least eight points with both signs present.
-
-### Heteroscedasticity and weighting
-
-Chromatographic response variance usually scales with concentration. Unweighted least squares
-minimises absolute squared residuals, so the high-concentration points — which have the largest
-absolute residuals — dominate the fit. The result is a curve that is accurate at the top of the range
-and biased at the bottom, which is exactly where an impurity reporting threshold or an LLOQ sits.
-
-`check_response.py` compares residual variance in the top and bottom thirds of the range. A ratio
-above roughly 10× with an unweighted fit is flagged; `1/x` or `1/x²` weighting is the usual remedy.
-State the weighting in the protocol before validation — switching to weighting after seeing the data
-to make the low end pass is not a statistical decision.
-
-### Back-calculated relative error
-
-The practical criterion: invert the fitted line, compute the concentration each response implies,
-and compare against nominal at each level. This is what the procedure will actually report, and it
-exposes a bad model in units an analyst and an assessor both understand. Bioanalytical work has
-required it for decades; it belongs in small-molecule QC validation too.
-
-## Precision
-
-### Estimate within each level, never pooled across levels
-
-Pooling results from 80%, 100% and 120% levels into one standard deviation makes the range itself
-appear as imprecision. The number produced is meaningless and always too large.
-`check_accuracy_precision.py` estimates precision within each level, and separately provides a
-level-independent view by converting to percent of nominal first.
-
-### Repeatability and intermediate precision are different quantities
-
-A one-way random-effects model on the intermediate-precision factor — day, analyst, or instrument:
-
-```
-observation = grand mean + group effect + residual
-```
-
-with `MS_within` and `MS_between` from the ANOVA table:
-
-```
-s²_repeatability = MS_within
-s²_between       = max(0, (MS_between - MS_within) / n_effective)
-s²_intermediate  = s²_repeatability + s²_between
-```
-
-For a balanced design `n_effective` is the replicates per group; unbalanced designs use the standard
-expected-mean-square coefficient, which the script reports when it applies.
-
-The between-group variance is truncated at zero because a negative variance estimate is not
-meaningful — it means the data cannot distinguish the groups. The script says so when it happens
-rather than silently reporting zero.
-
-Why this matters: a procedure can show 0.07% RSD within a day and 1.65% RSD across days. The
-within-day figure is real, and reporting it as the procedure's precision understates routine
-performance by more than twenty-fold. Q2(R2) 3.3.2.2 exists precisely because the between-day
-component is the one that bites in routine use.
-
-### Confidence intervals on a standard deviation
-
-A precision estimate from six or nine determinations is imprecise, and Q2(R2) 3.3.2.4 asks for an
-interval alongside it. For a variance with `ν` degrees of freedom:
-
-```
-s · sqrt(ν / χ²_{1-α/2, ν})  <  σ  <  s · sqrt(ν / χ²_{α/2, ν})
-```
-
-These intervals are wide, and that is the point. With ν = 5 the upper bound is roughly twice the
-point estimate. An RSD that lands just inside a limit on six replicates has not demonstrated that the
-procedure meets the limit. For the total (intermediate) SD, which is a sum of variance components,
-the effective degrees of freedom come from the Satterthwaite approximation.
-
-## Accuracy
-
-Report mean percent recovery, or the difference from the accepted true value, **with a confidence
-interval** — Q2(R2) 3.3.1.4 is explicit, and a bare mean is not sufficient. The interval is
-`mean ± t_{1-α/2, n-1} · s/√n` at each level.
-
-The stricter reading, available as `--require-ci-within-limit`, asks that the whole interval sit
-inside the acceptance limit rather than just the point estimate. Q2(R2) says the observed interval
-should be *compatible with* the criterion. Which reading applies is a decision to make and justify in
-the protocol, before the data exist.
-
-### Combined accuracy and precision
-
-Q2(R2) 3.3.3 permits a single combined criterion assessed with a prediction interval, a tolerance
-interval, or a confidence interval, instead of separate accuracy and precision criteria. This is
-often the more honest framing — what matters is whether a future reportable result will be close
-enough to the truth, which is a tolerance-interval question. If you use it, describe the approach and
-supply the individual results as supporting information.
-
-## Detection and quantitation limits
-
-The `3.3σ/S` and `10σ/S` formulae are estimates whose value depends entirely on which σ you choose.
-On the same calibration data, σ from the residual SD of the regression, from the SD of the
-y-intercept, and from the SD of blank responses commonly give limits spanning a factor of two or
-more. None is wrong; they answer slightly different questions.
-
-Consequences for practice:
-
-- Report the limit **and the approach**, per Q2(R2) 3.2.3.5. A number alone is not reportable.
-- Confirm an estimated limit with real determinations at or near it. `3.2.3.4` allows skipping the
-  estimate entirely and validating the QL directly by accuracy and precision, which is cleaner.
-- For impurity procedures, the QL must be at or below the reporting threshold.
-- Signal-to-noise scaling assumes noise is constant with concentration. It usually is not; confirm at
-  the resulting level.
-- CLSI's limit of blank / limit of detection / limit of quantitation are defined differently again,
-  with their own protocols. Do not translate between the schemes casually.
-
-## Method comparison and transfer
-
-### Ordinary least squares is the wrong regression here
-
-OLS assumes the x values are known without error. In a method comparison both procedures have
-measurement error, and ignoring the error in x biases the slope toward zero — a regression-dilution
-effect that manufactures apparent proportional bias where none exists.
-
-**Deming regression** accounts for error in both variables given `λ`, the ratio of error variances.
-With `λ = 1` (equal precision) it reduces to orthogonal regression. Standard errors here come from a
-jackknife, which avoids distributional assumptions about the slope.
-
-**Passing–Bablok** is non-parametric: the slope is a shifted median of all pairwise slopes, with a
-rank-based confidence interval. It assumes no distribution, tolerates outliers, and is the usual
-choice in clinical method comparison. Its confidence intervals are wider, honestly reflecting what
-the data support.
-
-Report both. Agreement between them is reassuring; disagreement points to outliers or to a
-distributional problem worth understanding before concluding anything.
-
-### Bland–Altman answers a different question
-
-Regression asks whether the relationship is proportional. Bland–Altman asks how far apart two
-procedures are on the same sample: mean difference (bias) and limits of agreement at
-`bias ± 1.96·SD`. Both matter, and neither substitutes for the other.
-
-Two cautions. The limits of agreement are themselves estimates with confidence intervals, which are
-wide for small n — the script reports the half-width. And if the difference trends with
-concentration, a single mean bias and its limits are misleading no matter how tight they look; the
-script tests for that trend and flags it.
-
-### Equivalence: TOST, not a t test
-
-The default reflex at a transfer is a two-sample or paired t test, and `p > 0.05` written up as "no
-significant difference, methods equivalent". This inverts the logic. A non-significant result means
-the data were insufficient to detect a difference — and on a transfer dataset of ten or twenty
-samples, that outcome is close to guaranteed regardless of whether the procedures agree. The test
-rewards small studies.
-
-**Two one-sided tests** invert the hypotheses to match the question. Given a pre-stated margin `δ`,
-test both `H01: difference ≤ -δ` and `H02: difference ≥ +δ`. Rejecting both concludes equivalence.
-Operationally: the `(1-2α)` confidence interval on the difference must lie entirely inside `±δ`.
-
-A worked contrast from `compare_methods.py`: a transfer with a consistent +1.46% bias gives a paired
-t-test p-value below 0.0001 — a highly significant difference — while TOST establishes equivalence at
-a ±2% margin. Both are correct. The difference is real and it is small enough not to matter. Only
-TOST answers the question the transfer actually asks.
-
-The margin must be pre-stated, from the specification or the analytical target profile. A margin
-chosen after seeing the data is not an acceptance criterion, and this is the single most common way
-equivalence testing gets misused.
-
-## What none of this does
-
-These are computations. They do not establish that a procedure is fit for purpose. That conclusion
-requires the intended purpose, the specification, product and process knowledge, the laboratory's
-history with the technique, and the judgement of people who are accountable for it. A script that
-reported "validated" would be lying about what it can know.