xpose.xtras (version 0.2.2)

get_cov_matrix: Extract a parameter covariance or correlation matrix

Description

Pulls the uncertainty (covariance step) matrix for estimated parameters, with built-in support for nonmem (via the .cov/.cor output tables) and nlmixr2 (via the fit object's covariance matrix) models. This is what feeds cormat(), but is exported separately since it may be useful on its own (eg, for programmatic checks on parameter colinearity).

Usage

get_cov_matrix(
  xpdb,
  type = c("correlation", "covariance"),
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  drop_fixed = TRUE,
  quiet
)

Value

A symmetric numeric matrix, with parameter names as dimnames.

Arguments

xpdb

<xp_xtras> or <xpose_data> object

type

<character> Either "correlation" (default) or "covariance"

.problem

<numeric> Problem number to use. Uses the xpose default if not provided. Ignored for nlmixr2 models.

.subprob

<numeric> Subproblem number to use. Uses the xpose default if not provided. Ignored for nlmixr2 models.

.method

<character> Method to use. Uses the xpose default if not provided. Ignored for nlmixr2 models.

drop_fixed

<logical> Drop fixed (or otherwise not estimated) parameters from the matrix. See Details.

quiet

<logical> Silence extra debugging output

Details

For nonmem models, the matrix is built from the .cor/.cov output tables produced by the $COV step. NONMEM includes fixed-effect parameters in these tables as placeholder zeros (since no uncertainty is estimated for them); drop_fixed (the default) removes them.

For nlmixr2 models, uncertainty is always calculated for fixed-effect (theta) parameters; whether it's also calculated for random-effect (omega) diagonal (variance) elements depends on the nlmixr2est version and fit settings -- when present, those rows/columns are named "om.<eta name>" to distinguish them from the point estimates returned by get_prm(). drop_fixed has no effect here, since parameters without a standard error are already excluded from the fit's covariance matrix rather than represented as placeholder zeros.

In both cases, if the covariance step was not run, or did not complete successfully, an informative error is raised rather than returning partial or placeholder data.

Examples

get_cov_matrix(xpdb_x)
get_cov_matrix(xpdb_x, type = "covariance")

if (FALSE) {
xpdb_nlmixr2 <- nlmixr_example("xpdb_nlmixr2")
get_cov_matrix(xpdb_nlmixr2)
}