get_cov_matrix: Extract a parameter covariance or correlation matrix

In xpose.xtras: Extra Functionality for the 'xpose' Package

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
)

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.

Value

A symmetric numeric matrix, with parameter names as dimnames.

Examples

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

## Not run: 
xpdb_nlmixr2 <- nlmixr_example("xpdb_nlmixr2")
get_cov_matrix(xpdb_nlmixr2)

## End(Not run)

xpose.xtras documentation built on Sept. 1, 2026, 5:08 p.m.