add_prm_association: Describe parameter associations

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

Describe parameter associations

Description

The relationship between structural parameters and omega parameters can be described. This is useful if it deviates from the typical log-normal.

Default transformations are those that are built into pmxcv, but see examples for how associations can be described for other relationships.

Usage

add_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)

drop_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)

Arguments

xpdb	<xp_xtras> object
...	... <dynamic-dots> One or more formulas that define associations between parameters. One list of formulas can also be used, but a warning is generated. For drop_prm_association, these dots should be selectors for which associations will be dropped (⁠the2, the3,...⁠). Fixed effect selectors only will work.
.problem	<numeric> Problem number to apply this relationship.
.subprob	<numeric> Problem number to apply this relationship.
.method	<numeric> Problem number to apply this relationship.
quiet	Silence extra output.

Details

At time of writing, the built-in distributions for pmxcv are below. Those marked with an asterisk require a fixed effect parameter to calculate CV.

• log typical log-normal. Optional exact parameter (if TRUE, default, will not calculate with integration); this is unrelated to the cvtype option. Note, if cvtype is set to "sqrt", log-normal gte_prm CVs will use the square root, not any integration or analytical estimate, regardless of how this association is specified..

• logexp* modified log-normal log(1+X)

• logit* logit-normal

• arcsin* arcsine-transform

• nmboxcox* Box-Cox transform as typically implemented in pharmacometrics. Requires a lambda parameter.

To pass a custom parameter, use custom transform, and pass pdist and qdist to that transform. See Examples.

Reminder about qdist and pdist: Consider that qlogis transforms a proportion to a continuous, unbounded number; it is the logit transform. The pdist function converts a continuous, unbounded number to a proportion; it is the inverse logit transform. Other R stats functions work similarly, and as such functions used as qdist and pdist values are expected to act similarly.

Note that the functions used in describing associations are not real functions, it is just the syntax for this application. Based on examples, be mindful of where positional arguments would acceptable and where named arguments are required. Care has been given to provide a modest amount of flexibility with informative errors for fragile points, but not every error can be anticipated. If this function or downstream results from it seem wrong, the association syntax should be scrutinized. These "functions" are not processed like in mutate_prm, so (eg) the2 will not be substituted for the value of the2; if lambda is a fitted value (like the2), in that edge case the value of the2 should be written explicitly in the association formula, and if any mutate_prm changes the2 then users should be mindful of the new association needed. This may be updated in the future.

Format for associations is: LHS~fun(OMEGA, args...)

• LHS: Selector for a fixed effect parameter. Can be ⁠the{m}⁠ (eg, the1), {name} (eg, THETA1) or {label} (eg, TVCL). These should not be quoted. Multiple associations can be defined at once with +. Cannot be empty.

• RHS: Should be a simple call to only one function, which should be custom or one of the built-in distributions or custom(...). A lot of things can look like simple calls, so may not break immediately; keep to the described format and everything should be fine.

• RHS OMEGA: Selector for omega variable. Similar rules to the fixed effect selector. Can be ⁠ome{m}⁠, {name} or {label}, limited to diagonal elements. Should not be quoted. OMEGA is not a named argument (OMEGA={selector} should not be considered valid); whatever is used as the first argument to the "function" will be considered an OMEGA selector. NOTE, if selecting an OMEGA parameter by name (eg, OMEGA(2,2)), backticks (eg `OMEGA(2,2)`) must be used or else the selection will throw an error.

• RHS args: Applies when the distribution has extra arguments. If these are limited to 1, can be passed by position (eg, lambda for nmboxcox and exact for log). For custom(), qdist, pdist and any arguments needed to pass to them should be named.

For the nmboxcox transformation, a lambda value (especially negative ones) may not work well with the integration-based CV estimation. This may occur even if the lambda is fitted and stable in that fitting, but it cannot be predicted which ones will be affected. This note is intended to forewarn that this might happen.

Value

An updated xp_xtras object

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

dist.intcv

Examples

pheno_base %>%
   add_prm_association(the1~log(IIVCL),V~log(IIVV)) %>%
   get_prm() # get_prm is the only way to see the effect of associations

# These values are not fitted as logit-normal, but
# just to illustrate:
pheno_final %>%
   add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) %>%
   get_prm()

# ... same for Box-Cox
pheno_base %>%
   add_prm_association(V~nmboxcox(IIVV, lambda=0.5)) %>%
   # Naming the argument is optional
   add_prm_association(CL~nmboxcox(IIVCL, -0.1)) %>%
   get_prm()

# A 'custom' use-case is when logexp, log(1+X), is
# desired but 1 is too large.
# Again, for this example, treating this like it applies here.
pheno_base %>%
  add_prm_association(V~custom(IIVV, qdist=function(x) log(0.001+x),
        pdist=function(x) exp(x)-0.001)) %>%
   get_prm()

# Dropping association is easy
bad_assoc <- pheno_final %>%
   add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV))
bad_assoc

xpose.xtras documentation built on Aug. 23, 2025, 9:07 a.m.