gte {gte}

Generalized Turnbull's Estimator

Description

The gte function computes the generalized Turnbull's Estimator (GTE) proposed by Dehghan and Duchesne (2011). It is a nonparametric estimator of a conditional survival function given a vector of continuous covariates that can handle interval-censored lifetimes.
The print method for objects obtained from gte only prints the output value surv.summary.
The plot method for objects obtained from gte plots the estimate of the conditional survival function, by default overlaying curves if more than one estimate is present and shading the innermost interval, in which the GTE is indeterminate.

Usage

gte(formula, data, z, h = NULL, itermax = 1e+05, tole = 5e-04)

## S3 method for class 'gte'
print(x, ...)

## S3 method for class 'gte'
plot(
  x,
  overlay = TRUE,
  shade = TRUE,
  xlab = "time",
  ylab = "survival",
  xleg = "bottomleft",
  yleg = NULL,
  ...
)

Arguments

formula

A formula object with the response on the left of a ~ operator, and the covariates on the right. The response must be a survival object as returned by the Surv function from the package survival (see Details).

data

An optional data frame, list or environment containing the variables in the model formula. If not found in data, the variables are taken from environment(formula), typically the environment from which gte is called.

z

A matrix: each row contains the values of a covariate vector at which an estimate of the conditional survival function is requested. If there is only one covariate, it can be a vector (possibly of length 1).

h

A vector: the values of the bandwidth parameter h for each covariate (default = equation 7 of Dehghan and Duchesne (2011)).

itermax

maximal number of iterations for the algorithm (default=100000).

tole

maximal distance between successive iterations tolerated before declaring convergence (default=0.0005).

x

An object, produced by the gte function, to print or to plot.

...

Further arguments to be passed to print.default or plot.default.

overlay

A logical: Should the curves be overlayed when there is more than one estimate of the conditional survival function in the gte object x? (default=TRUE)

shade

A logical: Should the rectangles of indeterminate NPMLE (innermost interval) be shaded? (default=TRUE)

xlab

A label for the x-axis, by defaut xlab = "time".

ylab

A label for the y-axis, by defaut ylab = "survival".

xleg

x location for legend, "bottomleft" by default (see legend).

yleg

y location for legend, NULL by default (see legend).

Details

For interval-censored data, the Surv function should be called with the argument type="interval" or type="interval2". If type="interval", the event argument is mandatory. Therefore, in addition to the left and right endpoints of the censoring interval (called, respectively, left and right for illustrative purpose), one would need a third variable (status) taking the value 0 for right censored data, 1 for an event at exact time, 2 for left censored data and 3 for interval censored data. The Surv function would be called as follows:
Surv(time=left, time2=right, event=status, type="interval").

If type="interval2", the event argument cannot be given. The value of event is derived from the time and time2 argument as follows:
if time takes the value NA, event=2 (left censored data);
if time2 takes the value NA, event=0 (right censored data);
if time=time2, event=1 (exact time);
otherwise, event=3 (interval censored data).
See the help page of the Surv function for more details.

In the gte function, the data must be given through the Surv function but it is internally transformed in two vectors : L and R for the left and right endpoints of the censoring interval, respectively.
If event=0 (right censored data), then L=time and R=Inf;
if event=1 (exact time), then L=time and R=time;
if event=2 (left censored data), then L=0 and R=time;
and if event=3 (interval censored data), then L=time and R=time2;
If one has vectors L and R respecting this convention, they can be given directly to gte by calling Surv as follows:
Surv(L, R, type="interval2").

Value

time

A vector: the ordered distinct values of the left and right endpoints of the censoring interval (omitting the smallest value, but always including time 0).

surv

A matrix: the estimates of the conditional survival function at time time. The ith column refers to the ith value of the covariate vector given in z (row i of z).

intmap

A matrix : The intervals of the potential steps in the conditional survival function, called innermost interval, over which the GTE is indeterminate. The left endpoints of the intervals are in the first row, and the rigth endpoints in the second. The object attribute LRin denotes whether to include each of the endpoints or not. This matrix is computed with an internal function derived from function Aintmap of the interval package.

surv.summary

A summary of surv: the estimates of the conditional survival function only for the intervals of the potential steps in the function (innermost intervals). The row names describe the intervals, which are detailed in intmap.

Call

The function call.

Author(s)

Mohammad Hossein Dehghan, Thierry Duchesne and Sophie Baillargeon

References

Dehghan, M. H. and Duchesne, T. (2011). A generalization of Turnbull's estimator for nonparametric estimation of the conditional survival function with interval-censored data. Lifetime Data Analysis, 17, 234-255.

See Also

Surv

Examples

## Calling Surv() with type="interval2"
Fit <- gte(Surv(L, R, type="interval2") ~ Z, data=simul, z=c(10, 20))
Fit

## Calling Surv() with type="interval"
event <- ifelse(is.na(simul$R), 0,
                ifelse(is.na(simul$L), 2,
                       ifelse(simul$R==simul$L, 1, 3)))
time <- ifelse(event==2, simul$R, simul$L)
time2 <- ifelse(event==3, simul$R, NA)
simul_event <- cbind(simul, time, time2, event)

Fit_event <- gte(Surv(time, time2, event, type="interval") ~ Z, data=simul_event, z=c(10, 20))
Fit_event

# The results are the same
all.equal(Fit_event$time, Fit$time)
all.equal(Fit_event$surv, Fit$surv)

## Plotting the results
plot(Fit, xleg="topright")