README file:  Survival Sacrifice  Programs

1.  "Survival Sacrifice"  is a  application written by 
    Piet Groeneboom to implement the methods discussed
    in the Statistics 593 Course Notes, Spring 1998:
   
        Groeneboom, Piet (1998).
        Some Inverse Problems in Statistics:
        Special Topics Course, Statistics 593.
        Technical Report ??, Department of Statistics, 
        University of Washington, Seattle.
    
    The version of the application posted on 11/16/00 uses a new
    algorithm exploiting the structure of the Hessian.
        
    A recent paper on this model with references to previous work is:
    
        van der Laan, M. J, Jewell, N. P., and Peterson, D.  (1997).
        Efficient estimation of the lifetime and disease onset distribution.
        Biometrika 84, 539 - 554. 
      
2.  The model for "Survival Sacrifice Data" treated here means that:
    (a)  (T_1i , T_2i), i = 1, ... , n  are i.i.d. with joint d.f.  F on R^2;
          with T_1i \le T_2i   a.s.  
    (b)  C_1, ... , C_n are i.i.d. random variables with d.f. G .
    (c)  observations consist of X_i = (Z_i,D_1i , D_2i), i = 1, ... , n where
         Z_i =  min{T_2i , C_i} ,
         D_1i =  1{T_1i \le C_i}, 
         D_2i =  1{T_2i \le C_i}. 
         Thus we observe right-censored data for F_2, the second marginal of $F$,
         and (roughly, at least) interval censored (case 1) data for the first marginal $F_1$ 
         of F. 
    The goal is to estimate the two marginal distribution functions $F_1$ and $F_2$ of $F$.
         
3.  Methods available in the program:
        Primal-Dual interior point algorithm for computation of the joint NPMLE 
        (F_1, F_2).  This method is described in the course notes listed above in 1; 
        also see

             Wright, S. J. (1996).
             Primal-Dual Interior Point Methods.
             SIAM, Philadelphia.  

        Other algorithms (including pseudo maximum likelihood, logarithmic barrier interior
        point method) are under further development.
                    
4.  Data (included and) generated in the application:
    A   Two types of randomly generated data:
        In both cases  T_1 ~ exponential(1), T_3 ~exponential(1/2)   
        (so E(T_3) =2) are independent;
                      T_2 = T_1 + T_3  (so E(T_2) = 3).  
        Case A.  C ~ exponential(2/5), (so E(C) = 2.5).  
        Case B.  C ~ Uniform on {1,2,3}.
    
    B. One can choose to use input files or to generate random samples
       by the menu "Samples"; An input files dat.100 is provided as an example,
       generated as in Case A of the randomly generated data.

5.  User-specified data is allowed; input files should be in 
    the form of three columns, the first for Z_i, the second for D_1i, the third for D_2i.
    
6.  For running one of the algorithms on either input files or randomly
        generated data, press "command-r" or use the menu "Run".

7.  Output: 
      (i) values of the "duality criterion \mu ", Euclidean norm of the gradient vector divided
          by the sample size  n,  and value of -log-likelihood for successive
          iterations of the algorithm. For more information on the primal dual method,
          see the notes in 1 above, or Wright (1996).
          The iterations can be stopped at any time by pressing "command-period" (="apple-period").
          The iterations are stopped automatically if the criteria are zero in
          7 decimals. The text output of the iterations can be saved if desired,
          the name can be specified in the dialog box that will appear.
          The value of the estimator at the end of the iterations, together with the data,
          is written to a file called "NPMLE".
      (ii) a plot of the estimated d.f., which can be saved as a PICT
           file via the menu or "command-s". The PICT file can be opened
           by SimpleText or applications like Adobe Illustrator or Mathematica.
           One can exit the plot by pressing return.
      
      Because the output files can be large for big n, the program uses a freeware
      replacement of the Apple toolbox Text Edit routines.
      At the time that the program was written (1996), the toolbox Text Edit routines
      still had the limitation of 32K.
      Since in Mac OS 8.1 SimpleText still refuses to open files bigger than 32K,
      we fear that the situation in this respect still has not changed,
      which is an absolute disgrace in this day and age!
      The replacement of the Apple toolbox Text Edit routines is called TE32K.c 
      and was written by Roy Wood and Michael J. Lowe, whose contribution
      (given unknowingly) is gratefully acknowledged. The text files that are
      produced can be read by any editor that can handle text files bigger than 32K
      (in which case they cannot be read by SimpleText!), like BBEdit or Textures
      or by the application itself (in the latter no printing facilities are included, 
      nor do we use any of the more advanced interface features; one can do editing of
      the text and save the changes, though).
          
7.  For more information on (Macintosh compatible) 
    C source code for this program, please contact
    either Jon Wellner or Piet Groeneboom. The executable was compiled
    using Metrowerks CodeWarrior 3.0. 
    (Copyright issues are involved in making source code available.)

Written by Jon Wellner and Piet Groeneboom,  July 1998.
Updated August 1998.