Surv {survival}  R Documentation 
Create a Survival Object
Description
Create a survival object, usually used as a response variable in a model formula. Argument matching is special for this function, see Details below.
Usage
Surv(time, time2, event,
type=c('right', 'left', 'interval', 'counting', 'interval2', 'mstate'),
origin=0)
is.Surv(x)
Arguments
time 
for right censored data, this is the follow up time. For interval data, the first argument is the starting time for the interval. 
event 
The status indicator, normally 0=alive, 1=dead. Other choices are

time2 
ending time of the interval for interval censored or counting
process data only. Intervals are assumed to be open on the left and
closed on the right, 
type 
character string specifying the type of censoring. Possible values
are 
origin 
for counting process data, the hazard function origin. This option was intended to be used in conjunction with a model containing time dependent strata in order to align the subjects properly when they cross over from one strata to another, but it has rarely proven useful. 
x 
any R object. 
Details
When the type
argument is missing the code assumes a type based
on the following rules:
If there are two unnamed arguments, they will match
time
andevent
in that order. If there are three unnamed arguments they matchtime
,time2
andevent
.If the event variable is a factor then type
mstate
is assumed. Otherwise typeright
if there is notime2
argument, and typecounting
if there is.
As a consequence the type
argument will normally be omitted.
When the survival type is "mstate" then the status variable will be
treated as a factor. The first level of the factor is taken to
represent censoring and remaining ones a transition to the given
state. (If the status variable is a factor then mstate
is assumed.)
Interval censored data can be represented in two ways. For the first
use type = "interval"
and the codes shown above. In that usage the
value of the time2
argument is ignored unless event=3.
The second approach is to think of each observation as a time
interval with (infinity, t2) for left censored, (t1, infinity) for
right censored, (t,t) for exact and (t1, t2) for an interval.
This is the approach used for type = interval2. Infinite values can
be represented either by actual infinity (Inf) or NA.
The second form has proven to be the more useful one.
Presently, the only methods allowing interval censored data are the
parametric models computed by survreg
and survival curves
computed by survfit
; for both of these,
the distinction between open and closed intervals
is unimportant.
The distinction is important for counting process data and
the Cox model.
The function tries to distinguish between the use of 0/1 and 1/2 coding for
censored data via the condition
if (max(status)==2)
.
If 1/2 coding is used and all the subjects are censored, it will
guess wrong.
In any questionable case it is safer to use logical coding,
e.g., Surv(time, status==3)
would indicate that '3' is
the code for an event.
For multistate survival the status variable will be a factor, whose
first level is assumed to correspond to censoring.
Surv objects can be subscripted either as a vector, e.g.
x[1:3]
using a single subscript,
in which case the drop
argument is ignored and the result will be
a survival object;
or as a matrix by using two subscripts.
If the second subscript is missing and drop=F
(the default),
the result of the subscripting will be a Surv object, e.g.,
x[1:3,,drop=F]
,
otherwise the result will be a matrix (or vector), in accordance with
the default behavior for subscripting matrices.
Value
An object of class Surv
. There are methods for print
,
is.na
, and subscripting survival objects. Surv
objects
are implemented as a matrix of 2 or 3 columns that has further
attributes. These include the type (left censored, right censored,
counting process, etc.) and labels for the states for multistate
objects. Any attributes of the input arguments are also preserved
in inputAttributes
. This may be useful for other packages that
have attached further information to data items such as labels; none
of the routines in the survival package make use of these
values, however.
In the case of is.Surv
, a logical value TRUE
if x
inherits from class "Surv"
, otherwise an FALSE
.
Note
The use of 1/2 coding for status is an interesting historical
artifact.
For data contained on punch cards, IBM 360 Fortran treated blank as a zero,
which led to a policy within the Mayo Clinic section of Biostatistics to never
use "0" as a data value since one could not distinguish it from a
missing value.
Policy became habit, as is often the case, and the use of 1/2 coding for
alive/dead endured long after the demise of the punch cards that had
sired the practice.
At the time Surv
was written many Mayo data sets still used this
obsolete convention, e.g., the lung
data set found in the package.
See Also
coxph
,
survfit
,
survreg
, lung
.
Examples
with(aml, Surv(time, status))
survfit(Surv(time, status) ~ ph.ecog, data=lung)
Surv(heart$start, heart$stop, heart$event)