add_prm_association {xpose.xtras}R Documentation

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.

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...)

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


[Package xpose.xtras version 0.0.2 Index]