.-
help for ^stcoxtvc^                              (STB-41: ssa11)
.-

Risk-pool expansion for cox regression
--------------------------------------

        ^stcoxtvc^ varlist [^if^ exp] [^in^ range] 
                            [^, ep^s^(^#^)^ ^p^reserv ^nosh^ow ^st^rata^(^varlist^)^ ]

^stcoxtvc^ is for use with survival-time data; see help @st@.  You must have 
^stset^ your data before using this command; see help @stset@.


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

Risk-pool expansion enables Cox regression with covariates that vary in time 
"continuously" rather than in a few steps. After invoking ^stcoxtvc^, 
time-varying covariates may be defined using the name of the survival time 
variable as the dynamic time variable.

^stcoxtvc^ may require huge amounts of memory. Specifying the list of variables
that you will use as time-constant covariates, or in the construction of 
time-varying covariates helps to reduce memory requirements. If you want to 
invoke ^stcox^ only on a selection of cases (with ^if^ or ^in^ phrases) specify 
these phrases already here. Similarly, if you want to use stratification, 
^stcoxtvc^ will require less memory if these variables are known already here.

^stcoxtvc^ should not be used with parametric survival time models. 


Options
-------

^eps(^#^)^ specifies a typically small number so that a case that is in the risk
    set  at time t is represented in the expanded data by an "infinitesimal" 
    episode (t-eps,t]. Infinitesimal episodes rather that n death-on-arrival-
    episodes are required in Stata because of the particular order in which 
    Stata orders failures, censors, and entries that occur "at" some time t. 
    ^eps^ should be set to a number that is small compared to the measurement 
    unit of time. ^eps^ defaults to 1E-6.       

^strata(^varnames^)^ specifies up to 5 strata variables. In ^stcox^, observations
    with equal values of the variables are assumed to be in the same stratum.
    Stratified estimates (equal coefficients across strata but baseline hazard
    unique to each stratum) are then estimated. 
      ^strata^ are used in risk-pool expansion so that records are replicated
    only at all times at which failures occur within the stratum, and so memory
    requirements are reduced when strata are specified. Performing a stratified
    analysis with ^stcox^ on ^stcoxtvc^ expanded-ed data that do not account for 
    the strata waistes memory but produces otherwise correct results.

^preserve^ specifies that the data are preserved before data manipulation, so 
    that the data will be restored in original form after pressing Break. (Note
    that ^stcoxtvc^ defaults to not preserving the data.)

^noshow^ prevents ^stcoxtvc^ from showing the names of the key ^st^ variables.
    If this appeals to you, consider typing ^stset, noshow^ to make noshow 
    the default for all ^st^ commands; see help @stset@.


Remarks
-------

^stcoxtvc^ generates a `risk-pool expanded' data set in which each record 
(id,t0,t1,died) is expanded into a sequence of records (id,t-,t,d) for all 
times t, t0<t<=t1, at which a failure occured for at least one of the cases, 
where t- = t-eps, where eps defaults to 1E-6. The maximum partial likelihood 
estimator (mple) depends only on the risk pools at the event times, and hence 
the mple's of the unexpanded and expanded data are identical.

^stcoxtvc^ has two main applications for Cox regression:

  * to compute -exact- partial likelihood estimates in case of tied failure 
    times rather than Stata's standard Breslow's approximations. ^stcoxe^ 
    provides a canned solution.

  * to allow for covariates that vary in time -continuously-. In the expanded 
    format, time varying covariates can be constructed by evaluating the 
    covariates at the event times t. An example is given below. 
       Under partial-likelihood estimation, the values of covariates at time 
    points at which no event occurs, do not enter the partial likelihood 
    function, and hence are simply irrelevant. 

^stcoxtvc^ calls ^st_rpool^ for the actual risk pool expansion.

^stcoxtvc^ uses ^st-aux^ to generate the ^st^ key variables before expansion if 
these variables have not yet been defined: a case identifier, entry times, and 
a failure/censor indicator. 


Example
-------

Assume, you want to analyze how the age-of-marriage of a person depends on 
his/her occupational status (time-varyign covariate). The time-constant 
variables are sex and educ (level of education). Time variables (expressed in 
months since age 16) are marriage time (mtime), begin and end of first job 
(wtime1b, wtime1e), begin and end of second job (wtime2b, wtime2e) etc. 

        . ^stset mtime died, id(respnr)^
        . ^stcoxtvc^
        . ^gen work = 0^
        . ^replace work = 1 if mtime > wtime1b^
        . ^replace work = 0 if mtime > wtime1e^
        . ^replace work = 1 if mtime > wtime2b^
        . ^replace work = 0 if mtime > wtime2e^
        . ... repeat for additional jobs
        . ^stcox sex educ work^ 

If you want to perform a stratified ^stcox^-analysis, you have to issue
the ^strata(^varlist^)^ options with both ^stexpand^ and ^stcox^.


Author
------

      Jeroen Weesie
      Utrecht University
      Netherlands
      weesie@@weesie.fsw.ruu.nl


Also See
--------

    STB:  STB-41 ssa11
 Manual:  [R] st
On-Line:  help for @st@, @stset@, @stegen@, @strepl@, @stsplit@, @stcoxe@, @st_rpool@.