Join Bayesian model output summaries to input data

nm_join_bayes() and nm_join_bayes_quick() both join model output summaries to the input data. Underneath this calls bbr::nm_join() on each chain submodel and then combines the results, summarizing the table values across chains.

By default nm_join_bayes() replaces some table quantities with summaries of simulated values. It selects a subset of posterior samples and simulates EPRED and IPRED with specified mrgsolve model. It also feeds the simulated EPRED values to npde to calculate EWRES and NPDE values.

nm_join_bayes_quick(), on the other hand, avoids the simulation; the reported values are calculated from the table values. Warning: these estimates should not be considered as reliable but may be useful in the early stages of model development.

nm_join_bayes(
  .mod,
  mod_mrgsolve,
  .join_col = "NUM",
  .files = NULL,
  .superset = FALSE,
  ...,
  dv_col = "DV",
  y_col = "Y",
  point_fn = stats::median,
  probs = c(0.025, 0.975),
  resid_var = TRUE,
  n_post = 1000,
  epred = TRUE,
  ipred = TRUE,
  ipred_path = NULL,
  ewres_npde = TRUE,
  npde_decorr_method = c("cholesky", "inverse", "polar"),
  presim_fn = NULL,
  min_batch_size = 200
)

nm_join_bayes_quick(
  .mod,
  .join_col = "NUM",
  .files = NULL,
  .superset = FALSE,
  ...,
  point_fn = stats::median
)

Arguments

.mod

A bbi_nmbayes_model object.

mod_mrgsolve

An mrgsolve model object, potentially updated to be optimized for simulation from the data set and model (e.g., ODE solver tolerance). This must capture y_col.

.join_col

Use this column to join tables files to the input data.

.files

Paths to table files to pass to bbr::nm_join() calls (one per each chain submodel). By default, all tables specified in the $TABLE blocks of the control stream will be used. Note that, unlike bbr::nm_join(), this function accepts only relative paths (which nm_join() interprets as relative to submodel output directory) because the paths need to be valid for each chain submodel.

.superset

If FALSE, the default, the data will be joined to the NONMEM output and if TRUE, the NONMEM output will be joined to the data; that is, if you use .superset, you will get the same number of rows as you have in the input data and NONMEM output columns like PRED and CWRES will be filled with NA.

...

Additional arguments passed to bbr::nm_join().

dv_col

Pass this data column as the dependent variable when calculating EWRES and NPDE.

y_col

The name of the dependent variable in mod_mrgsolve. This is a simulated quantity corresponding to dv_col.

point_fn

Function used to calculate point estimates of table values across chains and of simulated EPRED and IPRED values (e.g., mean or median).

probs

A two-item vector of lower and upper probabilities to pass to stats::quantile() to calculate the bounds of the simulated EPRED and IPRED values.

resid_var

Whether to include residual variability in simulations.

n_post

Randomly select this number of posterior draws to use as input to the simulation.

epred

Simulate EPRED values, including the point estimate as EPRED and the bounds as EPRED_lo and EPRED_hi.

ipred

Simulate IPRED values, including the point estimate as IPRED and the bounds as IPRED_lo and IPRED_hi.

ipred_path

Write the IPRED simulation result (as comma-separated values) to this path. This is useful if you need access to the full results (e.g., for LOO calculations), not just the summary returned by this function.

ewres_npde

Whether to replace EWRES and NPDE values obtained from table with ones generated with npde.

npde_decorr_method

Pass this value to decorr.method of npde::autonpde().

presim_fn

Before simulating, apply this function to the data frame that results from joining the input data and table values. The main purpose of this argument is to provide a way to do any column renames that are required for the mrgsolve simulation (e.g., renaming a column to "TIME").

min_batch_size

To simulate EPRED and IPRED values, posterior samples are split into batches and sent as items to future *apply functions. The number of batches is chosen so that each batch has at least the number of samples specified by this argument.

Note: You may be able to tune this value to get better performance for a particular case (considering factors such as the model, targeted future backend, and machine). However, the results across runs with the same initial seed will differ if you change this value. To avoid the results varying across different machines and future backends, do not dynamically set this value based on the number of available workers.

Value

A data frame. The base data frame is the result of combining the bbr::nm_join() results for each chain submodel and collapsing across chains with point_fn. EPRED, IPRED, EWRES, and NPDE values are replaced with a simulated estimate, if requested by the corresponding argument.

Details

Messages

nm_join_bayes() and nm_join_bayes_quick() display messages from bbr::nm_join() about the data and table files being joined for the first chain. Messages for the subsequent chains are omitted to avoid flooding the console with identical output.

As with bbr::nm_join(), you can suppress these messages by setting the bbr.verbose option to FALSE.

Parallel processing

To enable parallel processing for the EPRED and IPRED simulations, configure future ahead of calling this function via future::plan().

Progress bar

The EPRED and IPRED simulations support displaying a progress bar via the progressr package. The simplest way to enable a progress bar is to wrap the nm_join_bayes() call inside a progressr::with_progress() call.