spower                 package:Hmisc                 R Documentation

_S_i_m_u_l_a_t_e _P_o_w_e_r _o_f _2-_S_a_m_p_l_e _T_e_s_t _f_o_r _S_u_r_v_i_v_a_l _u_n_d_e_r _C_o_m_p_l_e_x _C_o_n_d_i_t_i_o_n_s

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

     Given functions to generate random variables for survival times
     and censoring times, 'spower' simulates the power of a user-given
     2-sample test for censored data.  By default, the logrank (Cox
     2-sample) test is used, and a 'logrank' function for comparing 2
     groups is provided.  For composing S-Plus functions to generate
     random survival times under complex conditions, the 'Quantile2'
     function allows the user to specify the intervention:control
     hazard ratio as a function of time, the probability of a control
     subject actually receiving the intervention (dropin) as a function
     of time, and the probability that an intervention subject receives
     only the control agent as a function of time (non-compliance,
     dropout).  'Quantile2' returns a function that generates either
     control or intervention uncensored survival times subject to
     non-constant treatment effect, dropin, and dropout.  There is a
     'plot' method for plotting the results of 'Quantile2', which will
     aid in understanding the effects of the two types of
     non-compliance and non-constant treatment effects.  'Quantile2'
     assumes that the hazard function for either treatment group is a
     mixture of the control and intervention hazard functions, with
     mixing proportions defined by the dropin and dropout
     probabilities.  It computes hazards and survival distributions by
     numerical differentiation and integration using a grid of (by
     default) 7500 equally-spaced time points.

     The 'logrank' function is intended to be used with 'spower' but it
     can be used by itself as long as the 'group' variable has only the
     values '1' and '2' and there are no missing data.  It returns the
     1 degree of freedom chi-square statistic.

     The 'Weibull2' function accepts as input two vectors, one
     containing two times and one containing two survival
     probabilities, and it solves for the scale and shape parameters of
     the Weibull distribution ('S(t)=exp(-alpha*t^ gamma)') which will
     yield those estimates.  It creates an S-Plus function to evaluate
     survival probabilities from this Weibull distribution.  'Weibull2'
     is useful in creating functions to pass as the first argument to
     'Quantile2'.

     The 'Lognorm2' and 'Gompertz2' functions are similar to 'Weibull2'
     except that they produce survival functions for the log-normal and
     Gompertz distributions.

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

     spower(rcontrol, rinterv, rcens, nc, ni, 
            test=logrank, nsim=500, alpha=0.05, pr=TRUE)

     Quantile2(scontrol, hratio, 
               dropin=function(times)0, dropout=function(times)0,
               m=7500, tmax, qtmax=.001, mplot=200, pr=TRUE, ...)

     ## S3 method for class 'Quantile2':
     print(x, ...)

     ## S3 method for class 'Quantile2':
     plot(x, 
          what=c('survival','hazard','both','drop','hratio','all'),
          dropsep=FALSE, lty=1:4, col=1, xlim, ylim=NULL,
          label.curves=NULL, ...)

     logrank(S, group)

     Gompertz2(times, surv)
     Lognorm2(times, surv)
     Weibull2(times, surv)

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

rcontrol: a function of 'n' which returns 'n' random uncensored failure
          times for the control group.  'spower' assumes that
          non-compliance (dropin) has been taken into account by this
          function. 

 rinterv: similar to 'rcontrol' but for the intervention group 

   rcens: a function of 'n' which returns 'n' random censoring times. 
          It is assumed that both treatment groups have the same
          censoring distribution. 

      nc: number of subjects in the control group 

      ni: number in the intervention group 

scontrol: a function of a time vector which returns the survival
          probabilities for the control group at those times assuming
          that all patients are compliant 

  hratio: a function of time which specifies the intervention:control
          hazard ratio (treatment effect) 

       x: an object of class '"Quantile2"' created by 'Quantile2' 

       S: a 'Surv' object or other two-column matrix for right-censored
          survival times 

   group: group indicators have length equal to the number of rows in
          'S'.  Only values allowed are 1 and 2. 

   times: a vector of two times 

    surv: a vector of two survival probabilities 

    test: any function of a 'Surv' object and a grouping variable which
          computes a chi-square for a two-sample censored data test. 
          The default is 'logrank'. 

    nsim: number of simulations to perform (default=500) 

   alpha: type I error (default=.05) 

      pr: set to 'FALSE' to cause 'spower' to suppress progress notes
          for simulations. Set to 'FALSE' to prevent 'Quantile2' from
          printing 'tmax' when it calculates 'tmax'. 

  dropin: a function of time specifying the probability that a control
          subject actually becomes an intervention subject at the
          corresponding time 

 dropout: a function of time specifying the probability of an
          intervention subject dropping out to control conditions 

       m: number of time points used for approximating functions
          (default is 7500) 

    tmax: maximum time point to use in the grid of 'm' times.  Default
          is the time such that 'scontrol(time)' is 'qtmax'. 

   qtmax: survival probability corresponding to the last time point
          used for approximating survival and hazard functions. 
          Default is '.001'.  For 'qtmax' of the time for which a
          simulated time is needed which corresponds to a survival
          probability of less than 'qtmax', the simulated value will be
          'tmax'. 

   mplot: number of points used for approximating functions for use in
          plotting (default is 200 equally spaced points) 

     ...: optional arguments passed to the 'scontrol' function when
          it's evaluated by 'Quantile2' 

    what: a single character constant (may be abbreviated) specifying
          which functions to plot.  The default is '"both"' meaning
          both survival and hazard functions.  Specify 'what="drop"' to
          just plot the dropin and dropout functions, 'what="hratio"'
          to plot the hazard ratio functions, or '"all"' to make 4
          separate plots showing all functions (6 plots if
          'dropsep=TRUE'). 

 dropsep: set 'dropsep=TRUE' to make 'plot.Quantile2' separate pure and
          contaminated functions onto separate plots 

     lty: vector of line types 

     col: vector of colors 

    xlim: optional x-axis limits 

    ylim: optional y-axis limits 

label.curves: optional list which is passed as the 'opts' argument to
          'labcurve'. 

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

     'spower' returns the power estimate (fraction of simulated
     chi-squares greater than the alpha-critical value).  'Quantile2'
     returns an S-Plus function of class '"Quantile2"' with attributes
     that drive the 'plot' method.  The major attribute is a list
     containing several lists.  Each of these sub-lists contains a
     'Time' vector along with one of the following: survival
     probabilities for either treatment group and with or without
     contamination caused by non-compliance, hazard rates in a similar
     way, intervention:control hazard ratio function with and without
     contamination, and dropin and dropout functions.  'logrank'
     returns a single chi-square statistic, and 'Weibull2', 'Lognorm2'
     and 'Gompertz2' return an S function with three arguments, only
     the first of which (the vector of 'times') is intended to be
     specified by the user.

_S_i_d_e _E_f_f_e_c_t_s:

     'spower' prints the interation number every 10 iterations if
     'pr=TRUE'.

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

     Frank Harrell 
      Department of Biostatistics 
      Vanderbilt University School of Medicine 
      f.harrell@vanderbilt.edu

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

     Lakatos E (1988): Sample sizes based on the log-rank statistic in
     complex clinical trials.  Biometrics 44:229-241 (Correction
     44:923).

     Cuzick J, Edwards R, Segnan N (1997): Adjusting for non-compliance
     and  contamination in randomized clinical trials. Stat in Med
     16:1017-1029.

     Cook, T (2003): Methods for mid-course corrections in clinical
     trials with survival outcomes.  Stat in Med 22:3431-3447.

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

     'cpower', 'ciapower', 'bpower', 'cph', 'coxph', 'labcurve'

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

     # Simulate a simple 2-arm clinical trial with exponential survival so
     # we can compare power simulations of logrank-Cox test with cpower()
     # Hazard ratio is constant and patients enter the study uniformly
     # with follow-up ranging from 1 to 3 years
     # Drop-in probability is constant at .1 and drop-out probability is
     # constant at .175.  Two-year survival of control patients in absence
     # of drop-in is .8 (mortality=.2).  Note that hazard rate is -log(.8)/2
     # Total sample size (both groups combined) is 1000
     # % mortality reduction by intervention (if no dropin or dropout) is 25
     # This corresponds to a hazard ratio of 0.7283 (computed by cpower)

     cpower(2, 1000, .2, 25, accrual=2, tmin=1, 
            noncomp.c=10, noncomp.i=17.5)

     ranfun <- Quantile2(function(x)exp(log(.8)/2*x),
                         hratio=function(x)0.7283156,
                         dropin=function(x).1,
                         dropout=function(x).175)

     rcontrol <- function(n) ranfun(n, what='control')
     rinterv  <- function(n) ranfun(n, what='int')
     rcens    <- function(n) runif(n, 1, 3)

     set.seed(11)   # So can reproduce results
     spower(rcontrol, rinterv, rcens, nc=500, ni=500, 
            test=logrank, nsim=50)  # normally use nsim=500 or 1000

     # Simulate a 2-arm 5-year follow-up study for which the control group's
     # survival distribution is Weibull with 1-year survival of .95 and
     # 3-year survival of .7.  All subjects are followed at least one year,
     # and patients enter the study with linearly increasing probability  after that
     # Assume there is no chance of dropin for the first 6 months, then the
     # probability increases linearly up to .15 at 5 years
     # Assume there is a linearly increasing chance of dropout up to .3 at 5 years
     # Assume that the treatment has no effect for the first 9 months, then
     # it has a constant effect (hazard ratio of .75)

     # First find the right Weibull distribution for compliant control patients
     sc <- Weibull2(c(1,3), c(.95,.7))
     sc

     # Inverse cumulative distribution for case where all subjects are followed
     # at least a years and then between a and b years the density rises
     # as (time - a) ^ d is a + (b-a) * u ^ (1/(d+1))

     rcens <- function(n) 1 + (5-1) * (runif(n) ^ .5)
     # To check this, type hist(rcens(10000), nclass=50)

     # Put it all together

     f <- Quantile2(sc, 
           hratio=function(x)ifelse(x<=.75, 1, .75),
           dropin=function(x)ifelse(x<=.5, 0, .15*(x-.5)/(5-.5)),
           dropout=function(x).3*x/5)

     par(mfrow=c(2,2))
     # par(mfrow=c(1,1)) to make legends fit
     plot(f, 'all', label.curves=list(keys='lines'))

     rcontrol <- function(n) f(n, 'control')
     rinterv  <- function(n) f(n, 'intervention')

     set.seed(211)
     spower(rcontrol, rinterv, rcens, nc=350, ni=350, 
            test=logrank, nsim=50)  # normally nsim=500 or more
     par(mfrow=c(1,1))

