Package 'bayespk'

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

Help Index


bayespk: Bayesian population pharmacokinetics without writing Stan

Description

Fits 1- and 2-compartment linear population pharmacokinetic models to NONMEM-style data with precompiled Stan programs based on closed-form solutions.

Author(s)

Maintainer: Daiki Kumakura [email protected]

References

Stan Development Team. RStan: the R interface to Stan. https://mc-stan.org


Sampler diagnostics

Description

Sampler diagnostics

Usage

bpk_diagnostics(x)

Arguments

x

A bpk_fit.

Value

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.

Examples

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

Description

Posterior draws of population parameters

Usage

bpk_draws(x)

Arguments

x

A bpk_fit.

Value

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.

Examples

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)))
}

Fit a Bayesian population pharmacokinetic model

Description

Samples the posterior with Stan (NUTS) using a precompiled closed-form model. The data are a NONMEM-style data frame used as is.

Usage

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,
  ...
)

Arguments

model

A model from pk_model().

data

NONMEM-style data frame.

priors

Priors from pk_priors(); unspecified ones get defaults.

chains, iter, warmup, cores, seed

Passed to rstan::sampling().

adapt_delta

Target acceptance rate of NUTS.

prior_only

Logical; sample from the prior only (ignores DV).

...

Further arguments to rstan::sampling().

Details

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.

Value

An object of class bpk_fit.

Examples

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

Description

Dosing regimen

Usage

dose_regimen(amt, ii = 0, n = 1, rate = 0, start = 0)

Arguments

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.

Value

Data frame with time, amt and rate.

Examples

dose_regimen(100, ii = 12, n = 3)

Concentrations from closed-form solutions

Description

Central-compartment concentrations of a linear 1- or 2-compartment model, summed over doses. These are the same solutions used in the Stan model.

Usage

pk_conc(
  times,
  doses,
  par,
  structure = c("1cmt", "2cmt"),
  route = c("iv", "oral")
)

Arguments

times

Observation times.

doses

Data frame with time, amt and optionally rate (0 for bolus or oral doses), as returned by dose_regimen().

par

Named numeric vector of parameters (CL, V or CL, V1, Q, V2, and KA for oral).

structure

"1cmt" or "2cmt".

route

"iv" or "oral".

Value

Numeric vector of concentrations at times.

Examples

pk_conc(0:24, dose_regimen(100), c(CL = 5, V = 50, KA = 1), "1cmt", "oral")

Define a population pharmacokinetic model

Description

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.

Usage

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
)

Arguments

structure

"1cmt" or "2cmt".

route

"iv" (bolus, or infusion when the data have RATE > 0) or "oral" (first-order absorption).

iiv

Character vector of parameters with log-normal between-subject variability.

error

Residual error: "additive", "proportional", "combined" or "log" (additive on the log scale; DV must be positive).

covariates

A list of formulas, one or more per parameter, such as CL ~ (WT / 70)^0.75 (fixed exponent), CL ~ (WT / 70)^b_wt (estimated exponent named b_wt), CL ~ exp(b_age * (AGE - 40)) (estimated) or CL ~ (SEX == 1)^b_sex (estimated effect of a category). Terms can be multiplied: CL ~ (WT / 70)^0.75 * (CRCL / 100)^b_crcl.

correlated

Logical; estimate correlations between the random effects.

ka_faster

Logical, oral models only. If TRUE, the typical KA is constrained to be larger than the typical disposition rate (k = CL/V for 1-cmt, the fast rate alpha for 2-cmt) of a subject at the covariate reference values. This removes the flip-flop mode in which KA and the disposition rate swap. Use it only when absorption is known to be faster than distribution; it is wrong for flip-flop drugs such as many extended-release forms. The prior density on KA is kept and set to zero for KA <= rate (not renormalised). Default FALSE.

Details

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).

Value

An object of class bpk_model.

Examples

pk_model("2cmt", route = "oral", iiv = c("CL", "V1", "KA"),
         covariates = list(CL ~ (WT / 70)^0.75))

Specify priors

Description

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.

Usage

pk_priors(...)

Arguments

...

Named priors.

Details

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.

Value

An object of class bpk_priors.

Examples

pk_priors(CL = lognormal(log(5), 0.5), omega = half_normal(0.5))

Posterior predictions

Description

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.

Usage

## 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,
  ...
)

Arguments

object

A bpk_fit.

regimen

Optional dosing regimen from dose_regimen().

times

Times for regimen predictions (default: 100 points over the regimen plus one dosing interval).

type

"population" or "typical" (used with regimen).

covariates

Named list of covariate values for regimen predictions; unspecified covariates are set to the reference value of each term (categorical terms to their non-reference state, i.e. indicator 0).

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.

Value

A data frame of predictions with quantiles.

Examples

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)
}

Prior sensitivity by power-scaling

Description

Calls priorsense::powerscale_sensitivity() on the population parameters.

Usage

prior_sensitivity(x, ...)

Arguments

x

A bpk_fit.

...

Passed to priorsense::powerscale_sensitivity().

Value

The result of priorsense::powerscale_sensitivity().

Examples

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)
}

Prior distributions

Description

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.

Usage

lognormal(meanlog, sdlog)

normal(mean, sd)

half_normal(scale)

Arguments

meanlog, sdlog

Mean and standard deviation on the log scale.

mean, sd

Mean and standard deviation.

scale

Scale of a half-normal distribution.

Value

An object of class bpk_prior.

Examples

lognormal(log(5), 0.5)
half_normal(0.5)

Summarise a fit

Description

Summarise a fit

Usage

## S3 method for class 'bpk_fit'
summary(object, probs = c(0.05, 0.5, 0.95), ...)

Arguments

object

A bpk_fit.

probs

Quantiles to report.

...

Unused.

Value

A data frame of posterior summaries and convergence diagnostics.

Examples

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))
}