openpkflow 2.2.0__tar.gz → 2.5.0__tar.gz

openpkflow-2.5.0/.dockerignore

@@ -0,0 +1,11 @@
+*.pyc
+__pycache__/
+*.egg-info/
+dist/
+build/
+*.log
+.env
+.ipynb_checkpoints/
+site/
+.vscode/
+.idea/

{openpkflow-2.2.0 → openpkflow-2.5.0}/.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: write
+
 jobs:
   test:
     name: Python ${{ matrix.python-version }}
@@ -16,10 +19,10 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -32,7 +35,7 @@ jobs:
         run: pytest --tb=short -q --cov=openpkflow --cov-report=xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           files: coverage.xml
           flags: ${{ matrix.python-version }}
@@ -46,9 +49,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -61,9 +64,9 @@ jobs:
     if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.draft == false)
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -81,7 +84,7 @@ jobs:
             --benchmark-columns=min,mean,stddev,rounds,iterations
 
       - name: Upload benchmark results
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: benchmark-results-${{ github.sha }}
           path: benchmark.json

{openpkflow-2.2.0 → openpkflow-2.5.0}/.github/workflows/docs.yml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

{openpkflow-2.2.0 → openpkflow-2.5.0}/.github/workflows/publish.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -31,7 +31,7 @@ jobs:
         run: python -m twine check dist/*
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -47,7 +47,7 @@ jobs:
 
     steps:
       - name: Download build artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -68,7 +68,7 @@ jobs:
 
     steps:
       - name: Download build artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

openpkflow-2.5.0/.github/workflows/slow-validation.yml

@@ -0,0 +1,26 @@
+name: Slow validation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 3 * * 0"
+
+jobs:
+  slow-validation:
+    name: Slow validation (Python 3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,reports,ml]"
+
+      - name: Run slow validation tests
+        run: pytest -m slow tests/validation -q

{openpkflow-2.2.0 → openpkflow-2.5.0}/.gitignore

@@ -65,9 +65,14 @@ handout/
 !src/**/*.html
 !examples/**/*.html
 !docs/**
+!webapp/index.html
 
 # MkDocs generated site
 site/
+!site/
+site/*
+!site/app/
+!site/app/index.html
 
 # Uploaded images
 *.png

{openpkflow-2.2.0 → openpkflow-2.5.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/CLAUDE.md → openpkflow-2.5.0/AGENTS.md

@@ -1,6 +1,45 @@
-# CLAUDE.md
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.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
+
+**Web app layer (same as CLAUDE.md):**
+- `api/` — FastAPI REST adapter. Current routers: nca, dissolution, sim, ivivc, be.
+  Adding a new endpoint requires a schema (schemas/), service (services/), router (routers/),
+  and registration in main.py. Follow the existing nca router pattern exactly.
+- `webapp/` — React + Vite + Tailwind frontend. Current pages: Home, NCA, Dissolution, Sim,
+  IVIVC, BE. See `progress_web_app.md` for the full file map and next candidates.
+- Do NOT add pharmacometric logic to api/ or webapp/. Add to src/openpkflow/ first.
+
+**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 AGENTS.md disagree, AGENTS.md wins. Flag the conflict to the user.
+5. Never use `--no-verify` to bypass pre-commit hooks. Fix the underlying issue instead.
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+---
 
 ## Identity
 
@@ -19,17 +58,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 +80,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 +104,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 +124,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 +177,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 +202,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 +255,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 +272,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 +304,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 +328,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.2.0 → openpkflow-2.5.0}/CHANGELOG.md

@@ -11,6 +11,75 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.5.0] - 2026-06-12
+
+### Added
+
+- Student-friendly interface (`openpkflow.student`) with three one-call
+  functions: `analyze_pk()` for NCA, `fit_dissolution()` for dissolution
+  model fitting + f1/f2 comparison, and `fit_pk_model()` for 1/2-compartment
+  PK curve fitting.
+- `student/sim.py` compartmental equations delegate to validated
+  `sim/methods.py` functions (c_1cmt_oral, c_1cmt_iv_bolus, c_2cmt_oral) --
+  no duplicate math.
+- Hixson-Crowell model added to dissolution `_REGISTRY` (now 6 default
+  models: zero_order, first_order, higuchi, korsmeyer_peppas, weibull,
+  hixson_crowell).
+- External validation of NCA engine against WinNonlin(r) (Kim et al. 2018,
+  PMC6989226, Table 3): all 8 parameters within 0.02% for Theoph Subject 8
+  (Cmax, Tmax, lambda_z, t1/2, AUClast, AUCinf, CL/F, Vz/F).
+
+### Fixed
+
+- Mandated disclaimer text (CLAUDE.md rule 7) applied to all student module
+  report summaries.
+- `test_all_default_models_fit` updated to expect 6 default models.
+
+---
+
+## [2.4.0] — 2026-05-30
+
+### Added
+
+- Research-grade replicate bioequivalence screening via `replicate_be()`:
+  long-format full/partial replicate data parsing, GMR + conventional 90% CI,
+  CVwR estimation, EMA-style scaled-limit summaries, and FDA-style RSABE point
+  criterion screening. These outputs are explicitly documented as exploratory
+  and not a replacement for jurisdiction-specific validated SAS/R workflows.
+- Replicate BE CLI/report workflow: `openpkflow be replicate`, HTML/Markdown
+  reports, JSON export, example partial-replicate CSV, and scalar reference
+  validation fixtures for the screening calculations.
+- Release-readiness documentation and slow-validation workflow for heavyweight
+  reference checks, plus a read-only `scripts/release_readiness.py` checker.
+
+---
+
+## [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