ICAOD (version 1.0.1)

multiple: Locally Multiple Objective Optimal Designs for the 4-Parameter Hill Model

Description

The 4-parameter Hill model is of the form $$f(D) = c + \frac{(d-c)(\frac{D}{a})^b}{1+(\frac{D}{a})^b} + \epsilon,$$ where \(\epsilon \sim N(0, \sigma^2)\), \(D\) is the dose level and the predictor, \(a\) is the ED50, \(d\) is the upper limit of response, \(c\) is the lower limit of response and \(b\) denotes the Hill constant that control the flexibility in the slope of the response curve. Sometimes, the Hill model is re-parameterized and written as $$f(x) = \frac{\theta_1}{1 + exp(\theta_2 x + \theta_3)} + \theta_4,$$ where \(\theta_1 = d - c\), \(\theta_2 = - b\), \(\theta_3 = b\log(a)\), \(\theta_4 = c\), \(\theta_1 > 0\), \(\theta_2 \neq 0\), and \(-\infty < ED50 < \infty\), where \(x = log(D) \in [-M, M]\) for some sufficiently large value of \(M\). The new form is sometimes called 4-parameter logistic model. The function multiple finds locally multiple-objective optimal designs for estimating the model parameters, the ED50, and the MED, simultaneously. For more details, see Hyun and Wong (2015).

Usage

multiple(
  minDose,
  maxDose,
  iter,
  k,
  inipars,
  Hill_par = TRUE,
  delta,
  lambda,
  fimfunc = NULL,
  ICA.control = list(),
  sens.control = list(),
  initial = NULL,
  tol = sqrt(.Machine$double.xmin),
  x = NULL
)

Arguments

minDose

Minimum dose \(D\). For the 4-parameter logistic model, i.e. when Hill_par = FALSE, it is the minimum of \(log(D)\).

maxDose

Maximum dose \(D\). For the 4-parameter logistic model, i.e. when Hill_par = FALSE, it is the maximum of \(log(D)\).

iter

Maximum number of iterations.

k

Number of design points. Must be at least equal to the number of model parameters to avoid singularity of the FIM.

inipars

A vector of initial estimates for the vector of parameters \((a, b, c, d)\). For the 4-parameter logistic model, i.e. when Hill_par = FALSE, it is a vector of initial estimates for \((\theta_1, \theta_2,\theta_3, \theta_4)\).

Hill_par

Hill model parameterization? Defaults to TRUE.

delta

Predetermined meaningful value of the minimum effective dose MED. When \(\delta < 0 \), then \(\theta_2 > 0\) or when \(\delta > 0\), then \(\theta_2 < 0\).

lambda

A vector of relative importance of each of the three criteria, i.e. \(\lambda = (\lambda_1, \lambda_2, \lambda_3)\). Here \(0 < \lambda_i < 1\) and s \(\sum \lambda_i = 1\).

fimfunc

A function. Returns the FIM as a matrix. Required when formula is missing. See 'Details' of minimax.

ICA.control

ICA control parameters. For details, see ICA.control.

sens.control

Control Parameters for Calculating the ELB. For details, see sens.control.

initial

A matrix of the initial design points and weights that will be inserted into the initial solutions (countries) of the algorithm. Every row is a design, i.e. a concatenation of x and w. Will be coerced to a matrix if necessary. See 'Details' of minimax.

tol

Tolerance for finding the general inverse of the Fisher information matrix. Defaults to .Machine$double.xmin.

x

A vector of candidate design (support) points. When is not set to NULL (default), the algorithm only finds the optimal weights for the candidate points in x. Should be set when the user has a finite number of candidate design points and the purpose is to find the optimal weight for each of them (when zero, they will be excluded from the design). For design points with more than one dimension, see 'Details' of sensminimax.

Value

an object of class minimax that is a list including three sub-lists:

arg

A list of design and algorithm parameters.

evol

A list of length equal to the number of iterations that stores the information about the best design (design with least criterion value) of each iteration. evol[[iter]] contains:

iter		Iteration number.
x		Design points.
w		Design weights.
min_cost		Value of the criterion for the best imperialist (design).
mean_cost		Mean of the criterion values of all the imperialists.
sens		An object of class 'sensminimax'. See below.
param		Vector of parameters.

empires

A list of all the empires of the last iteration.

alg

A list with following information:

nfeval		Number of function evaluations. It does not count the function evaluations from checking the general equivalence theorem.
nlocal		Number of successful local searches.
nrevol		Number of successful revolutions.
nimprove		Number of successful movements toward the imperialists in the assimilation step.
convergence		Stopped by 'maxiter' or 'equivalence'?

method

A type of optimal designs used.

design

Design points and weights at the final iteration.

out

A data frame of design points, weights, value of the criterion for the best imperialist (min_cost), and Mean of the criterion values of all the imperialistsat each iteration (mean_cost).

The list sens contains information about the design verification by the general equivalence theorem. See sensminimax for more details. It is given every ICA.control$checkfreq iterations and also the last iteration if ICA.control$checkfreq >= 0. Otherwise, NULL.

param is a vector of parameters that is the global minimum of the minimax criterion or the global maximum of the standardized maximin criterion over the parameter space, given the current x, w.

Details

When \(\lambda_1 > 0\), then the number of support points k must at least be four to avoid singularity of the Fisher information matrix.

One can adjust the tuning parameters in ICA.control to set a stopping rule based on the general equivalence theorem. See 'Examples' below.

References

Hyun, S. W., and Wong, W. K. (2015). Multiple-Objective Optimal Designs for Studying the Dose Response Function and Interesting Dose Levels. The international journal of biostatistics, 11(2), 253-271.

See Also

sensmultiple

Examples

# NOT RUN {
# All the examples are available in Hyun and Wong (2015)

#################################
#  4-parameter logistic model
# Example 1, Table 3
#################################
lam <- c(0.05, 0.05, .90)
# Initial estimates are derived from Table 1
# See how the stopping rules are set via 'stop_rul', checkfreq' and 'stoptol'
Theta1 <- c(1.563, 1.790, 8.442, 0.137)
res1 <- multiple(minDose = log(.001), maxDose = log(1000),
                 inipars = Theta1, k = 4, lambda = lam, delta = -1,
                 Hill_par = FALSE,
                 iter = 1,
                 ICA.control = list(rseed = 1366, ncount = 100,
                                    stop_rule = "equivalence",
                                    checkfreq = 100, stoptol = .95))
# }
# NOT RUN {
res1 <- update(res1, 1000)
# stops at iteration 101
# }
# NOT RUN {
#################################
#  4-parameter Hill model
#################################
## initial estimates for the parameters of Hill model:
a <- 0.008949  # ED50
b <- -1.79 # Hill constant
c <- 0.137 # lower limit
d <- 1.7 # upper limit
# D belongs to c(.001, 1000) ## dose in mg
## the vector of Hill parameters are now c(a, b, c, d)
# }
# NOT RUN {
res2 <- multiple(minDose = .001, maxDose = 1000,
                 inipars =  c(a, b, c, d),
                 Hill_par = TRUE, k = 4, lambda = lam,
                 delta = -1, iter = 1000,
                 ICA.control = list(rseed = 1366, ncount = 100,
                                    stop_rule = "equivalence",
                                    checkfreq = 100, stoptol = .95))
# stops at iteration 100
# }
# NOT RUN {


# use x argument to provide fix number of  dose levels.
# In this case, the optimization is only over weights
# }
# NOT RUN {
res3 <- multiple(minDose = log(.001), maxDose = log(1000),
                 inipars = Theta1, k = 4, lambda = lam, delta = -1,
                 iter = 300,
                 Hill_par = FALSE,
                 x = c(-6.90, -4.66, -3.93, 3.61),
                 ICA.control = list(rseed = 1366))
res3$evol[[300]]$w
# if the user provide the desugn points via x, there is no guarantee
#   that the resulted design is optimal. It only provides the optimal weights given
#   the x points of the design.
plot(res3)
# }
# NOT RUN {
# }