xpose.xtras (version 0.0.2)

get_prm: Access model parameters

Description

Access model parameter estimates from an xpdb object.

Methods have been added to implement extensions. See Details.

Usage

get_prm(
  xpdb,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  digits = 4,
  transform = TRUE,
  show_all = FALSE,
  quiet
)

Value

A tibble for single problem/subprob or a named list for multiple problem|subprob.

Arguments

xpdb

An xpose_data object from which the model output file data will be extracted.

.problem

The problem to be used, by default returns the last one for each file.

.subprob

The subproblem to be used, by default returns the last one for each file.

.method

The estimation method to be used, by default returns the last one for each file

digits

The number of significant digits to be displayed.

transform

Should diagonal OMEGA and SIGMA elements be transformed to standard deviation and off diagonal elements be transformed to correlations.

show_all

Logical, whether the 0 fixed off-diagonal elements should be removed from the output.

quiet

Logical, if FALSE messages are printed to the console.

Details

When using an <xp_xtra> object, this function will add a column to the output where CV% for each diagonal element of omega is calculated. This CV% is with respect to the resulting structural parameter, so unless the default log-normal association is applicable update with add_prm_association.

For log-normal, users may prefer to use the first-order CV% (\(\sqrt{\omega^2}\)) instead of the exact. In such case, xpdb <- set_option(xpdb, cvtype="sqrt") will get that preferred form.

If a single omega parameter is associated with multiple fixed effect parameters, the cv column will be a list. For the omega row associated with multiple fixed effect parameters, there will be multiple CV values. This will be the case even if the transformation is log-normal and therefore scale-invariant, given the need for generality.

Note the approach used to calculate CV% assumes an untransformed scale for the fitted parameter value (unrelated to transform=TRUE). That means, for example, that for a logit-normal fitted parameter value, it is expected the value will be something constrained between 0 and 1, not the unbounded, continuous transformed value. The function <mutate_prm> is intended to help where that might be an issue.

References

Prybylski, J.P. Reporting Coefficient of Variation for Logit, Box-Cox and Other Non-log-normal Parameters. Clin Pharmacokinet 63, 133-135 (2024). https://doi.org/10.1007/s40262-023-01343-2

See Also

add_prm_association()

Examples

# xpose parameter table
get_prm(xpose::xpdb_ex_pk, .problem = 1)

# xpose.xtra parameter table (basically the same)
get_prm(pheno_final, .problem = 1)

# For the sake of example, even though these were all lognormal:
pheno_final %>%
  add_prm_association(CLpkg~logit(IIVCL)) %>%
  add_prm_association(Vpkg~nmboxcox(IIVV, lambda = 0.01)) %>%
  get_prm(.problem = 1)