adsasi (version 0.9.0.1)

adsasi_1d: Adaptive Sample Size Finder With One Floating Parameter

Description

This function empirically finds the relationship between sample size and a numeric parameter of interest, for a given experiental simulation scenario supplied by the user in the form of a function (most typically a clinical trial, but any experiment whose success rate increases with the number of observations can be processed). adsasi_1d will search the two-dimensional space empirically (sample size x parameter of interest), favoring exploration of low sample size regions, to find the line where power is nominal. Power is understood in a broad sense here, as a probability of success of the experiment rather than a strict statistical power.

Usage

adsasi_1d(
  simfun,
  tar_power = 0.9,
  ...,
  optivar,
  optiwin = c(min = 0, max = 1),
  optilog = FALSE,
  optiround = FALSE,
  nsims = 5000,
  verbose = FALSE,
  impNN = Inf,
  capNN = 2000,
  initiation = TRUE,
  savegraphs = FALSE,
  keepsims = FALSE,
  n_slope_coefs = 3,
  n_size_coefs = 5
)

Value

A list with 2 numbers in it : minimum sample size, named min_NN, and corresponding best parameter value, named min_optival. If keepsims=TRUE, several other objects will be appended to the list (see Note).

Arguments

simfun

(function) The user-supplied function that describes the clinical trial scenario (or similar experiment) that needs to be explored. Must have as named arguments a sample size (named NN) and an arbitrary number of design parameters (one of which will be optimized). Must return a boolean indicating whether the trial is successful or not, after performing any required computations (regressions, bootstraps) as written by the user, and never return NA.

tar_power

(single number between 0 and 1) Target power (or more broadly, probability of success). adsasi_1d will seek regions where simfun returns TRUE with a frequency of tar_power, assuming that higher sample size equals higher probability of success.

...

Additional named arguments to be passed to simfun. Some of these arguments can be functions themselves (e.g. for trying different analysis models). Any simfun argument without a default value must be specified here.

optivar

(single string) Name of the simfun argument that needs to be optimized.

optiwin

(numeric vector of size 2) Bounds of the region to be explored for values of optivar.

optilog

(boolean) Whether optivar is best explored and drawn in log scale (as in the case of a ratio) or linearly. If for example optiwin is c(0.1,10) for a ratio, graphs will be drawn with 1 as the middle value if optilog is TRUE and 5.05 is it is FALSE.

optiround

(boolean) Whether optivar needs to be rounded to the nearest integer to make sense for simfun (for example, if it is a number of centers in a cluster-randomized trial).

nsims

(single number) Number of simulations to be run across all values of optivar. After initialization, simulations are run in batches of 10% of existing simulations, until nsims is reached.

verbose

(boolean) Whether to print extra diagnostics messages throughout the run.

impNN

(single number, or infinity) Sample size that is considered impossible (either computationnally, or logistically). The simulator will exit if, after 500+ simulations, it looks like the best value is above this. In practice, is mostly useful to avoid expensive computations in situations where simfun is not written well or is prohibitively long to compute for large sample sizes.

capNN

(single number, or infinity) Maximum sample size that will be simulated. Also mostly useful to avoid expensive computations.

initiation

(boolean, or numeric matrix) Either a boolean indicating whether or not to keep the first 150 simulations for the relationship inference (those tend to be far from tar_power), or a matrix with simulation results from a previous run which the user wants enrich with more simulations (formatted exactly as produced by adsasi_1d with the same opti* arguments). See Value and Notes below for how to get this data from the output to be able to reuse it.

savegraphs

(boolean or string) Whether to save graphs on drive (vs. showing them in the console). If string, is interpreted as a typical name to be used (several graphs will be drawn, with iteration number, timestamp and .png file extension appended). The string can contain a filepath, but folders must already exist (e.g. with dir.create() from base, if automated).

keepsims

(boolean or string) Whether to keep simulations and last fit in the returned object, which by default only containe the best value.

n_slope_coefs

(single integer) Number of coefficients for the slope polynomial. The slope polynomial tries to model the relationship between optivar and the loss of power as sample size locally deviates from the (unknown) target.

n_size_coefs

(single integer) Number of coefficients for the size polynomial. The size polynomial tries to model the relationship between optivar and the target sample size. Its shape is the most useful output of the function.

Examples

# First, the user defines a function for their target situation. In this simple example, a 2-sample
# t-test with unequal allocation. The design parameter of interest will be the ratio of 
# n1 (observations in arm 1) to NN (total sample size). Note the syntax to avoid returning NAs. 
simulate_unequal_t_test = function(NN=20,ratio_n1_NN=0.5,delta=1)
 {
  n1 = round(ratio_n1_NN*NN) ; n2 = NN-n1
  yy1 = rnorm(n1) ; yy2 = rnorm(n2,delta)
  pp=NA ; try(pp <- t.test(yy1,yy2)$p.value,silent=TRUE)
  !is.na(pp) & pp<0.05
  }
simulate_unequal_t_test()
# Now we empirically find the relationship between sample size and the parameter of interest. 
# Note that we can change the delta parameter directly from the adsasi_1d call. 
# nsims should generally be much higher than in this fast-running example (>5000). 
batch=adsasi_1d(simulate_unequal_t_test,delta=1.25,optivar="ratio_n1_NN",nsims=200,keepsims=TRUE)
# Drawing the output in a different style
plot( batch[["abscissae"]],batch[["size_natural_estimate_by_optival"]]
     ,xlab="Optimization parameter",ylab="Estimated sample size",type="o",col="red"
     )
polygon( c(batch[["abscissae"]],rev(batch[["abscissae"]]))
        ,c( batch[["size_confint_higher_by_optival"]]
           ,rev(batch[["size_confint_lower_by_optival"]])
           )
        ,col="#55000088",border=NA
        )