tsT                package:adaptTest                R Documentation

_F_u_n_c_t_i_o_n _t_o _i_m_p_l_e_m_e_n_t _a_n _a_d_a_p_t_i_v_e _t_w_o-_s_t_a_g_e _t_e_s_t

_D_e_s_c_r_i_p_t_i_o_n:

     There are four key quantities for the specification of an adaptive
     two-stage test: the overall test level alpha, stopping bounds
     alpha1 <= alpha0 and the local level alpha2 of the test after the
     second stage. These quantities are interrelated through the
     overall level condition. The function 'tsT' calculates any of
     these quantities based on the others.

_U_s_a_g_e:

     tsT(typ, a = NA, a0 = NA, a1 = NA, a2 = NA)

_A_r_g_u_m_e_n_t_s:

     typ: type of test: '"b"' for Bauer and Koehne (1994), '"l"' for
          Lehmacher and Wassmer (1999), '"v"' for Vandemeulebroecke
          (2006) and '"h"' for the horizontal conditional error
          function

       a: alpha, the overall test level

      a0: alpha0, the futility stopping bound

      a1: alpha1, the efficacy stopping bound and local level of the
          test after the first stage

      a2: alpha2, the local level of the test after the second stage

_D_e_t_a_i_l_s:

     An adaptive two-stage test can be viewed as a family of decreasing
     functions f[c](p1) in the unit square. Each of these functions is
     a conditional error function, specifying the type I error
     conditional on the p-value p1 of the first stage. For example,
     f[c](p1) = min(1, c/p1) corresponds to Fisher's combination test
     (Bauer and Koehne, 1994). Based on this function family, the test
     can be put into practice by specifying the desired overall level
     alpha, stopping bounds alpha1 <= alpha0 and a parameter alpha2.
     After computing p1, the test stops with or without rejection of
     the null hypothesis if p1 <= alpha1 or p1 > alpha0, respectively.
     Otherwise, the null hypothesis is rejected if and only if p2 <=
     f[c](p1) holds for the p-value p2 of the second stage, where c is
     such that the local level of this latter test is alpha2 (e.g., c =
     c(alpha2) = exp(-chi2_{4,alpha2}/2) for Fisher's combination
     test).

     The four parameters alpha, alpha0, alpha1 and alpha2 are
     interdependent: they must satisfy the level condition 

    alpha1 + int_{alpha1}^{alpha0} cef_{alpha2}(p1) d p1 = alpha,

     where cef_{alpha2} is the conditional error function (of a
     specified family) with parameter alpha2. For example, this
     conditon translates to 

       alpha = alpha1 + c(alpha2) * (log(alpha0) - log(alpha1))

     for Fisher's combination test (assuming that c(alpha2) < alpha1;
     Bauer and Koehne, 1994). The function 'tsT' calculates any of the
     four parameters based on the remaining ones. Currently, this is
     implemented for the following four tests: Bauer and Koehne (1994),
     Lehmacher and Wassmer (1999), Vandemeulebroecke (2006), and the
     horizontal conditional error function.

_V_a_l_u_e:

     If three of the four quantities alpha, alpha0, alpha1 and alpha2
     are provided, 'tsT' returns the fourth. If only alpha and alpha0
     are provided, 'tsT' returns alpha1 under the condition alpha1 =
     alpha2 (the so-called "Pocock-type").

     If the choice of arguments is not allowed (e.g., alpha0 < alpha1)
     or when a test cannot be constructed with this choice of arguments
     (e.g., alpha0 = 1 and alpha < alpha2), 'tsT' returns 'NA'.

     IMPORTANT: When the result is (theoretically) not unique, 'tsT'
     returns the maximal alpha1, maximal alpha2 or minimal alpha0.

     In all cases, 'tsT' returns the result for the test specified by
     'typ'.

_N_o_t_e:

     The argument 'typ', and either exactly three of alpha, alpha0,
     alpha1 and alpha2, or only alpha and alpha0, must be provided to
     'tsT'.

_A_u_t_h_o_r(_s):

     Marc Vandemeulebroecke

_R_e_f_e_r_e_n_c_e_s:

     Bauer, P., Koehne, K. (1994). Evaluation of experiments with
     adaptive interim analyses. _Biometrics_ 50, 1029-1041.

     Lehmacher, W., Wassmer, G. (1999). Adaptive sample size
     calculations in group sequential trials. _Biometrics_ 55,
     1286-1290.

     Vandemeulebroecke, M. (2006). An investigation of two-stage tests.
     _Statistica Sinica_ 16, 933-951.

     Vandemeulebroecke, M. (2008). Group sequential and adaptive
     designs - a review of basic concepts and points of discussion.
     _Biometrical Journal_ 50, 541-557.

_S_e_e _A_l_s_o:

     'adaptTest' package description

_E_x_a_m_p_l_e_s:

     ## Example from Bauer and Koehne (1994): full level after final stage, alpha0 = 0.5
     alpha  <- 0.1
     alpha2 <- 0.1
     alpha0 <- 0.5
     alpha1 <- tsT(typ="b", a=alpha, a0=alpha0, a2=alpha2)
     plotCEF(typ="b", a2=alpha2, add=FALSE)
     plotBounds(alpha1, alpha0)

     ## See how similar Lehmacher and Wassmer (1999) and Vandemeulebroecke (2006) are
     alpha  <- 0.1
     alpha1 <- 0.05
     alpha0 <- 0.5
     alpha2l <- tsT(typ="l", a=alpha, a0=alpha0, a1=alpha1)
     alpha2v <- tsT(typ="v", a=alpha, a0=alpha0, a1=alpha1)
     plotCEF(typ="l", a2=alpha2l, add=FALSE)
     plotCEF(typ="v", a2=alpha2v, col="red")
     plotBounds(alpha1, alpha0)

     ## A remark about numerics
     tsT(typ="b", a=0.1, a1=0.05, a0=0.5)
     tsT(typ="b", a=0.1, a2=0.104877, a0=0.5)
     tsT(typ="b", a=0.1, a2=tsT(typ="b", a=0.1, a1=0.05, a0=0.5), a0=0.5)

     ## An example of non-uniqueness: the maximal alpha1 is returned; any smaller value would also be valid
     alpha  <- 0.05
     alpha0 <- 1
     alpha2 <- 0.05
     alpha1 <- tsT(typ="b", a=alpha, a0=alpha0, a2=alpha2)
     tsT(typ="b", a0=alpha0, a1=alpha1, a2=alpha2)
     tsT(typ="b", a0=alpha0, a1=alpha1/2, a2=alpha2)

