Community Quarto book documenting PKNCA ≥ 0.12.2 — feedback welcome

[TeunP]

What this is

I've built a comprehensive Quarto book documenting PKNCA ≥ 0.12.2 with runnable examples throughout. It covers every function, option, and parameter in the package and is aimed at analysts, clinical pharmacologists, and developers who want a single reference that goes deeper than the existing vignettes.

Source: https://github.com/TeunP/PKNCA.doc
(public repo — clone and quarto render to build locally with your installed PKNCA version)

---

What's covered

19 user chapters — all verified against live PKNCA 0.12.2 via Rscript:

Chapter	Highlights
Workflow & options	All 21 options documented with defaults and effect
Interval selection & parameter catalogue	Full get.interval.cols() table (143 params)
AUC types & integration methods	lin up/log down, lin-log (Tmax switch), linear; partial AUC; aucabove; time_above
Half-life & terminal phase	adj.r.squared.factor as selection tolerance; quality filters (only min.hl.points enforced inside fit); Tobit regression (pk.calc.half.life() direct API); lambda.z.corrxy
Extravascular (oral/SC)	BLQ handling, imputation strategies, tmin, first.tmin
Intravascular (IV)	Full bolus NCA + complete IV infusion example with ceoi, MRT correction
Multiple-dose / steady-state	deg.fluc, swing, ptr (= Cmax/Ctrough), cav, tau.choices
Urine excretion	ae, fe, clr.*; new: volpk, ermax, ertmax, ertlst, clr.*.dn
Sparse PK	AUC + SE + df; new sparse AUMC (sparse_aumclast); derived params (mrt.sparse.last, cl.sparse.last, kel.sparse.last)
Post-processing	exclude(), exclude_nca_*; normalize() / normalize_by_col(); .dn table (17 params); get_halflife_points()
Units	pknca_units_table() S3 generic + PKNCAdata method; allow_partial_missing_units
Imputation	start_conc0, start_predose, start_cmin; custom methods
Regulatory / CDISC	PP domain column mapping; exclude → PPEXCLFL; summary() for CSR tables
Validation	testthat suite; manual AUClast spot-check vs. both linear and lin-up/log-down
+ TSS, superposition, dose-aware interpolation, custom parameters, utilities

---

One thing I found while writing this

When hl_method = "tobit" is passed through PKNCAdata(options = list(hl_method = "tobit")) via pk.nca(), the call reaches pk.calc.half.life() but lloq is NULL, triggering the "Please report a bug" stop. The lloq is not currently wired through the pk.nca() pipeline from PKNCAconc. I documented the direct pk.calc.half.life() API as a workaround and added a note that pipeline integration is pending. Happy to open a separate issue if useful.

---

How to build

# Install PKNCA 0.12.2
remotes::install_github("humanpred/pknca")

# Clone and render
# git clone https://github.com/TeunP/PKNCA.doc
# cd PKNCA.doc
# quarto render

Feedback very welcome — happy to correct anything or fill gaps.

[billdenney]

At a glance, that looks great! It's a type of documentation that I've wanted to have for a while. Ideally, this would fit in a similar way to the way that mrgsolve generates their website (https://mrgsolve.org/). I don't know the mechanism for that exactly.

To make this a pull request, it will need to be part of the PKNCA code base (starting from this repository), but please investigate how mrgsolve does it first so that we can use the same method (I recall a conversation with Kyle from a long time ago that they did something differently).

[TeunP]

Thanks for the feedback! I looked into how mrgsolve does it — they use a companion repo pattern: the pkgdown function reference lives in the main package repo, and the Quarto user guide lives in a separate repo under the same org, with both linked at the top level. That seems like the right model for PKNCA too.

I've updated the book to be ready for that setup. Here's what's already done on my end:

• .github/workflows/book.yml — renders the book with Quarto and deploys to GitHub Pages on every push to main
• _quarto.yml — site-url set, navbar links back to the pkgdown function reference and pkgdown home
• index.qmd — dynamic version badge showing which PKNCA version the book was built against (updates on each render)
• All 21 chapters — every chapter now has a footer callout linking to the relevant humanpred.github.io/pknca/reference/<function>.html pages
• CLAUDE.md and CONTRIBUTING.md — cover the full update workflow, conventions, known gotchas, and the cross-linking pattern, so the book can be maintained by anyone

What would be needed from the humanpred org:

1. Create a new public repo humanpred/pknca-book (transfer or mirror TeunP/PKNCA.doc)
2. In that repo's Settings → Pages, set Source: GitHub Actions (the workflow is already there)
3. Optionally, add a link back from the pkgdown site's _pkgdown.yml navbar:

   navbar:
     right:
       - text: "User Guide"
         href: https://humanpred.github.io/pknca-book/

Separate bug: while writing the half-life chapter I found that when hl_method = "tobit" is routed via PKNCAdata(options = list(hl_method = "tobit")), the lloq from PKNCAconc is not wired through to pk.calc.half.life(), triggering the "Please report a bug" stop. I'm documenting the direct-call workaround in the book for now — happy to file a separate issue for this if useful.

[TeunP]

One additional note on the mrgsolve comparison: mrgsolve actually has three separate layers, not two:

Layer	URL	What it is
Hub site	mrgsolve.org	A Quarto website (not book) — landing page with full navbar (UserGuide, Blog, Vignettes, Learn, Docs, Models, Source, Help)
User guide	mrgsolve.org/user-guide/	The Quarto book — equivalent to what we built
pkgdown docs	mrgsolve.org/docs/	Function reference

What we built is the equivalent of mrgsolve.org/user-guide/. The book is live as a preview at https://teunp.github.io/PKNCA.doc/ — the layout looks correct for this layer.

To fully replicate the mrgsolve layout with that polished hub navbar, a third layer would be needed: a separate Quarto website (not book) serving as a landing page that links to the pkgdown docs, the user guide, and anything else under the humanpred umbrella. That would be an additional effort on top of the companion repo setup described above.

[TeunP]

Here is the architecture of what is already in place at https://teunp.github.io/PKNCA.doc/:

The two-site setup (layers 1 and 2)

humanpred/pknca (existing)          humanpred/pknca-book (new)
─────────────────────────           ──────────────────────────
pkgdown renders from R source       Quarto renders from .qmd files
        │                                       │
        ▼                                       ▼
humanpred.github.io/pknca/          humanpred.github.io/pknca-book/
├── reference/index.html            ├── index.html  (version badge)
│   ├── PKNCAconc.html              ├── workflow.html
│   ├── PKNCAdose.html              ├── intervals.html
│   ├── pk.nca.html                 ├── halflife.html
│   └── ... (all functions)         └── ... (21 chapters)
└── news/index.html                          │
        │                                    │
        └──── navbar: "User Guide" ──────────┘
                                             │
                              footer on every chapter:
                              "pkgdown reference: PKNCAconc() · pk.nca() · ..."
                              links back to reference/PKNCAconc.html

What a chapter looks like (bottom of every page)

Every chapter ends with a callout, e.g. on workflow.html:

pkgdown reference: PKNCAconc() · PKNCAdose() · PKNCAdata() · pk.nca() · PKNCA.options()

Each function name is a clickable link to its pkgdown reference page.

What the navbar looks like

The book's top navbar (set in _quarto.yml) has two links on the right:

Function Reference	→ humanpred.github.io/pknca/reference/index.html
pkgdown site	→ humanpred.github.io/pknca/

And on the pkgdown side (once the optional navbar entry is added), readers see a "User Guide" link pointing back to the book.

[TeunP]

For reference, I've added BUILDING_SETUP.md to the book repo — a step-by-step Claude Code instruction file covering all three layers: mirroring the book into humanpred/pknca-book, linking it from the pkgdown navbar, and building the hub landing page (layer 3) for full mrgsolve-style parity.

→ https://github.com/TeunP/PKNCA.doc/blob/main/BUILDING_SETUP.md