optimizeTrial: Use simulated annealing to search over a space of trial...
In aaronjfisher/designOptim: Design optimizer

Description Usage Arguments Details Value References Examples

We aim to minimize an objective function which we aim to minimize is the expected sample size, with additive penalties on power. If power for any alternative hypothesis is less than a supplied threshold (see cases), a penalty will be applied.

optimizeTrial(args_list_init, args_list_fixed, cases, max_K = 20,
  objective_fun = min_E_SS_power_constraints, logit_search = c(),
  local_n_search = FALSE, max_n_local = NULL, min_n_local = NULL,
  time_limit_optim_cpu = NA, time_limit_optim_elapsed = NA,
  max_n_feas = NULL, optim_method = "SANN", maxit = 1000, trial_method,
  parscale_ratio_N = 100, parscale_ratio_K = 1, parscale_ratio_logit = 3,
  build_precision = TRUE, print_interval = NULL, npoints_sqrt = 25,
  stage1_feasible = NULL, returnFullPath = FALSE,
  verbose = is.null(print_interval), print_obj = FALSE)

`args_list_init`	a list containing a subset of the arguments for the functions `getEffBounds` and `simTrial` (or comparable functions, see `trial_method argument`). This is the subset of arguments over which we will search when trying to minimize the objective function. The values supplied in `args_list_init` form the initial values at which we start the search. Elements of this list must be vectors.
`args_list_fixed`	a subset of arguments for the functions `getEffBounds` and `simTrial` (or comparable functions, see `trial_method argument`) which we will not search over. Instead, these arguments will remain fixed at the user-specified values. Arguments not specified will be set to their defaults. Elements of this list must be vectors.
`cases`	a list of lists describing power constraints, and prior distribution of treatment effects over which to calculate the expected sample size (or duration). List elements are individually passed to `objective_fun` for evaluation (via `get_case_perf_obj`).
`max_K`	an upper limit for the number of stages for the trial. `optimizeTrial` will not search for trials with more stages than this.
`objective_fun`	objective function to minimize. This depends on the evaluation of the current proposed design at each element of `cases`. Pre-set options that can be used are `min_E_SS_power_constraints` and `min_E_dur_power_constraints`. If a custom objective function is supplied here instead, it must be able to run in the context of the `get_case_perf_obj` function, and give output in the same format as that of `min_E_SS_power_constraints`.
`logit_search`	a list of parameters for which optim will search in the logit space. This can include parameters which are bounded to the range (0,1).
`local_n_search`	[DEPRECATED] (logical) whether a search over n_total should be done at each iteration of optim. This had previously generated the output `local_search_calls`.
`max_n_local`	[DEPRECATED] largest sample size for searches within iterations of optimization. Especially useful to set for optimizing a 1-stage design.
`min_n_local`	[DEPRECATED] smallest sample size for searches within iterations of optimization. Especially useful to set for optimizing a 1-stage design.
`time_limit_optim_cpu`	used to set a session time limit (see `setSessionTimeLimit`).
`time_limit_optim_elapsed`	used to set a session time limit (see `setSessionTimeLimit`).
`max_n_feas`	largest total sample size to consider when checking feasibility
`optim_method`	passed to `optim`.
`maxit`	passed to `optim`. Tells the number of optimization iterations. For simulated annealing, this is the same as the number of function calls.
`trial_method`	the type of trial to run. 'cov' for covariance-based, 'MB' for Maurer Bretz (2013).
`parscale_ratio_N`	used to create the `parscale` argument passed to `optim`. Tells the change in sample size that is comparable to a unit change in other parameters.
`parscale_ratio_K`	used to create the `parscale` argument passed to `optim`. Tells the change in the number of stages that is comparable to a unit change in other parameters.
`parscale_ratio_logit`	used to create the `parscale` argument passed to `optim`. For any parameter where do search for optimal values on the logit space, this tells the unit change that is comparable to a unit change in other parameters.
`build_precision`	if TRUE, the search will start by making approximate calculations for the efficacy boundaries, and will increase the precision of these efficacy boundary calculations as the search progresses.
`print_interval`	if set to `NULL`, no intermediate results will be reported. If set to a positive integer, this integer tells the number of simulated annealing steps to run in between results being printed to the console. The last number printed in each line of results is best objective function yet found. This report is a more detailed version of the results generally reported by `optim`, if `control$trace=1`.
`npoints_sqrt`	passed to `feasibility_check` to see if it is indeed possibly to have a trial at this sample size that meets the power constraints. If not, no optimization is performed.
`stage1_feasible`	output from `min_n_feasible`, if pre-calculated. If supplied, trial feasibility will be assumed.
`returnFullPath`	(logical) tells whether the entire history of the search should be returned as well.
`verbose`	(logical) should progress be printed via `message`.
`print_obj`	(logical) In progress reports, should the objective function be printed rather than just the interpretable, unpenalized expected sample size.

The argument trial_method determines which type of trial should be performed ('cov' or 'MB'). Based on this, the relevant trial parameters to be optimized should be listed in args_list_init. The parameters to hold fixed should be listed in args_list_fixed.

The cases argument should be a list of cases in which power, expected sample size and/or expected duration should be calculated. Internally, at each iteration of the search, the get_case_perf_obj function is used to evaluate the trial.

A list of results with

`soln`	the best design found during optimization
`performance_crossvalidated`	The solution found by optim may have low sample size or duration only due to Monte-Carlo error in calculating trial performance. To counter this potential bias, we recalculate the performance of the design returned by our optimization, and return the results in `performance_crossvalidated`.
`obj_final_crossvalidated`	The objective function value of the design from optim. Like `performance_crossvalidated`, this value is recalculated after the optimization procedure.
`optim_results`	output from `optim`
`obj_penalized_trajectory`	Each evaluation of the objective function.
`fullPath`	design and results from each iteration of the optimization
`time_optimized`	time taken for optimization procedure
`stage1_feasible`	output from `min_n_feasible`
`feasible`	[DEPRECATED]
`optim_iterations`	Number of iterations performed
`local_search_calls`	[DEPRECATED]

Maurer, W. and F. Bretz (2013). Multiple testing in group sequential trials using graphical approaches. Statistics in Biopharmaceutical Research.

## Not run: 



## Generate example inputs
set.seed(0)
bound_style <- 'unstructured'
trial_method <- 'cov'
inputsMISTIE <- getExampleInputsMISTIE(iter=50, bound_style=bound_style, trial_method=trial_method)
inputsMISTIE$npoints_sqrt <- 9 # set to low resolution for example search for 1-stage reference trial
str(inputsMISTIE,1) # list of inputs



## Optimize adaptive trial
optimized <- do.call(optimizeTrial,inputsMISTIE) #~ 4-7 minutes


## Visualize results for approximately optimized trial
soln <- optimized$soln

bounds<-getBoundsFromOptimSoln(
  soln = soln,
  case = inputsMISTIE$cases[[1]],
  trial_method = trial_method
  )
# If calculation of efficacy boundary is unstable, particularly in
# later stages, increase soln$maxpts or decrease soln$abseps
# and recompute eff_bounds


matplot(x=cumsum(soln$n_per_stage),
  y=data.frame(bounds$eff_bounds),type='o',pch=1:3,lty=1:3,
  ylim=range(unlist(bounds)),
  ylab='Boundary (z-scale)',
  xlab='Cumulative number with outcome observed',
  col='blue', main='Trial decision boundaries')
matlines(x=cumsum(soln$n_per_stage)[(1:soln$num_stages-1)],
  y=bounds$fut_bounds[(1:soln$num_stages-1),],
  col='red',type='o',pch=1:3,lty=1:3)
legend('bottomright',
  c('H01 Eff','H02 Eff', 'H0C Eff','H01 Fut','H02 Fut', 'H0C Fut'),
  col=rep(c('blue','red'),each=3),
  pch=rep(1:3,times=2),lty=rep(1:3,times=2))



## End(Not run)