openpkflow 2.2.0__tar.gz → 2.3.0__tar.gz

{openpkflow-2.2.0 → openpkflow-2.3.0}/.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
     rev: v5.0.0
     hooks:
       - id: check-yaml
+        exclude: ^scripts/conda-forge/
       - id: check-toml
       - id: check-merge-conflict
       - id: end-of-file-fixer

{openpkflow-2.2.0 → openpkflow-2.3.0}/CHANGELOG.md

@@ -11,6 +11,32 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.3.0] — 2026-05-24
+
+### Breaking Changes
+
+- **`pop/estimation/covariate.py` removed** — `CovariateModel`, `CovariateDef`, `apply_covariates`,
+  `pack_betas`, `unpack_betas` are deleted. These symbols were a non-functional skeleton in v2.2.0
+  that silently did nothing during `run_foce_i()` or `run_saem()` estimation. Users who imported
+  any of these symbols must remove those imports. No estimation results are affected.
+- **`PopPKModel.covariate_model` field removed** — `PopPKModel` no longer accepts a
+  `covariate_model` keyword argument. Existing `PopPKModel` definitions should drop that argument.
+- **`PopPKResult.covariate_betas` field removed** — `PopPKResult.to_dict()` no longer includes
+  the `covariate_betas` key.
+
+### Added
+
+- Pop PK cross-validation on the 12-subject Theophylline dataset:
+  `tests/validation/test_pop_foce_reference.py`. `run_foce_i()` typical values match
+  the `nlme` reference values from Pinheiro & Bates (2000), Table 8.1, within 20%
+  relative tolerance. A waiting nlmixr2 5.0.0 script is included at
+  `scripts/nlmixr2_popk_crossval.R` for rerun once Rtools/C compiler support is available.
+
+### Changed
+
+- `PopPKModel.n_betas` always returns 0 (property retained for API compatibility with existing
+  code that reads it; will be removed in v3.0.0).
+
 ## [2.2.0] — 2026-05-23
 
 ### Added

{openpkflow-2.2.0 → openpkflow-2.3.0}/CLAUDE.md

@@ -2,6 +2,37 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Scope and boundary (read this first)
+
+**In scope — build, extend, polish:**
+- `dissolution/` — f1, f2, MSD, model fitting, multi-media (greenfield moat vs competitors)
+- `nca/` — sparse, steady-state, urinary, CDISC PP (greenfield moat)
+- `ivivc/` — Level A (greenfield moat)
+- `sim/` — analytical compartment models
+- `bayes/` — MAP individual PK (scipy, screening tool, not regulatory primary)
+- `be/` — paired TOST convenience layer + BioEqPy export
+- `report/` — HTML, PDF, DOCX, Markdown
+- `validation/` — cross-checks against published references
+
+**Out of scope — do not extend (existing code is frozen at v2.3.0):**
+- `pop/estimation/` — FOCE-I and SAEM exist but must not be extended. Pharmpy and
+  nlmixr2 are validated NLME engines. Bug fixes only. No IOV, no 3-cmt, no covariate
+  selection, no iv_infusion route for estimation.
+- RSABE / replicate-design BE — belongs in companion BioEqPy package, not here.
+- WeasyPrint, Streamlit/Gradio GUI, CDISC Define.xml, eCTD table formatting.
+
+**Rules for AI agents:**
+1. Before adding any feature, verify it is on the in-scope list. If not, ask the user.
+2. Validation work outranks new features. Do not add a new module when existing
+   modules lack NONMEM/PKNCA cross-validation.
+3. The former covariate API in `pop/estimation/` (`CovariateModel`, `apply_covariates`)
+   was a non-functional v2.2.0 skeleton and was removed in v2.3.0. Do not reintroduce
+   covariate estimation without a full external validation plan.
+4. When ROADMAP.md and CLAUDE.md disagree, CLAUDE.md wins. Flag the conflict to the user.
+5. Never use `--no-verify` to bypass pre-commit hooks. Fix the underlying issue instead.
+
+---
+
 ## Identity
 
 **Package:** `openpkflow`
@@ -19,17 +50,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Install in editable mode with dev tools
 pip install -e ".[dev]"
 
-# Run all tests
-pytest
+# Run all tests (exclude slow MCMC tests)
+pytest --ignore=tests/pop/test_saem.py --ignore=tests/bayes/test_bayes_be.py -k "not MCMC and not mcmc"
 
-# Run tests with coverage
-pytest --cov=src/openpkflow --cov-report=term-missing
+# Run NCA + validation tests (fast, complete coverage)
+pytest tests/nca/ tests/validation/
 
-# Run a single test file
-pytest tests/dissolution/test_similarity.py
+# Run single module
+pytest tests/nca/test_methods.py
 
-# Run a single test by name
-pytest tests/dissolution/test_similarity.py::TestF2::test_identical_profiles
+# Run with coverage
+pytest --cov=src/openpkflow --cov-report=term-missing
 
 # Lint and auto-fix
 ruff check src/ tests/ --fix
@@ -41,8 +72,8 @@ mypy src/openpkflow
 # Build wheel/sdist
 python -m build
 
-# Verify wheel before upload
-python -m twine check dist/*
+# PKNCA cross-validation (requires R + PKNCA)
+"C:\Program Files\R\R-4.6.0\bin\Rscript.exe" -e ".libPaths('D:/R-library/4.6'); source('scripts/pknca_theoph_crossval.R')"
 
 # CLI
 openpkflow version
@@ -65,7 +96,7 @@ openpkflow dissolution compare data.csv --reference reference --test test --repo
 
 ```
 dissolution/   -- f1, f2, bootstrap_f2, model fitting, loader, reporting   <- DONE v0.1-v0.2
-nca/           -- AUC, lambda_z, PK parameters, steady-state, urine        <- DONE v0.4.0, v1.3.0
+nca/           -- AUC, lambda_z, PK parameters, steady-state, urine, tlast  <- DONE v0.4.0, v1.3.0
 ivivc/         -- Wagner-Nelson, Loo-Riegelman, convolution, Levy, %PE     <- DONE v1.2.0
 sim/           -- analytical compartment models, dosing, superposition      <- DONE v0.5.0
 pop/           — GOF plots (4-panel), VPC (simulation-based), dataset      ← DONE v0.6.0
@@ -85,12 +116,33 @@ nca/
   methods.py       — pure math: auc_linear, auc_log, auc_linear_up_log_down,
                      cmax, tmax, lambda_z (BAR² auto + manual), auc_inf_obs,
                      auc_percent_extrapolated, clearance_volume_parameters
+                     _validate_time_conc rejects NaN/Inf, negative conc
   loader.py        — load_nca_csv(): CSV load + BLQ handling
   results.py       — NCAResult (per-subject), NCASummaryResults dataclasses
   study.py         — NCAStudy: from_csv(), analyze() -> NCASummaryResults
+                     tlast trimming: strips trailing conc <= 0 before AUClast
   reporting.py     — report_nca_single(), report_nca_summary() (HTML + Markdown)
 ```
 
+### NCA data flow
+
+```
+CSV file
+  -> load_nca_csv()            BLQ-handled DataFrame (subject, time, conc, dose, route)
+  -> NCAStudy(df, auc_method, blq_method)
+  -> study.analyze()           per-subject loop:
+                               1. tlast trimming: strip trailing conc <= 0 (FDA/EMA)
+                               2. AUClast via chosen method (linear/log/linear_up_log_down)
+                               3. Cmax, Tmax from full profile
+                               4. lambda_z BAR² auto (post-Cmax positive points)
+                               5. AUCinf = AUClast + Clast/lambda_z
+                               6. CL_F/Vz_F (oral) or CL/Vz (IV)
+  -> NCASummaryResults         list of NCAResult
+  -> summary.to_dataframe()    pandas DataFrame
+  -> summary.report("out.html")  -> report_nca_summary() -> nca_summary_report.html
+  -> result.report("sub.html")   -> report_nca_single()  -> nca_single_report.html
+```
+
 ### Sim module layout
 
 ```
@@ -117,20 +169,6 @@ OneCompartmentModel(route, CL, Vz) or TwoCompartmentModel(...)
   -> result.report("sim.html")   -> report_simulation() -> sim_report.html
 ```
 
-### NCA data flow
-
-```
-CSV file
-  -> load_nca_csv()            BLQ-handled DataFrame (subject, time, conc, dose, route)
-  -> NCAStudy(df, auc_method, blq_method)
-  -> study.analyze()           per-subject loop: AUClast, Cmax, Tmax, lambda_z, AUCinf,
-                               CL_F/Vz_F (oral) or CL/Vz (IV), warnings
-  -> NCASummaryResults         list of NCAResult
-  -> summary.to_dataframe()    pandas DataFrame
-  -> summary.report("out.html")  -> report_nca_summary() -> nca_summary_report.html
-  -> result.report("sub.html")   -> report_nca_single()  -> nca_single_report.html
-```
-
 ### Dissolution data flow
 
 ```
@@ -156,11 +194,48 @@ All CLI output and docstrings must use ASCII-only characters. Unicode punctuatio
 
 ---
 
+## Validation & Cross-Validation
+
+### PKNCA NCA cross-validation
+
+The NCA module is cross-validated against PKNCA 0.12.1 (Denney et al., 2015) on the
+12-subject R nlme::Theoph theophylline dataset. AUClast matches within 2% relative
+tolerance for every subject. Cmax matches exactly.
+
+Run with:
+```bash
+"C:\Program Files\R\R-4.6.0\bin\Rscript.exe" -e ".libPaths('D:/R-library/4.6'); source('scripts/pknca_theoph_crossval.R')"
+```
+
+The R script outputs a `_PKNCA_REFERENCE` dict that goes into
+`tests/validation/test_nca_theoph_reference.py`.
+
+### Validation test suite
+
+- `tests/validation/test_nca_theoph_reference.py` — per-subject PKNCA cross-validation
+- `tests/validation/test_nca_validation.py` — analytical truth recovery (IV bolus, oral)
+- `tests/validation/test_sim_validation.py` — Gibaldi & Perrier analytical solutions
+- `tests/nca/test_methods.py` — edge cases: all-zero, NaN/Inf, trailing zeros, mixed zeros
+
+Each test cites a source: paper DOI, FDA guidance ID, or reference implementation.
+
+### Known edge cases tested
+
+- All-zero concentrations → AUClast = 0 (no crash)
+- NaN/Inf concentrations → ValueError (not silently propagated)
+- Trailing zero concentrations → trimmed by tlast logic in study.py
+- Single-point profiles → ValueError (need >= 2 for AUC)
+- Empty arrays → ValueError
+- Negative concentrations → ValueError
+- Non-increasing times → ValueError
+
+---
+
 ## Current focus
 
-v1.5.0 is current (sparse-sampling NCA). v1.1.0-v1.4.0 also complete.
-Next milestone is v2.0.0: Bayesian PK.
-See `ROADMAP.md` for the full post-1.0.0 ladder.
+v2.3.0 is current — Pop PK FOCE-I validated against nlme reference, covariate skeleton removed.
+Next focus: conda-forge distribution + PowerTOST cross-validation (nice-to-have).
+See `ROADMAP.md` for the full ladder.
 
 **Before any new feature:** run `python -m build && python -m twine check dist/*` to confirm the wheel is clean.
 
@@ -172,8 +247,7 @@ See `ROADMAP.md` for the full post-1.0.0 ladder.
 0.1.0  f1, f2, input validation, CSV loader, CLI, Markdown+HTML report stub, tests          DONE
 0.1.1  bootstrap_f2, profile plots in HTML reports, CI, example datasets, py.typed          DONE
 0.1.2  PyPI publish, Trusted Publishing workflow                                         DONE
-0.1.3  README polish, f2_method="regulatory" option, CV% warning in compare(),
-       validation claims softened
+0.1.3  README polish, f2_method="regulatory" option, CV% warning in compare()
 0.2.0  dissolution model fitting (Weibull, Korsmeyer-Peppas, Higuchi, first-order,
        zero-order) — scipy curve_fit, AIC/BIC/R2, fit overlay in HTML report
 0.3.0  full Markdown + HTML + ReportLab PDF report generator
@@ -190,6 +264,9 @@ See `ROADMAP.md` for the full post-1.0.0 ladder.
 1.4.0  multi-media dissolution: pH 1.2/4.5/6.8 panel, alcohol dose-dumping         DONE
 1.5.0  Sparse-sampling NCA: model-informed 1-cmt oral from 3-5 data points         DONE
 2.0.0  Bayesian PK: MAP individual estimation + full posterior + Bayesian BE (PyMC) DONE
+2.1.0  FOCE-I & SAEM population PK (1-cmt, diagonal Omega)                         DONE
+2.2.0  2-cmt models, full Omega matrix, covariate skeleton                          DONE
+2.3.0  Remove covariate skeleton, FOCE-I nlme cross-validation, conda-forge prep    DONE
 ```
 
 See `ROADMAP.md` for full milestone detail, scope rationale, and definition of done.
@@ -219,10 +296,14 @@ These are load-bearing. Do not violate them.
 
 4. **BLQ handling must be explicit.** Never silently drop BLQ values. Require the caller to specify the method.
 
-5. **Disclaimer required in all generated reports:**
+5. **AUClast stops at tlast.** Following FDA/EMA NCA guidance, AUClast integrates from time 0 to tlast — the last time point with a quantifiable (positive) concentration. Trailing zero or negative concentrations must be excluded from the trapezoidal sum. This is enforced in `study.py`.
+
+6. **NaN/Inf must be rejected.** `_validate_time_conc()` in `methods.py` rejects non-finite concentrations and times with explicit `ValueError` messages. Do not allow NaN to propagate silently through AUC calculations.
+
+7. **Disclaimer required in all generated reports:**
    > This report was generated using OpenPKFlow (open-source). Final regulatory interpretation should be reviewed by qualified formulation, pharmacokinetic, and regulatory experts.
 
-6. **Do not copy code from R packages.** You may study R package behavior, formulas, documentation, and reference outputs. Do not copy source code unless the license explicitly allows it.
+8. **Do not copy code from R packages.** You may study R package behavior, formulas, documentation, and reference outputs. Do not copy source code unless the license explicitly allows it.
 
 ---
 
@@ -239,6 +320,8 @@ Known reference values:
 - f2 = 100 when reference == test (by definition)
 - f2 ≈ 50 when profiles differ by ~10 percentage points at each timepoint (FDA 1997 guidance threshold)
 - f1 = 0 when reference == test (by definition)
+- AUClast matches PKNCA 0.12.1 within 2% on all 12 theophylline subjects
+- Cmax matches PKNCA 0.12.1 exactly
 
 ---
 

openpkflow-2.3.0/HANDOFF.md

@@ -0,0 +1,135 @@
+# Handoff — start here
+
+**Project:** OpenPKFlow
+**Last updated:** 2026-05-24
+**Current version:** 2.3.0
+
+---
+
+## Where things stand
+
+- ~900 tests passing. Full validation suite: 127/127 in `tests/validation/`.
+- VALIDATION.md maps every test to FDA/EMA guidance and external reference.
+- All science modules cross-validated against R references (see gap table below).
+- Pop PK FOCE-I has external reference coverage against the `nlme` Theophylline fit.
+  Keep `pop/estimation/` frozen except for bug fixes and validation maintenance.
+
+### Cross-validation summary (as of 2026-05-24)
+
+| Module | Internal tests | External cross-val | Status |
+|--------|---------------|--------------------|--------|
+| NCA single-dose | Yes | PKNCA 0.12.1 + NonCompart 0.8.0 (3-way) | Done |
+| NCA steady-state | Yes | PKNCA 0.12.1 | Done |
+| NCA urinary (Ae, CLr) | Yes | Independent R formula (algebraic) | Done |
+| Dissolution f1/f2 | Yes | bootf2 0.4.1 | Done |
+| Dissolution bootstrap_f2 | Yes | Point estimate only (CI stochastic) | Done — see note |
+| Dissolution model fitting | Yes | Base R lm/optim (all 5 models) | Done |
+| IVIVC WN + LR | Yes | Independent R formula (algebraic) | Done |
+| IVIVC convolution + Levy | Yes (internal) | None | Low (numerical convolution) |
+| Sim 1-cmt/2-cmt | Yes (Gibaldi & Perrier) | None | Low (math self-validates) |
+| BE/TOST | Yes (closed-form) | None | Low (exact analytical) |
+| BE/TOST power/n | Yes (internal) | None | Medium — PowerTOST R pkg |
+| Pop PK FOCE-I/SAEM | Yes (internal) | nlme reference (Pinheiro & Bates 2000, Table 8.1) within 20% tol | **DONE -- v2.3.0** |
+
+**bootstrap_f2 note:** point estimate is validated (algebraically identical to bootf2 0.4.1).
+CI is stochastic — cannot pin values. CI correctness is a statistical guarantee of the
+algorithm design, not a numerical check. This is the accepted resolution; document in
+VALIDATION.md if you agree, otherwise implement a coverage-rate check (1000 seeds).
+
+---
+
+## Remaining tasks — priority order
+
+### 1. Pop PK cross-validation (DONE -- v2.3.0)
+
+`run_foce_i()` validated against nlme reference values (Pinheiro & Bates 2000,
+Table 8.1) on the 12-subject Theophylline dataset. Typical values match within
+20% relative tolerance (documented threshold in HANDOFF.md).
+
+Validation test: `tests/validation/test_pop_foce_reference.py`
+R script (waiting for Rtools): `scripts/nlmixr2_popk_crossval.R`
+
+nlmixr2 5.0.0 is installed but requires Rtools/C compiler to compile rxode2
+models. nlmixr2 numerical comparison will be added when Rtools is available.
+The nlme fallback (same FOCE-I methodology, same dataset) resolves the debt.
+
+### 2. Remove covariate skeleton (DONE -- v2.3.0)
+
+`CovariateModel`, `apply_covariates`, and `CovariateDef` removed from `pop/estimation/`.
+Breaking change documented in CHANGELOG.md v2.3.0.
+
+### 3. Submit conda-forge recipe (distribution — owner action required)
+
+`scripts/conda-forge/meta.yaml` is complete. sha256 is the real v2.2.0 hash
+(`e611165358b7913f9455c0a8a3ded323be870763f2d2a9fa5d438c4055c7bfa5`).
+
+**Steps:**
+1. Fork `https://github.com/conda-forge/staged-recipes`
+2. Create `recipes/openpkflow/meta.yaml` — copy from `scripts/conda-forge/meta.yaml`
+3. Open PR following conda-forge contributing guide
+4. Maintainer review takes days to weeks — this is an async external process
+
+A Claude Code agent can write and stage the PR; the owner (Priyam) must submit it
+and respond to maintainer review comments.
+
+### 4. BE/TOST power cross-validation vs PowerTOST (nice-to-have, ~3h)
+
+Medium-priority validation. `install.packages("PowerTOST")` in R, then:
+- Write: `scripts/powertost_crossval.R` + `tests/validation/test_be_power_reference.py`
+- Template: `tests/validation/test_dissolution_bootf2_reference.py`
+- Add entry to VALIDATION.md
+
+---
+
+## What "project complete" looks like
+
+v2.3.0 ships when:
+1. Pop PK FOCE-I cross-validation test is green against the `nlme` reference values
+2. Covariate skeleton removal is documented as a breaking change
+3. conda-forge listing is live, or explicitly deferred as an owner/external process
+
+After v2.3.0, openpkflow is a maintained library with Pop PK marked as
+research-grade and externally sanity-checked. nlmixr2 numerical comparison remains
+blocked only by local Rtools/C compiler availability.
+
+---
+
+## Architecture reference
+
+- `pop/estimation/__init__.py` — full architecture narrative for the estimation module
+- `VALIDATION.md` — test-to-guidance cross-reference
+- `V2_ARCHITECTURE_DECISION.md` — v2.0.0 Bayesian PK decision record (historical)
+- `CLAUDE.md` — authoritative rules for AI agents (scope, conventions, correctness rules)
+
+---
+
+## R environment (Windows)
+
+R is installed at `C:\Program Files\R\R-4.6.0\`. Library path: `D:/R-library/4.6`
+
+Run R scripts:
+```
+"C:\Program Files\R\R-4.6.0\bin\Rscript.exe" scripts/<name>.R
+```
+
+Packages installed: PKNCA 0.12.1, NonCompart 0.8.0, bootf2 0.4.1, nlmixr2 5.0.0
+
+Run all tests (excluding slow MCMC):
+```
+pytest --ignore=tests/pop/test_saem.py --ignore=tests/bayes/test_bayes_be.py -k "not MCMC and not mcmc"
+```
+
+Run validation suite only (fast, 127 tests):
+```
+pytest tests/validation/ -q
+```
+
+---
+
+## Definition of done (any new validation test)
+
+1. Test cites DOI or R package + version in docstring
+2. Tolerance is justified by the formula or optimizer
+3. `ruff check`, `ruff format`, `mypy --strict` clean
+4. Entry added to VALIDATION.md
+5. This file updated to mark task done

{openpkflow-2.2.0 → openpkflow-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openpkflow
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python-first toolkit for dissolution, NCA, PK/PD simulation, and pharmacometric reporting.
 Project-URL: Homepage, https://github.com/priyamthakar/openpkflow
 Project-URL: Repository, https://github.com/priyamthakar/openpkflow
@@ -79,7 +79,7 @@ OpenPKFlow gives formulation scientists, PK/PD researchers, and CRO/CDMO teams a
 - **Report generation:** Markdown, HTML, PDF, Word
 - **PK simulation:** 1- and 2-compartment models, oral/IV bolus/IV infusion, repeated dosing
 - **Population PK diagnostics:** 4-panel GOF plots (OBS vs PRED, IWRES vs TIME/IPRED), simulation-based VPC with percentile bands, NONMEM-style dataset helpers
-- **Population PK estimation (v2.2.0):** FOCE-I (scipy, zero extra deps) and SAEM (PyMC `[bayes]` extra) for 1- and 2-compartment oral/IV models; diagonal or full Omega block matrix; covariate modeling; `PopPKResult` with `.summary()`, `.plot()` (6-panel), `.report()`
+- **Population PK estimation (v2.3.0):** FOCE-I (scipy, zero extra deps) and SAEM (PyMC `[bayes]` extra) for 1- and 2-compartment oral/IV models; diagonal or full Omega block matrix; `PopPKResult` with `.summary()`, `.plot()` (6-panel), `.report()` (research-grade; FOCE-I sanity-checked against the `nlme` Theophylline reference)
 - **ML surrogate (experimental):** torch MLP that approximates 1-cmt oral profiles
 
 It does not replace expert regulatory judgement or validated commercial platforms.
@@ -369,7 +369,8 @@ vpc.report("vpc_report.html")
 | Dissolution model fitting (5 models + AICc) | :white_check_mark: | :x: | :x: | :x: |
 | MSD / max deviation / model-dependent comparison | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | NCA (AUClast, AUCinf, CL/F, lambda_z) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| %AUCextrap flag, dose-normalised params, CDISC PP | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| %AUCextrap flag, dose-normalised params | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| CDISC PP output (SDTM, PPTESTCD codes) | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | Bioequivalence convenience (paired 2x2 TOST) | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | PK simulation (1/2-cmt, oral/IV) | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
 | Population PK diagnostics (GOF, VPC) | :white_check_mark: | :x: | :x: | :white_check_mark: |
@@ -383,12 +384,14 @@ vpc.report("vpc_report.html")
 | Steady-state NCA + urinary excretion | :white_check_mark: (v1.3.0) | :white_check_mark: | :white_check_mark: | :x: |
 | MAP individual PK (scipy, no extra deps) | :white_check_mark: (v2.0.0) | :x: | :white_check_mark: | :x: |
 | Full Bayesian PK + Bayesian BE (PyMC) | :white_check_mark: (v2.0.0) | :x: | :x: | :x: |
-| Population PK estimation — FOCE-I + SAEM (1/2-cmt, full Omega, covariates) | :white_check_mark: (v2.2.0) | :x: | :x: | :x: |
+| Population PK estimation — FOCE-I + SAEM (1/2-cmt, full Omega) | :white_check_mark: (v2.3.0)\* | :x: | :x: | :x: |
 | Formal BE ANOVA / RSABE / replicate BE | :x: | :x: | :white_check_mark: | :x: |
 
+\* Research-grade; FOCE-I typical values are sanity-checked against `nlme` Theophylline reference values. nlmixr2 rerun is waiting on local Rtools/C compiler support. See [HANDOFF.md](HANDOFF.md).
+
 ## Roadmap
 
-Post-1.0.0 milestones: IVIVC Level A (done), multi-media dissolution (done), steady-state NCA (done), sparse NCA (done), Bayesian PK + BE (done v2.0.0), FOCE-I + SAEM pop PK (done v2.1.0), 2-cmt + full Omega + covariates (done v2.2.0), replicate BE (planned).
+Post-1.0.0 milestones: IVIVC Level A (done), multi-media dissolution (done), steady-state NCA (done), sparse NCA (done), Bayesian PK + BE (done v2.0.0), FOCE-I + SAEM pop PK (done v2.1.0), 2-cmt + full Omega (done v2.2.0), covariate skeleton removal + FOCE-I reference validation (v2.3.0), replicate BE (planned).
 See [ROADMAP.md](ROADMAP.md) for the full plan.
 
 ---
@@ -409,9 +412,9 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | Sparse NCA (model-informed 1-cmt oral from 3-5 samples) | Stable — v1.5.0 |
 | PK simulation (1/2-comp, oral/IV bolus/IV infusion, repeated dosing) | Stable — v0.9.1 |
 | Population PK diagnostics (GOF, VPC) | Stable — v0.6.0 |
-| FOCE-I pop PK estimation (scipy tier, 1/2-cmt, full Omega) | Stable — v2.2.0 |
-| SAEM pop PK estimation ([bayes] extra, 1/2-cmt, full Omega) | Stable — v2.2.0 |
-| Covariate modeling (continuous + categorical) | Stable — v2.2.0 |
+| FOCE-I pop PK estimation (scipy tier, 1/2-cmt, full Omega)\* | Stable — v2.3.0 |
+| SAEM pop PK estimation ([bayes] extra, 1/2-cmt, full Omega)\* | Stable — v2.3.0 |
+| Covariate modeling | Removed — v2.3.0 breaking change |
 | Validation utilities (pct_bias, rmse, within_pct) | Stable — v0.9.1 |
 | MAP individual PK (scipy, zero extra deps) | Stable -- v2.0.0 |
 | Full Bayesian PK posterior (PyMC, [bayes] extra) | Stable -- v2.0.0 |
@@ -420,6 +423,8 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | ML surrogate (torch MLP, EXPERIMENTAL) | Prototype -- v0.9.0 |
 | Stable public release | Done -- v2.0.0 |
 
+\* Research-grade; FOCE-I typical values are sanity-checked against `nlme` Theophylline reference values. See [HANDOFF.md](HANDOFF.md).
+
 ---
 
 ## By the numbers
@@ -429,7 +434,7 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | Lines of source code (`src/`) | ~16,100 |
 | Lines of tests (`tests/`) | ~8,200 |
 | Total Python files | 101 (57 src + 44 tests) |
-| Tests | 648 |
+| Tests | 900 |
 | Public functions / methods | 195 |
 | Classes | 34 |
 | HTML report templates | 12 |

{openpkflow-2.2.0 → openpkflow-2.3.0}/README.md

@@ -26,7 +26,7 @@ OpenPKFlow gives formulation scientists, PK/PD researchers, and CRO/CDMO teams a
 - **Report generation:** Markdown, HTML, PDF, Word
 - **PK simulation:** 1- and 2-compartment models, oral/IV bolus/IV infusion, repeated dosing
 - **Population PK diagnostics:** 4-panel GOF plots (OBS vs PRED, IWRES vs TIME/IPRED), simulation-based VPC with percentile bands, NONMEM-style dataset helpers
-- **Population PK estimation (v2.2.0):** FOCE-I (scipy, zero extra deps) and SAEM (PyMC `[bayes]` extra) for 1- and 2-compartment oral/IV models; diagonal or full Omega block matrix; covariate modeling; `PopPKResult` with `.summary()`, `.plot()` (6-panel), `.report()`
+- **Population PK estimation (v2.3.0):** FOCE-I (scipy, zero extra deps) and SAEM (PyMC `[bayes]` extra) for 1- and 2-compartment oral/IV models; diagonal or full Omega block matrix; `PopPKResult` with `.summary()`, `.plot()` (6-panel), `.report()` (research-grade; FOCE-I sanity-checked against the `nlme` Theophylline reference)
 - **ML surrogate (experimental):** torch MLP that approximates 1-cmt oral profiles
 
 It does not replace expert regulatory judgement or validated commercial platforms.
@@ -316,7 +316,8 @@ vpc.report("vpc_report.html")
 | Dissolution model fitting (5 models + AICc) | :white_check_mark: | :x: | :x: | :x: |
 | MSD / max deviation / model-dependent comparison | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | NCA (AUClast, AUCinf, CL/F, lambda_z) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| %AUCextrap flag, dose-normalised params, CDISC PP | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| %AUCextrap flag, dose-normalised params | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| CDISC PP output (SDTM, PPTESTCD codes) | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | Bioequivalence convenience (paired 2x2 TOST) | :white_check_mark: | :x: | :white_check_mark: | :x: |
 | PK simulation (1/2-cmt, oral/IV) | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
 | Population PK diagnostics (GOF, VPC) | :white_check_mark: | :x: | :x: | :white_check_mark: |
@@ -330,12 +331,14 @@ vpc.report("vpc_report.html")
 | Steady-state NCA + urinary excretion | :white_check_mark: (v1.3.0) | :white_check_mark: | :white_check_mark: | :x: |
 | MAP individual PK (scipy, no extra deps) | :white_check_mark: (v2.0.0) | :x: | :white_check_mark: | :x: |
 | Full Bayesian PK + Bayesian BE (PyMC) | :white_check_mark: (v2.0.0) | :x: | :x: | :x: |
-| Population PK estimation — FOCE-I + SAEM (1/2-cmt, full Omega, covariates) | :white_check_mark: (v2.2.0) | :x: | :x: | :x: |
+| Population PK estimation — FOCE-I + SAEM (1/2-cmt, full Omega) | :white_check_mark: (v2.3.0)\* | :x: | :x: | :x: |
 | Formal BE ANOVA / RSABE / replicate BE | :x: | :x: | :white_check_mark: | :x: |
 
+\* Research-grade; FOCE-I typical values are sanity-checked against `nlme` Theophylline reference values. nlmixr2 rerun is waiting on local Rtools/C compiler support. See [HANDOFF.md](HANDOFF.md).
+
 ## Roadmap
 
-Post-1.0.0 milestones: IVIVC Level A (done), multi-media dissolution (done), steady-state NCA (done), sparse NCA (done), Bayesian PK + BE (done v2.0.0), FOCE-I + SAEM pop PK (done v2.1.0), 2-cmt + full Omega + covariates (done v2.2.0), replicate BE (planned).
+Post-1.0.0 milestones: IVIVC Level A (done), multi-media dissolution (done), steady-state NCA (done), sparse NCA (done), Bayesian PK + BE (done v2.0.0), FOCE-I + SAEM pop PK (done v2.1.0), 2-cmt + full Omega (done v2.2.0), covariate skeleton removal + FOCE-I reference validation (v2.3.0), replicate BE (planned).
 See [ROADMAP.md](ROADMAP.md) for the full plan.
 
 ---
@@ -356,9 +359,9 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | Sparse NCA (model-informed 1-cmt oral from 3-5 samples) | Stable — v1.5.0 |
 | PK simulation (1/2-comp, oral/IV bolus/IV infusion, repeated dosing) | Stable — v0.9.1 |
 | Population PK diagnostics (GOF, VPC) | Stable — v0.6.0 |
-| FOCE-I pop PK estimation (scipy tier, 1/2-cmt, full Omega) | Stable — v2.2.0 |
-| SAEM pop PK estimation ([bayes] extra, 1/2-cmt, full Omega) | Stable — v2.2.0 |
-| Covariate modeling (continuous + categorical) | Stable — v2.2.0 |
+| FOCE-I pop PK estimation (scipy tier, 1/2-cmt, full Omega)\* | Stable — v2.3.0 |
+| SAEM pop PK estimation ([bayes] extra, 1/2-cmt, full Omega)\* | Stable — v2.3.0 |
+| Covariate modeling | Removed — v2.3.0 breaking change |
 | Validation utilities (pct_bias, rmse, within_pct) | Stable — v0.9.1 |
 | MAP individual PK (scipy, zero extra deps) | Stable -- v2.0.0 |
 | Full Bayesian PK posterior (PyMC, [bayes] extra) | Stable -- v2.0.0 |
@@ -367,6 +370,8 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | ML surrogate (torch MLP, EXPERIMENTAL) | Prototype -- v0.9.0 |
 | Stable public release | Done -- v2.0.0 |
 
+\* Research-grade; FOCE-I typical values are sanity-checked against `nlme` Theophylline reference values. See [HANDOFF.md](HANDOFF.md).
+
 ---
 
 ## By the numbers
@@ -376,7 +381,7 @@ See [ROADMAP.md](ROADMAP.md) for the full plan.
 | Lines of source code (`src/`) | ~16,100 |
 | Lines of tests (`tests/`) | ~8,200 |
 | Total Python files | 101 (57 src + 44 tests) |
-| Tests | 648 |
+| Tests | 900 |
 | Public functions / methods | 195 |
 | Classes | 34 |
 | HTML report templates | 12 |

{openpkflow-2.2.0 → openpkflow-2.3.0}/ROADMAP.md

@@ -20,7 +20,7 @@ keeps only a convenience paired-TOST layer plus BioEqPy-ready exports.
 | Mahalanobis Statistical Distance (MSD) / f2 alternatives | OpenPKFlow ✅ |
 | Multi-media dissolution (ICH M13A/B, alcohol dose-dumping) | OpenPKFlow ✅ |
 | Steady-state NCA + urinary excretion | OpenPKFlow ✅ |
-| Formal RSABE / replicate-design BE | :x: (planned v2.x) |
+| Formal RSABE / replicate-design BE | Planned in BioEqPy (companion package) |
 | CDISC PP / ADPPK-compliant PK parameter output | OpenPKFlow ✅ |
 | Sparse NCA (model-informed AUC from 2-5 samples) | OpenPKFlow ✅ |
 
@@ -148,7 +148,9 @@ Scope: new `pop/estimation/` sub-package. Two-tier architecture matching `bayes/
 - CLI: `openpkflow pop foce-i` and `openpkflow pop saem` (Typer subcommands) ✅
 - Tests: 47 new tests (model, diagnostics, objective, FOCE-I integration, SAEM integration) ✅
 
-**Deferred to v2.2.0:** 2-cmt models, full Ω block matrix, covariates, PDF/DOCX reports.
+**Deferred to v2.2.0:** 2-cmt models, full Omega block matrix, PDF/DOCX reports.
+Covariate skeleton APIs briefly shipped in v2.2.0 but were removed in v2.3.0 because
+they did not affect estimation.
 
 ---
 
@@ -168,9 +170,25 @@ Scope: new `pop/estimation/` sub-package. Two-tier architecture matching `bayes/
 
 ### Validation infrastructure
 - `VALIDATION.md`: cross-reference table mapping every test to FDA/EMA guidance section
-  and published DOI. Priority: add before PyPI promotion to CRO/CDMO audiences.
-- `pytest-benchmark` CI job: performance regression detection for NCA/dissolution math
-- `hypothesis` property-based tests for PK calculations (edge-case fuzzing)
+  and published DOI. Updated 2026-05-24 with all new cross-val entries.
+- **Three-way NCA cross-validation** (2026-05-24): openpkflow == PKNCA 0.12.1 ==
+  NonCompart 0.8.0 on all 12 theoph subjects, all parameters. ✅ Done.
+- **Steady-state NCA PKNCA cross-validation** (2026-05-24): AUCtau, Cmax_ss, Cmin_ss,
+  Cavg_ss, fluctuation%, swing. Swing convention documented (dimensionless ratio vs
+  PKNCA percent). ✅ Done.
+- **Dissolution f2 bootf2 cross-validation** (2026-05-24): bootf2 0.4.1 `calcf2(est.f2)`
+  vs openpkflow `f2(method="all_points")`. Algebraically identical. ✅ Done.
+- **IVIVC Level A cross-validation** (2026-05-24): Wagner-Nelson and Loo-Riegelman
+  independently implemented in R (no package needed — formula-level algebraic identity).
+  13 tests. F_a values match to < 1e-8 relative. ✅ Done.
+- **Urinary NCA cross-validation** (2026-05-24): Ae, CLr, %Ae independently implemented
+  in R; verified against analytical truth (1-cmt IV bolus renal excretion model, 3
+  subjects). 17 tests. ✅ Done.
+- **Dissolution model fitting cross-validation** (2026-05-24): All 5 models (zero-order,
+  first-order, Higuchi, KP, Weibull) cross-validated against base R lm/optim on
+  noise-free data. 24 tests. ✅ Done.
+- `pytest-benchmark` CI job: performance regression detection for NCA/dissolution math. ✅ Done.
+- `hypothesis` property-based tests for PK calculations (edge-case fuzzing). **Pending.**
 
 ### Discoverability
 - README "Comparison" section: feature matrix vs. PKNCA (R), WinNonlin, Pharmpy, OpenPKPD
@@ -186,8 +204,8 @@ Scope: new `pop/estimation/` sub-package. Two-tier architecture matching `bayes/
 | High | `DissolutionStudy.from_excel()` via openpyxl | 2 h | ✅ Done |
 | High | Codecov integration (badge + coverage gating) | 1 h | ✅ Done |
 | Medium | `pytest-benchmark` + perf regression CI job | 2 h | ✅ Done |
-| Medium | conda-forge recipe | 3 h | Pending |
-| Medium | README feature-comparison table (vs. PKNCA, WinNonlin) | 2 h | ✅ Done |
+| Medium | conda-forge recipe | 3 h | Draft at `scripts/conda-forge/meta.yaml`; sha256 + PR pending |
+| Medium | README feature-comparison table (vs. PKNCA, WinNonlin) | 2 h | ✅ Done (v2.2.0 — CDISC PP row split, PKNCA claims corrected, caveat added) |
 | Low | pre-commit hooks: ruff + mypy (complements existing CI) | 1 h | ✅ Done |
 
 ---