Feature request: tweakInits()

[billdenney]

At ACoP, someone asked if we had all the PsN features implemented. I said, "not yet." The specific request was for a function to tweak initial conditions to check for stability. I took a look at what PsN does (https://github.com/UUPharmacometrics/PsN/releases/download/v5.3.0/parallel_retries_userguide.pdf), and my read is that the most useful set of inputs would look something like the following:

tweakInits(object, n=5, tweakFrac= 0.1, tweakFixed = FALSE, keepAll = TRUE)

The arguments would be:

• object: The fit model
• n: the number of retries to perform
• tweakFrac: The fraction to modify the initial estimates (always ensuring that the new initial estimate is within the bounds)
• tweakFixed: Also tweak fixed parameters? (TRUE is yes, FALSE is no)
• keepAll: Should the full models be saved (TRUE) or just the parameter tables (FALSE)?

The output would be an object (proposed class: nlmixr2extraTweakInits) with a data.frame-like printing method, an as.data.frame() method, and a plotting method which would show all the parameter estimates and their CI for the original (blue) and the tweaked parameters (gray) with points at the estimates and lines for the CI. The data.frame would have columns for each parameter, each parameter RSE, back-transformed parameters, and the lower and upper bound of the CI.

Edit: clarified the output object

[mattfidler]

This tweaking is already built into focei but not saem

[mattfidler]

But not at this much detail. Mostly the restarting.

[billdenney]

Ah, this has a different goal than just restarting. The idea was that it is a model sensitivity check: rerun the model with different initial estimates and see if you get the same or different results.

[billdenney]

Based on an email comment from @bergsmat, I have updated the default keepAll to TRUE.

[mattfidler]

Should we call it parallelRetries() instead, since that is what PsN uses? I think it could be confusing, though.

[mattfidler]

The other possibility is to allow custom initial conditions, like their -rawres_input value. This could be used in log-likelihood profiling as well...

[mattfidler]

Another option to include is the seed. They should also be drawn before the estimation procedure because each sets the seed to a value.

[billdenney]

There are several tools that we are circling around. One is the PsN parallel retries and another is nonmemica::tweak.inits().
Both do similar but not quite identical things. The goal of parallelRetries() as far as I can tell is to focus on getting a better model fit when it's not converging. Maybe it should have both names with parallelRetries() as a wrapper for tweakInits()?

[bergsmat]

I agree, I think. Perhaps it is good to distinguish what is being done from why it is being done. Creating one or more deviations from initial conditions could be used to search for a nearby solution, or to test that a found solution is at least locally robust. If the exact same thing is going on underneath, no harm in "skinning" it two different ways, especially if you have a broad user group that will be familiar with a particular invocation. That said, I expect most of us will quickly discover whatever interface you supply, and recognize its applicability to our particular use cases. I would lean towards keeping the interface simple and using names that feel intuitive to you.