| Title: | Bayesian Population Pharmacokinetics Without Writing 'Stan' |
|---|---|
| Description: | Fits 1- and 2-compartment linear population pharmacokinetic models by Bayesian inference. Models are described in a few lines of R and the data are a 'NONMEM'-style data set used as is. Precompiled 'Stan' programs use closed-form solutions superposed over doses, so no 'CmdStan', no model code and no compilation are needed at run time. Reports convergence diagnostics by default and predicts new regimens from the posterior without refitting. |
| Authors: | Daiki Kumakura [aut, cre] |
| Maintainer: | Daiki Kumakura <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.0 |
| Built: | 2026-11-17 22:32:01 UTC |
| Source: | https://github.com/DaikiKumakura/bayespk |
Fits 1- and 2-compartment linear population pharmacokinetic models to NONMEM-style data with precompiled Stan programs based on closed-form solutions.
Maintainer: Daiki Kumakura [email protected]
Stan Development Team. RStan: the R interface to Stan. https://mc-stan.org
Sampler diagnostics
bpk_diagnostics(x)bpk_diagnostics(x)
x |
A |
A list with the number of divergent transitions, iterations at the maximum tree depth, E-BFMI per chain, maximum R-hat and minimum bulk and tail effective sample sizes of the population parameters.
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) bpk_diagnostics(fit) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) bpk_diagnostics(fit) }
Posterior draws of population parameters
bpk_draws(x)bpk_draws(x)
x |
A |
A draws_df (posterior package) with typical values on the natural
scale, estimated covariate effects, standard deviations of between-subject
variability (log scale), correlations and residual error.
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) head(posterior::as_draws_df(bpk_draws(fit))) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) head(posterior::as_draws_df(bpk_draws(fit))) }
Samples the posterior with Stan (NUTS) using a precompiled closed-form model. The data are a NONMEM-style data frame used as is.
bpk_fit( model, data, priors = NULL, chains = 4, iter = 2000, warmup = floor(iter/2), cores = getOption("mc.cores", 1L), seed = sample.int(.Machine$integer.max, 1), adapt_delta = 0.9, prior_only = FALSE, ... )bpk_fit( model, data, priors = NULL, chains = 4, iter = 2000, warmup = floor(iter/2), cores = getOption("mc.cores", 1L), seed = sample.int(.Machine$integer.max, 1), adapt_delta = 0.9, prior_only = FALSE, ... )
model |
A model from |
data |
NONMEM-style data frame. |
priors |
Priors from |
chains, iter, warmup, cores, seed
|
Passed to |
adapt_delta |
Target acceptance rate of NUTS. |
prior_only |
Logical; sample from the prior only (ignores |
... |
Further arguments to |
Data columns (case-insensitive): ID, TIME, DV, AMT (required);
EVID, MDV, RATE, ADDL, II (optional) and any covariates used in
the model. "." is read as missing. Doses are records with EVID == 1
(or AMT > 0 when EVID is absent); observations are records with
EVID == 0, MDV != 1 and a non-missing DV. Observations at or before
the first dose of a subject are dropped with a message. Not supported in
this version: steady-state records, reset events, modelled rates,
time-varying covariates and below-quantification records.
An object of class bpk_fit.
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) summary(fit) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) summary(fit) }
Dosing regimen
dose_regimen(amt, ii = 0, n = 1, rate = 0, start = 0)dose_regimen(amt, ii = 0, n = 1, rate = 0, start = 0)
amt |
Dose amount. |
ii |
Interval between doses. |
n |
Number of doses. |
rate |
Infusion rate (0 for bolus or oral). |
start |
Time of the first dose. |
Data frame with time, amt and rate.
dose_regimen(100, ii = 12, n = 3)dose_regimen(100, ii = 12, n = 3)
Central-compartment concentrations of a linear 1- or 2-compartment model, summed over doses. These are the same solutions used in the Stan model.
pk_conc( times, doses, par, structure = c("1cmt", "2cmt"), route = c("iv", "oral") )pk_conc( times, doses, par, structure = c("1cmt", "2cmt"), route = c("iv", "oral") )
times |
Observation times. |
doses |
Data frame with |
par |
Named numeric vector of parameters ( |
structure |
|
route |
|
Numeric vector of concentrations at times.
pk_conc(0:24, dose_regimen(100), c(CL = 5, V = 50, KA = 1), "1cmt", "oral")pk_conc(0:24, dose_regimen(100), c(CL = 5, V = 50, KA = 1), "1cmt", "oral")
Describes the structural model, the parameters with between-subject variability, the residual error and covariate effects. Nothing is compiled: the structure selects one of the precompiled closed-form models.
pk_model( structure = c("1cmt", "2cmt"), route = c("iv", "oral"), iiv = NULL, error = c("proportional", "additive", "combined", "log"), covariates = list(), correlated = FALSE, ka_faster = FALSE )pk_model( structure = c("1cmt", "2cmt"), route = c("iv", "oral"), iiv = NULL, error = c("proportional", "additive", "combined", "log"), covariates = list(), correlated = FALSE, ka_faster = FALSE )
structure |
|
route |
|
iiv |
Character vector of parameters with log-normal between-subject variability. |
error |
Residual error: |
covariates |
A list of formulas, one or more per parameter, such as
|
correlated |
Logical; estimate correlations between the random effects. |
ka_faster |
Logical, oral models only. If |
Parameters are CL, V (1-compartment) or CL, V1, Q, V2
(2-compartment), plus KA for oral absorption. For oral dosing,
bioavailability is not estimated, so CL, V, Q and V2 are apparent
values (divided by F).
An object of class bpk_model.
pk_model("2cmt", route = "oral", iiv = c("CL", "V1", "KA"), covariates = list(CL ~ (WT / 70)^0.75))pk_model("2cmt", route = "oral", iiv = c("CL", "V1", "KA"), covariates = list(CL ~ (WT / 70)^0.75))
Named arguments set priors: structural parameters (CL = lognormal(...)),
estimated covariate effects by their names (b_wt = normal(...)), the
standard deviation of between-subject variability per parameter
(omega_CL = half_normal(...)) or for all (omega = half_normal(...)),
residual error (sigma_add, sigma_prop, or sigma_log for log-scale
error) and the LKJ shape for correlations (lkj = 2). Anything not given
gets a default, shown by bpk_fit() and stored in the fit.
pk_priors(...)pk_priors(...)
... |
Named priors. |
Default priors for typical values are centred on rough data-based values (non-compartmental estimates from the first dose) with a log-scale standard deviation of 2, that is, a factor of about 7 per standard deviation. They are weakly informative only; give informative priors when prior knowledge exists.
An object of class bpk_priors.
pk_priors(CL = lognormal(log(5), 0.5), omega = half_normal(0.5))pk_priors(CL = lognormal(log(5), 0.5), omega = half_normal(0.5))
Without regimen, returns individual predictions at the observed times of
the fitted subjects. With regimen, simulates concentrations for that
regimen: type = "population" draws new subjects from the estimated
between-subject distribution, type = "typical" uses the typical subject.
Predictions are computed in R from posterior draws with the closed-form
solutions; no refit is needed.
## S3 method for class 'bpk_fit' predict( object, regimen = NULL, times = NULL, type = c("population", "typical"), covariates = list(), ndraws = 1000, probs = c(0.05, 0.5, 0.95), residual = FALSE, seed = 1, ... )## S3 method for class 'bpk_fit' predict( object, regimen = NULL, times = NULL, type = c("population", "typical"), covariates = list(), ndraws = 1000, probs = c(0.05, 0.5, 0.95), residual = FALSE, seed = 1, ... )
object |
A |
regimen |
Optional dosing regimen from |
times |
Times for |
type |
|
covariates |
Named list of covariate values for |
ndraws |
Number of posterior draws used. |
probs |
Quantiles to report. |
residual |
Logical; add residual error (prediction intervals for observations rather than for the concentration). |
seed |
Random seed. |
... |
Unused. |
A data frame of predictions with quantiles.
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) predict(fit, regimen = dose_regimen(320, ii = 12, n = 3), ndraws = 200) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) predict(fit, regimen = dose_regimen(320, ii = 12, n = 3), ndraws = 200) }
Calls priorsense::powerscale_sensitivity() on the population parameters.
prior_sensitivity(x, ...)prior_sensitivity(x, ...)
x |
A |
... |
Passed to |
The result of priorsense::powerscale_sensitivity().
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) if (requireNamespace("priorsense", quietly = TRUE)) prior_sensitivity(fit) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) if (requireNamespace("priorsense", quietly = TRUE)) prior_sensitivity(fit) }
lognormal() is used for typical values of structural parameters (its
meanlog and sdlog are on the log scale), normal() for estimated
covariate effects, and half_normal() for standard deviations.
lognormal(meanlog, sdlog) normal(mean, sd) half_normal(scale)lognormal(meanlog, sdlog) normal(mean, sd) half_normal(scale)
meanlog, sdlog
|
Mean and standard deviation on the log scale. |
mean, sd
|
Mean and standard deviation. |
scale |
Scale of a half-normal distribution. |
An object of class bpk_prior.
lognormal(log(5), 0.5) half_normal(0.5)lognormal(log(5), 0.5) half_normal(0.5)
Summarise a fit
## S3 method for class 'bpk_fit' summary(object, probs = c(0.05, 0.5, 0.95), ...)## S3 method for class 'bpk_fit' summary(object, probs = c(0.05, 0.5, 0.95), ...)
object |
A |
probs |
Quantiles to report. |
... |
Unused. |
A data frame of posterior summaries and convergence diagnostics.
if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) summary(fit, probs = c(0.025, 0.5, 0.975)) }if (requireNamespace("nlmixr2data", quietly = TRUE)) { d <- nlmixr2data::theo_sd mod <- pk_model("1cmt", route = "oral", iiv = c("CL", "V", "KA")) fit <- bpk_fit(mod, d, chains = 2, iter = 1000, seed = 1) summary(fit, probs = c(0.025, 0.5, 0.975)) }