sim.dp.byf2: Simulate Dissolution Profiles by f2 Values
In bootf2: Simulation and Comparison of Dissolution Profiles

Description Usage Arguments Details Value Examples

Given any mean dissolution profile dp, this function will simulate a mean dissolution profile such that when the newly simulated profile is compared to dp, the calculated f2 will be equal to the predefined target f2 value.

sim.dp.byf2(tp, dp, target.f2, seed = NULL, min.points = 3L,
            regulation = c("EMA", "FDA", "WHO", "Canada", "ANVISA"),
            model = c("Weibull", "first-order"), digits = 2L,
            max.disso = 100, message = FALSE, both.TR.85 = FALSE,
            time.unit = c("min", "h"), plot = TRUE, sim.dp.out,
            sim.target = c("ref.pop", "ref.median", "ref.mean"),
            model.par.cv = 50, fix.fmax.cv = 0, random.factor = 3)

`tp, dp`	Numeric vector of time points `tp` and the mean dissolution profiles `dp`.
`target.f2`	Numeric value of target f2. It can be a single value, or a vector of two values that represent the lower and upper limit of target f2 value. See Details.
`seed`	Integer seed value for reproducibility. If missing, a random seed will be generated for reproducibility purpose.
`min.points`	An integer indicating the minimum time points to be used to calculate f2. The default value 3 should be used for conventional f2 calculation. See Details. @seealso `calcf2()`.
`regulation`	Character strings indicating regulatory guidelines. @seealso `calcf2()` for the discussion of those guidelines.
`model`	Character strings of model names. Currently only `"Weibull"` and `"first-order"` models are supported. @seealso `sim.dp()` for the description of models.
`digits`	An integer indicating the decimal points for the output.
`max.disso`	Numeric value for the maximum possible dissolution. In theory, the maximum dissolution is 100%, but in practice, it is not uncommon to see higher values, such as 105%, or much lower values, especially for products with low solubility.
`message`	Logical. If `TRUE`, basic information of the simulation will be printed on screen.
`both.TR.85`	Logical. If `TRUE`, and if `regulation = "FDA"`, all measurements up to the time points at which both test and reference products dissolve more than 85% will be used to calculate f2. This is the conventional, but incorrect, interpretation of the US FDA rule. Therefore, the argument should only be set to `TRUE` for validation purpose such as comparing the results from old literature that use the wrong interpretation to calculate f2. @seealso `calcf2()` for detailed discussion.
`time.unit`	Character strings indicating the unit of time. It should be either `"min"` for minute or `"h"` for hour. It is mainly used for checking CV rules and making plot. See Regulation in Details. @seealso `calcf2()`.
`plot`	Logical. If `TRUE`, a a dissolution versus time plot will be included in the output.
`sim.dp.out`	Output of function `sim.dp()`. If this argument is supplied by the user, then `tp/dp`, `regulation`, `model`, `max.disso`, and `time.unit` will be ignored, if they are provided by the user, since all those arguments are included in `sim.dp.out`.
`sim.target`	Character strings indicating to which target profile should the newly simulated profile be compared for the calculation of f2. This argument is only applicable when `sim.dp.out` is provided. See Details.
`model.par.cv, fix.fmax.cv`	Numeric values expressed as percentages used for random generation of model parameters and fmax when optimization algorithm is not used, i.e., when `target.f2` is a vector of two numbers. See Details.
`random.factor`	Numeric value used for random generation of model parameters when optimization algorithm is used, i.e., when `target.f2` is a single number. See Details.

The main principle of the function is as follows:

For any given mean dissolution profile dp, fit a suitable mathematical model and obtain model parameters.
- No precise fitting is required since those parameters will be served as initial value for further model fitting.
- If sim.dp.out, the output of the function sim.dp(), is available, no initial fitting is necessary as model parameters can be read directly from the output, unless multivariate normal distribution approach was used in sim.dp(). In such case, initial model fitting will be done.
Find a suitable model parameters and simulate a new dissolution profile, comparing the new profile to the provided reference profile dp by calculating f2. If the the obtained f2 is equal to, or within the lower and upper limit of, the target.f2, then the function will output the obtained model parameters and the new profile.

There are two approaches used to find the suitable model parameters:

If target.f2 is a single value, optimization algorithm will be used and the newly simulated dissolution profile will have f2 equal to target.f2 when compared to dp (within numeric precision defined by the tolerance).
If target.f2 is a vector of two numbers representing the lower and upper limit of target f2 value, such as target.f2 = c(lower, upper), then dissolution will be obtained by random searching and the calculated f2 will be within the range of lower and upper.

For example, you can set target.f2 = c(54.95, 55.04) to have target f2 of 55. Since f2 should be normally reported without decimal, in practice, this precision is enough. You might be able to do with c(54.99, 55.01) if you really need more precision. However, the narrower the range, the longer it takes the function to run. With narrow range such as c(54.999, 55.001), it is likely the program will fail. In such case, provide single value to use optimization algorithm.

Arguments model.par.cv, fix.fmax.cv, and random.factor are certain numeric values used to better control the random generation of model parameters. The default values should work in most scenarios. Those values should be changed only when the function failed to return any value. Read vignette of the function (vignette("sim.dp.byf2", package = "bootf2")) for more details.

The data frame sim.summary in sim.dp.out, the output of function sim.dp(), contains dp, the population profile, and sim.mean and sim.median, the mean and median profiles calculated with n.units of simulated individual profiles. All these three profiles could be used as the target profile that the newly simulated profile will be compare to. Argument sim.target defines which of the three will be used: ref.pop, ref.mean, and ref.median correspond to dp, sim.mean and sim.median, respectively.

A list of 2 components: a data frame of model parameters and a data frame of mean dissolution profile generated using the said model parameters. The output can be passed to function sim.dp() to further simulate multiple individual profiles.

tp <- c(5, 10, 15, 20, 30, 45, 60)

mod.par.r <- list(fmax = 100, fmax.cv = 2, tlag = 0, tlag.cv = 0,
                  mdt = 25, mdt.cv = 4, beta = 2.1, beta.cv = 3)

d.r <- sim.dp(tp, model.par = mod.par.r, seed = 100, n.units = 120L,
              plot = FALSE)

model.par1 <- sim.dp.byf2(sim.dp.out = d.r, target.f2 = 60, seed = 123)
model.par2 <- sim.dp.byf2(sim.dp.out = d.r, target.f2 = c(59.95, 60.04),
                          seed = 123)