optimize_multiple_testing_procedure: Optimizes multiple testing procedure of two-stage, adaptive...

In mrosenblum/AdaptiveDesignOptimizerSparseLP: Two-Stage, Two Population, Adaptive Enrichment Design Optimizer Using Sparse Linear Programming

Description

Optimizes multiple testing procedure of two-stage, adaptive enrichment design for a precomputed (e.g., using optimize_design) end-of-stage-1 decision rule.

Usage

optimize_multiple_testing_procedure(
  subpopulation.1.proportion = 0.5,
  total.alpha = 0.05 - (1e-04),
  data.generating.distributions,
  stage.1.sample.sizes,
  stage.2.sample.sizes.per.enrollment.choice,
  objective.function.weights,
  power.constraints,
  type.of.LP.solver = c("cplex", "matlab", "GLPK", "gurobi"),
  discretization.parameter = c(1, 1, 10),
  number.cores = 30,
  ncp.list = c(),
  list.of.rectangles.dec = c(),
  LP.iteration = 1,
  prior.covariance.matrix = diag(2) * 0,
  round.each.multiple.testing.procedure.rectangle.to.integer = FALSE,
  plots.to.round.simply = c(),
  rounding.threshold.H01 = 1 - 1e-10,
  rounding.threshold.H02 = 1 - 1e-10,
  rounding.threshold.H0C = 1 - 1e-10,
  power.constraint.tolerance = 0,
  LP.solver.path = c(),
  cleanup.temporary.files = TRUE
)

Arguments

subpopulation.1.proportion	Proportion of overall population in subpopulation 1. Must be between 0 and 1.
total.alpha	Familywise Type I error rate (1-sided)
data.generating.distributions	Matrix encoding data generating distributions (defined in terms of treatment effect pairs and outcome variances) used to define power constraints and objective function; each row defines the pair (Delta_1,Delta_2) of subpopulation 1 and 2 average treatment effects, followed by outcome variances for the four combinations of subpouplation (1 and 2) by study arm (0 and 1).
stage.1.sample.sizes	Vector with 2 entries representing stage 1 sample sizes for subpopulations 1 and 2, respectively
stage.2.sample.sizes.per.enrollment.choice	Matrix with number.choices.end.of.stage.1 rows and 2 columns, where the (i,j) entry represents the stage 2 sample size under enrollment choice i for subpopulation j.
objective.function.weights	Vector with length equal to number of rows of population.parameters, representing weights used to define the objective function
power.constraints	Matrix with same number of rows as population.parameters (each representing a data generating distribution) and three columns corresponding to the required power to reject (at least) H_01, H_02, H_0C, respectively.
type.of.LP.solver	"matlab", "cplex", "GLPK", or "gurobi" The linear program solve that you want to use; assumes that you have installed this already and that path is set
discretization.parameter	vector with 3 elements representing initial discretization of decision region, rejection regions, and grid representing Type I error constraints
number.cores	the number of cores available for parallelization using the parallel R package
ncp.list	list of pairs of real numbers representing the non-centrality parameters to be used in the Type I error constraints; if list is empty, then default list is used.
list.of.rectangles.dec	list of rectangles representing decision region partition, encoded as a list with each element of the list having fields $lower_boundaries (pair of real numbers representing coordinates of lower left corner of rectangle), $upper_boundaries (pair of real numbers representing upper right corner of rectangle), $allowed_decisions (subset of stage.2.sample.sizes.per.enrollment.choice representing which decisions allowed if first stage z-statistics are in corresponding rectangle; default is entire list stage.2.sample.sizes.per.enrollment.choice), $preset_decision (indicator of whether the decision probabilities are hard-coded by the user; default is 0), $d_probs (empty unless $preset_decision==1, in which case it is a vector representing the probabilities of each decision); if list.or.rectangles.dec is empty, then a default partition is used based on discretization.parameter.
LP.iteration	positive integer used in file name to store output; can be used to avoid overwriting previous computations
prior.covariance.matrix	2x2 positive semidefinite matrix representing the covariance corresponding to each component of the mixture of multivariate normals prior distribution (used only in defining the objective function); the default is the matrix of all 0's, corresponding to the prior being a mixture of point masses
round.each.multiple.testing.procedure.rectangle.to.integer	TRUE/FALSE indicator of whether to round the multiple testing proce ure to integer values and save; only can be done if the procedure is passed a decision rule (encoded in list.of.rectangles.dec) that has all probabilities set as would typically be the case in the final refinement of the original problem
plots.to.round.simply	subset of plots (one per allowed enrollment decision) for which rounding is simply based on thresholding using rounding.threshold.H01, rounding.threshold.H02, rounding.threshold.H0C
rounding.threshold.H01	threshold above which fractional solution corresponding to probability of rejecting H01 is rounded to 1
rounding.threshold.H02	threshold above which fractional solution corresponding to probability of rejecting H02 is rounded to 1
rounding.threshold.H0C	threshold above which fractional solution corresponding to probability of rejecting H0C is rounded to 1
power.constraint.tolerance	amount by which power corresponding to rounded solution is allowed to be less than power.constraints; typically set to be small, e.g., 0.01
LP.solver.path	path (i.e., directory) where LP.solver is installed; e.g., if type.of.LP.solver=="cplex" then LP.solver.path is directory where cplex is installed
cleanup.temporary.files	TRUE/FALSE indicates whether temporary files generated during problem solving process should be deleted or not after termination; set to FALSE for debugging purposes only.

Value

Nothing is returned; instead the optimized design is saved as "optimized_design<k>.rdata", where <k> is the user-defined iteration number (LP.iteration).

Output

The software computes an optimized design and saves it as "optimized_design<k>.rdata", where <k> is the user-defined iteration number (LP.iteration). E.g., if one sets LP.iteration=1, then the optimized design is saved as "optimized_design1.rdata". That file can be opened in R and contains the following 6 items: input.parameters (the inputs passed to the optimized_design function) list.of.rectangles.dec (the decision rectangle partition of R^2) list.of.rectangles.mtp (the multiple testing procedure partition of R^2) ncp.active.FWER.constraints (the active familywise Type I error constraints in the optimized design, obtained using the dual solution to the linear program) ncp.list (the complete list of familywise Type I error constraints input to the linear program solver) sln (the solution to the linear program; sln$val is the expected sample size; sln$status, if either 1 or 5, indicates that a feasible solution was found and other wise the problem was infeasible or no solution was found; sln$z is the actual solution as a vector)

Author(s)

Michael Rosenblum, Ethan Fang, Han Liu

Examples

#For demonstration purposes, the code below implements the final
# iteration, as described in Section 5.2 of the paper, for Example
# 3.2 of the paper.
#First set all problem parameters based on Example 3.2, and using
#  explicit choices of sample sizes (where n=200, sigma=1,
# Delta^min=4*qnorm(0.95)/sqrt(200)=0.465),
# as follows:
subpopulation.1.proportion=0.5;
total.alpha=0.049;
delta_min=4*qnorm(0.95)/sqrt(200);
data.generating.distributions=matrix(
  data=c(0,0,1,1,1,1,
         0,delta_min,1,1,1,1,
         delta_min,0,1,1,1,1,
         delta_min,delta_min,1,1,1,1),
  nrow=4,
  ncol=6,
  byrow=TRUE,
  dimnames=list(c(),c("Delta1","Delta2","Variance10",
                      "Variance11","Variance20","Variance21")));
stage.1.sample.sizes=c(50,50);
stage.2.sample.sizes.per.enrollment.choice= matrix(
  c(50,50,
    0,0,
    150,0,
    0,150),
  nrow=4,ncol=2,
  byrow=TRUE,
  dimnames=list(c(), c("Subpopulation1Stage2SampleSize",
                       "Subpopulation2Stage2SampleSize")));
objective.function.weights=0.25*c(1,1,1,1);
prior.covariance.matrix=diag(2);
power.constraints=matrix(c(0,0,0,
			   0,0.83,0,
			   0.83,0,0,
			   0,0,0.83),nrow=4,ncol=3,byrow=TRUE,dimnames=list(c(),
			   c("PowerH01","PowerH02","PowerH0C")));
type.of.LP.solver="cplex";
discretization.parameter=c(1,0.25,10);
number.cores=min(parallel::detectCores(), 30);
# Load list of Type I Error Constraints (encoded as ncp.list in our
# software and denoted as G in the paper) and the partition of decision
# rectangles (encoded as list.of.rectangles.dec in our software and
# denoted as A_1 in the paper).
load(system.file("examples", "example3.2final.iteration.inputs.rdata",
package = "AdaptiveDesignOptimizerSparseLP"));
# Run final iteration solving sparse linear program with above inputs

optimize_multiple_testing_procedure(
  subpopulation.1.proportion,
  total.alpha = 0.049,
  data.generating.distributions,
  stage.1.sample.sizes,
  stage.2.sample.sizes.per.enrollment.choice,
  objective.function.weights,
  power.constraints,
  type.of.LP.solver,
  discretization.parameter,
  number.cores,
  ncp.list,
  list.of.rectangles.dec,
  LP.iteration = 5,
  prior.covariance.matrix,
  round.each.multiple.testing.procedure.rectangle.to.integer = TRUE,
  plots.to.round.simply = c(1, 2),
  power.constraint.tolerance = 0.01,
  LP.solver.path = c()
)

mrosenblum/AdaptiveDesignOptimizerSparseLP documentation built on Feb. 13, 2020, 12:59 p.m.