.-
help for ^studysi^
.-

Usage
-----
    ^studysi^ [method]^,edf0(^elist0^) hr^atio^(^hrlist^)^ 
              [^np^eriod^(^#^) ng^roups^(^#^) n(^#^) po^wer^(^#^) al^pha^(^#^) ar^atio^(^#[#...#]^)^
               ^tr^end ^do^se^(^#[#...#]^) lg(^#[#...#]^) ld^f^(^llist [^;^llist^;^... llist]^)^
               ^re^crt^(^rlist^) wg(^#[#...#]^) wd^f^(^wlist [^;^wlist^;^... wlist]^)^
               ^cr^over^(^#[#...#]^) pw^ehr^(^hrlist^) nolo^cal ^de^tail ]


Description 
-----------

^studysi^ calculates sample size and power for comparative studies with either
binary or time-to-event outcome. ^studysi^ has the following flexible features:-
1. An arbitrary number K (>=2) groups.
2. Global or linear trend tests with arbitrary dose levels.
3. Logrank (unweighted or weighted (Tarone-Ware or Harrington-Fleming with
   any index)) and binomial (conditonal and unconditional) tests.
4. Time dependent rates of event, loss to follow-up and withdrawal from 
   allocated treatment (treatment change).
5. Staggered entry


method: The method of comparison with the format
		l|t|h [I]|b [c|u]
	where
	l = unweighted logrank (default test)
	t = Tarone-Ware test (logrank with weights proportional to the square 
	    root of the total number at risk at event times.
	h = Harrington-Fleming (logrank with weights proportional to S**I,
            where S is the estimated pooled survival function at event times.
	I = Index for Harrington-Fleming weights. Default is I=1.
	b = Binomial test comparing the proportion of failure at the end of
	    the study.
	c = Binomial test is conditional on the total number of observed events
	    using Peto's approximation to the log odds ratio (default).
	u = Uncoditional binomial test.


Options
-------

^alpha^  specifies the significance level. The default is ^alpha(0.05)^.

^aratio^ specifies the allocation ratio. ^aratio(^#1 #2...#r^)^ means that allocation
       ratio for group k is #k, k=1,...r. If r<^ngroups^, the allocation ratio
       for group k is #r, k=r+1,...,^ngroups^. The default is equal group size.

^crover^ (Only when wg is specified) is the target group number when crossing
       over. ^crover(^#1 #2...#r^)^ means that the kth group withdrawing from
       allocated treatment (specified by ^wg^) crosses over to recieve the
       allocated treatment of group #k, k=1,...r. The default is that when
       individuals in group 1 change treatment, they receive the treatment
       assigned to those in group 2. Individuals in group k (k > 1) crossover
       to recieve the treatment assined to group 1.

^detail^ requests more detailed output including expected proportion of failure,
       withdrawal from allocated treatment and loss to follow-up by the end
       of the study.

^dose^ specifies doses for dose-respone (linear trend) test. ^dose(^#1 #2...#r^)^
       assigns dose for	groups 1,...,r. If r < ngroups, #r is taken as the
       dose for groups r+1,...ngroups. The default is dose(1 2...ngroups) which
       is only used when ^trend^ is specified but not ^dose^.

^edf0^ is required and gives the Control event distribution function. This need
       not be one of the distributions to be compared unless hratio = 1 for
       some of the groups. The format is ^edf0(^elist0^)^, where string "elist0"
       is "#1 [#2 ...#r^,^#1 #2 ...#r]". Thus, ^edf0(^p1 p2 ...pr^,^t1 t2 ...tr^)^
       gives the value pi for the cumulative distribution function for the
       event time at the end of time period ti, i=1,...,r. Instantaneous event
       rates are assumed constant within time periods ( time-to-event is
       piecewise exponential). If r < ^nperiod^, the instantaneous event rates in
       periods r+1,...,nperiod are taken to be the same as in period r. If only
       one value of ^edf0^ is specified, this is taken to be the value at the end
       of the study and the instantaneous event rate is constant thoughout
       follow-up. Thus if the number of periods ^nperiod = 6^ then ^edf0(0.5)^ is
       equivalent to ^edf0(0.5,6)^ and gives 50% cumulative failure at the end
       of period ^nperiod^ and an exponential distribution for the control
       failure time. ^edf0(0.2 0.4,1 5)^ gives expected cumulative proportions
       of failure ^0.2^ at the end of the first period and ^0.4^ at the end of the
       fifth period. The instantaneous event rate during the first period is
       ^-log(1-0.2)=0.223^. The instantaneous event rate during periods 2,3,4 and
       5 is ^-log((1-0.4)/(1-0.2))/4 = 0.072^ which is also the default rate
       during period 6. This gives cumulative failure probability of 0.55 at
       the end of period 6.

^hratio^ is required and specifies the event hazard ratio functions. The format
         is ^hratio(^hrlist^)^, where the string "hrlist" is
         "#1_1 [#1_2 ...#1_r1]^,^#2_1 [#2_2 ...#2_r2]^,^...^,^ #k_1 [#k_2 ...#k_rk]".
         The event hazard ratio of group i (relative to the control
         distribution edf0) is #i_j during period j, j=1,...ri; i=1,...k, If
         ri < ^nperiod^ then the hazard ratio function during periods ri+1,...
        ^nperiod^ is assumed to be #i_ri. If k < ^ngroups^, the hazard ratio
         functions for groups k+1,...,ngroups are assumed equal to the
         geometric mean of the hazard ratio functions for groups 1,...k.

^ldf^  is required when lg, groups with loss to follow-up, is specified. ^ldf^
       specifies the distribution function of time to loss-to-follow-up. The
       format is ^ld^f^(^llist [^;^llist^;^... llist]^)^, where each llist specifies
       a cumulative distribution function for time to to loss from follow-up,
       one for each group specified by ^lg^ and in the same order. Each llist has
       the same form and interpretation as a distribution function as elist0 in
      ^edf0^. e. g. if ^nperiod^ = 6, then ^lg(1 3) ldf(0.2;.05 0.15,2 5)^
       specifies that:
	 (i)   Groups 1 and 3 are subject to loss to follow-up.
	 (ii)  The cumulative probability of loss to follow-up is .2 by the end
	       of the last period in group1, .05 at the end of the period 2 and
	       .15 at the end of period 5 in group 3.
	 (iii) Individuals in the other groups are not subject to loss to
	       follow-up.

^lg^  specifies the groups subject to loss to follow-up. ^ldf^ must then be
      specified giving the cumulative distribution functions of time to loss-
      to-follow-up in the same order.

^local^ specifies local alternative for the unconditional binomial test of the
       null hypothesis of equal proportions. The default is ^nolocal^ if method
       is b u. 

^n^ specifies that total sample size is calculated if ^n^ = 0. Otherwise power
    is calculated given total sample size = ^n^. The default is ^n = 0^.

^ngroup^ specifies the number of comparitive groups. The default is ^ngroups^ = 2.

^nperiod^ is the number of time periods within which all instantaneous rates are
          constant. The default is ^nperiod = 1^.

^power^ specifies the study power. the default is power = 0.8 if ^n > 0^.

^pwehr^ specifies the hazard ratio function post withdrawal from allocated
        treatment. The format is ^pw^ehr^(^hrlist^)^, where hrlist gives the hazard
        ratio functions (relative to the control event time distribution) after
        treatment change for the groups specified by ^wg^ and in the same order.
        The format and interpretation of hrlist is the same as that of ^hratio^
        except that the hazard ratio functions for the remaining groups,
        subject to treatment change (given in ^wg^) but not assigned to a hazard
        ratio function by ^pwehr^, is taken to be the same as the last hazard
        ratio function specified by ^pwehr^. When both ^pwehr^ and ^crover^ are
        specified, ^crover^ is ignored.

^recrt^ specifies the duration and rate of recruitment. If ^recrt^ is not
        specified, recruitment is assumed completed at the begining of the
        study. i.e. duration of recruitment = 0. When ^recrt^ is specified, its
        format is ^recrt(^[duration [recrpr0]]^,^[w1 w2...wk]^,^[s1 s2...sk]^)^;
        where
            duration = the number of periods for the completion of recruitment.
                       The default is duration = ^nperiods^.
            recrpr0 = the proportion recruited (instantaneously) at the start
                      of the study. The default is recrpr0 = 0.
            w1...wk are the relative proportions recruited in periods 1 to k.
                    The default specifies equal proportions.
            s1...sm specify the shape of recruitment time distribution within
                    periods. si = 0 for uniform entry during period i, and
                    si = L>0 for negative exponential with rate L. The default
                    is uniform entry time within each period.

^wdf^  is required when wg, groups with treatment change (withdrawal from 
       allocated treatment), is specified. ^wdf^ specifies the distribution
       function of time to withdrawal. The format is the same as that of ^ldf^.

^wg^  specifies the groups subject to loss to follow-up. ^wdf^ must then be
      specified giving the cumulative distribution functions of time to 
      withdrawal from allocated treatment in the same order.


Examples
--------

	. ^studysi l, edf0(0.5) hr(1,0.75) np(3)^
           (compares two exponential distributions using the logrank test)

	. ^studysi h, edf0(0.5) hr(1,0.75,0.5) np(3) ng(3) recrt(2,,)^

	. ^studysi l, edf0(0.5) hr(1,0.75,0.5) np(3) ng(3) recrt(2,,) tr^

	. ^studysi , edf0(0.2 0.5,1 3) hr(1,0.6 0.6 0.75) np(3)^
           (treatment effect changes over time)

	. ^studysi l, edf0(0.5) hr(1,0.75) np(3) lg(1 2) ldf(.1;.1)^
           (10% lost to follow-up by end of study)

	. ^studysi l, edf0(0.5) hr(1,0.75) np(3) lg(1 2) ldf(.1;.1) /*^
                ^*/ wg(1 2) wdf(.3;.1)^
           (30% of group 1 and 10% og group 2 crossover by end of study)


Also see
--------

 Manual:  ^[R] sampsi^

