tmerge {survival} | R Documentation

## Time based merge for survival data

### Description

A common task in survival analysis is the creation of start,stop data sets which have multiple intervals for each subject, along with the covariate values that apply over that interval. This function aids in the creation of such data sets.

### Usage

    tmerge(data1, data2,  id,..., tstart, tstop, options)

### Arguments

`data1` | the primary data set, to which new variables and/or observation will be added
`data2` | second data set in which the other arguments will be found
`id` | subject identifier
`...` | operations that add new variables or intervals, see below
`tstart` | optional variable to define the valid time range for each subject, only used on an initial call
`tstop` | optional variable to define the valid time range for each subject, only used on an initial call
`options` | a list of options. Valid ones are idname, tstartname, tstopname, delay and na.rm. See the explanation below.

### Details

The program is often run in multiple passes, the first of which defines the basic structure, and subsequent ones that add new variables to that structure. For a more complete explanation of how this routine works refer to the vignette on time-dependent variables.

There are 4 types of optional arguments: a time dependent covariate (tdc), cumulative count (cumtdc), event (event) or cumulative event (cumevent). Time dependent covariates change their values before an event, events are outcomes.

- newname = tdc(y, x)A new time dependent covariate variable will created. The argument `y` is assumed to be on the scale of the start and end time, and each instance decribes the occurent of a "condition" at that time. The second argument `x` is optional. In the case where `x` is missing the count variable starts at 0 for each subject and becomes 1 at the time of the event; if `x` is present the count is set to the value of `x`. If the option `na.rm=TRUE` missing values of `x` are first removed.

  newname = cumtdc(y,x)Similar to tdc, except that the event count is accumulated over time for each subject.

  newname = event(y,x)Mark an event at time y. In the ususal case that `x` is missing the new 0/1 variable will be similar to the 0/1 status variable of a survival time.

  newname = cumevent(y,x)Cumulative events.

The function adds three new variables to the output data set: `tstart`, `tstop`, and `id`. The `options` argument can be used to change these names.

### Value

a data frame with two extra attributes `tname` and `tcount`. The first contains the names of the key variables; it's persistence from call to call allows the user to avoid constantly reentering the `options` argument. The tcount variable contains counts of the match types. New time values that occur before the first interval for a subject are "early", those after the last interval for a subject are "late", and those that fall into a gap are of type "gap". Intervals are assumed to be of the form (a,b], open on the left and closed on the right; a new time exactly coincident with the start of a subject's times will thus be "early".

The most common type will usually be "within", for those new times that fall inside an existing interval and cause it to be split into two. Observations that fall exactly on the edge of an interval but within the (min, max] time for a subject are counted as being on a "leading" edge, "trailing" edge or "boundary". The first corresponds for instance to an occurence at 17 for someone with an intervals of (0,15] and (17, 35]. A `tdc` at time 17 will affect this interval but an `event` at 17 would be ignored. An `event` occurence at 15 would count in the (0,15] interval. The last case is where the main data set has touching intervals for a subject, e.g. (17, 28] and (28,35] and a new occurence lands at the join. Events will go to the earlier interval and counts to the latter one.

These extra attributes are ephemeral, and will be discarded if the dataframe is modified in any way. This is intentional.

### Author(s)

Terry Therneau

### See Also

`neardate`

### Examples

    # The pbc data set contains baseline data and follow-up status
    # for a set of subjects with primary biliary cirrhosis, while the
    # pbcseq data set contains repeated laboratory values for those
    # subjects.
    # The first data set contains data on 312 subjects in a clinical trial plus
    # 106 that agreed to be followed off protocol, the second data set has data
    # only on the trial subjects.
    temp <- subset(pbc, id <= 312, select=c(id:sex, stage)) # baseline data
    pbc2 <- tmerge(temp, temp, id=id, endpt = event(time, status))
    pbc2 <- tmerge(pbc2, pbcseq, id=id, ascites = tdc(day, ascites),
                   bili = tdc(day, bili), albumin = tdc(day, albumin),
                   protime = tdc(day, protime), alk.phos = tdc(day, alk.phos))

    fit <- coxph(Surv(tstart, tstop, endpt==2) ~ protime + log(bili), data=pbc2)

[Package survival version 2.39-4 Index]