xpose.xtras (version 0.0.2)

mutate_prm: Transform parameter values in place

Description

Apply transformations to fitted parameter values.

As fitted, sometimes parameter values are not as easy to communicate, but to transform them outside of the xpose ecosystem limits some available features. To have the best experience, this function can update the parameter values that are used by xpose get_prm functions. At this time these transformations are not applied to param vars (list_vars), but that can already be done with the mutate method.

This only works for theta parameters.

All valid mutations are applied sequentially, so a double call to the2~the2^3 will result in effectively the2~the2^9, for example.

RSE values are calculated at runtime within get_prm, so they are not updated (or updatable) with this function.

Usage

mutate_prm(
  xpdb,
  ...,
  .autose = TRUE,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  .sesim = 1e+05,
  quiet
)

Value

An updated xp_xtras object with mutated parameters

Arguments

xpdb

<xp_xtras> object

...

... <dynamic-dots> One or more formulae that define transformations to parameters. RHS of formulas can be function or a value. That value can be a function call like in mutate() (the1~exp(the1)).

.autose

<logical> If a function is used for the transform then simulation is used to transform the current SE to a new SE. Precision of this transformation is dependent on .sesim. If parameter values are not assigned with a function, this option will simply scale SE to maintain the same RSE. See Details.

.problem

<numeric> Problem number to apply this relationship.

.subprob

<numeric> Problem number to apply this relationship.

.method

<numeric> Problem number to apply this relationship.

.sesim

<numeric> Length of simulated rnorm vector for .autose.

quiet

Silence extra output.

Details

Important points about covariance and correlation

Covariance and correlation parameters are adjusted when standard error (SE) values are changed directly or with .autose. When a transformation is applied as a function for the fixed effect parameter (eg, ~plogis), the resulting SE may have an unexpected scale; this is because it is now reporting the standard deviation of a transformed and potentially non-normal distribution. If the parameter were fit in the transformed scale (constrained to any appropriate bounds), it would likely have a different SE given that most covariance estimation methods (excluding non-parametric and resampling-based) will treat the constrained parameter as continuous and unconstrained.

The updates to variance-covariance values (and the correlation values, though that is mostly invariant) are applied to the entire matrices. When piped directly into get_prm, only the SE estimate is shown, but <get_file> can be used to see the complete updated variance-covariance values. This could be useful if those matrices are being used to define priors for a Bayesian model fitting, as the re-scaling of off-diagonal elements is handled automatically.

A function to transform parameters will result in a more accurate autose result. If a call (the1~exp(the)) or a value (the1~2) are used, the standard error will be simply scaled.

Examples

vismo_pomod %>%
  # Function
  mutate_prm(THETA11~exp) %>%
  # Value (se will not be scaled); plogis = inverse logit
  mutate_prm(THETA12~plogis(THETA12)) %>%
  get_prm()