Skip to contents

Classify likelihood profiles of an nlmixr2 fit

Source: R/profiles.R
classify_profiles.Rd

Fixes each selected population parameter at values on either side of its estimate, re-estimates all other parameters with nlmixr2extra::profileFixed(), and classifies the change in objective function value (dOFV) following Raue et al. (2009, Bioinformatics 25:1923-1929):

Usage

classify_profiles(
  fit,
  which = NULL,
  grid = NULL,
  threshold = 3.84,
  steps = c(0.1, 0.25, 0.5, 1, 2),
  flat_tol = 1,
  structural = NULL,
  map = NULL
)

Arguments

fit

An nlmixr2 fit (FOCEi or another estimation method supported by nlmixr2extra::profileFixed()).

which

Names of population parameters (thetas) to profile. By default all estimated thetas that are not residual error parameters.

grid

Optional named list of values (estimation scale) per parameter; replaces the stepwise search for that parameter.

threshold

dOFV threshold; 3.84 is the 95% point of a chi-squared distribution with one degree of freedom.

steps

Distances from the estimate, explored on each side in order.

flat_tol

dOFV below which a profile counts as flat (allows for the convergence noise of repeated estimation).

structural

Optional result of structural_identifiability().

map

Named character vector from fit parameter names to pkident parameter names, for example c(tcl = "CL", tv = "V").

Value

An object of class pkident_profiles. Use as_table() with "parameters" or "profiles".

Details

  • identifiable: dOFV exceeds threshold on both sides. An approximate profile-likelihood confidence interval is reported (interpolated on the signed-root scale; use profile(fit, method = "llp") from nlmixr2extra for a precise interval).

  • non_identifiable: dOFV exceeds the threshold on one side only (the open direction is reported), or on neither side. A profile that stays within flat_tol of its minimum is reported as flat, which suggests structural non-identifiability; otherwise it is reported as shallow.

  • unresolved: a profile fit failed.

Statements are limited to the explored range, which is reported.

Every profile fit is an upper bound of the profile likelihood: a failed or stuck re-estimation can only overstate dOFV. Each point more than flat_tol above the original fit, or above the lowest OFV found, is therefore re-estimated from the estimates of a neighbouring profile point (a warm start), and the lower value is kept. If profiling finds a lower OFV than the original fit, dOFV is measured from that lower value and the drop is reported (ofv_drop): the original fit was not at its minimum, which is common along non-identifiable directions.

By default, each side is explored by stepping away from the estimate by steps on the estimation scale, stopping once dOFV exceeds the threshold. The default steps suit log-transformed parameters (cl <- exp(tcl + ...)); for other parameters give grid.

If a structural_identifiability() result is given with map, each profile is placed next to the structural decision, which distinguishes "structurally identifiable but not determined by these data" from structural non-identifiability.

Examples

if (FALSE) { # \dontrun{
fit <- nlmixr2(one_compartment, data, est = "focei")
classify_profiles(fit, which = c("tcl", "tv"))
} # }