R: *c*onfidence *i*ntervals for survival curves.

ci {survMisc} | R Documentation

## confidence intervals for survival curves.

### Description

confidence intervals for survival curves.

### Usage

    ci(x, ...)

    ## S3 method for class 'ten'
    ci(x, ..., CI = c("0.95", "0.9", "0.99"), how = c("point",
      "nair", "hall"), trans = c("log", "lin", "asi"), tL = NULL, tU = NULL,
      reCalc = FALSE)

    ## S3 method for class 'stratTen'
    ci(x, ..., CI = c("0.95", "0.9", "0.99"),
      how = c("point", "nair", "hall"), trans = c("log", "lin", "asi"),
      tL = NULL, tU = NULL)

### Arguments

`x` | An object of class `ten`.
`CI` | Confidence intervals. As the function currently relies on lookup tables, currently only 90%, 95% (the default) and 99% are supported.
`how` | Method to use for confidence interval. `point` (the default) uses pointwise confirence intervals. The alternatives use confidence bands (see details).
`trans` | Transformation to use. The default is `trans="log"`. Also supported are linear and arcsine-square root transformations.
`tL` | Lower time point. Used in construction of confidence bands.
`tU` | Upper time point. Used in construction of confidence bands.
`...` | Additional arguments (not implemented).
`reCalc` | Recalcuate the values? If `reCalc=FALSE` (the default) and the `ten` object already has the calculated values stored as an `attribute`, the value of the `attribute` is returned directly.

### Details

In the equations below

sigma^2(t) = V[S(t)]/[S(t)]^2

Where S(t) is the Kaplan-Meier survival estimate and V[S(t)] is Greenwood's estimate of its variance.
The pointwise confidence intervals are valid for individual times, e.g. `median` and `quantile` values. When plotted and joined for multiple points they tend to be narrower than the bands described below. Thus they tend to exaggerate the impression of certainty when used to plot confidence intervals for a time range. They should not be interpreted as giving the intervals within which the entire survival function lies.
For a given significance level alpha, they are calculated using the standard normal distribution Z as follows:

- linear

  S(t)+- Z(1-alpha) sigma(t) S(t)

- log transform

  [S(t)^(1/theta), S(t)^theta]

  where

  theta = exp ( Z(1-alpha)sigma(t) / log(S(t)) )

- arcsine-square root transform
  upper:

  sin^2(max[0, arcsin S(t)^0.5 - Z(1-alpha)sigma(t)/2 (S(t)/1-S(t))^0.5])

  lower:

  sin^2(min[pi/2, arcsin S(t)^0.5 + Z(1-alpha)sigma(t)/2 (S(t)/1-S(t))^0.5])

Confidence bands give the values within which the survival function falls within a range of timepoints.
The time range under consideration is given so that tL >= min(t), the minimum or lowest event time and tU <= max(t), the maximum or largest event time.
For a sample size n and 0 < a_l < a_u <1:

a_l = n*sigma^2(t_l) / [1+n*sigma^2(t_l)]

a_u = n*sigma^2(t_u) / [1+n*sigma^2(t_u)]

For the Nair or equal precision (EP) confidence bands, we begin by obtaining the relevant confidence coefficient c[alpha]. This is obtained from the upper a-th fractile of the random variable

U = sup{ |W(x)[x(1-x)]^0.5|, a_l <= x <= a_u}

Where W is a standard Brownian bridge.
The intervals are:

- linear

  S(t)+- c[alpha] sigma(t) S(t)

- log transform (the default)
  This uses theta as below:

  theta = exp (c[alpha] * sigma(t) / log(S(t)))

  And is given by:

  [S(t)^(1/theta), S(t)^theta]

- arcsine-square root transform
  upper:

  sin^2(max[0, arcsin S(t)^0.5 - c[alpha]*sigma(t)/2 (S(t)/1-S(t))^0.5])

  lower:

  sin^2(min[pi/2, arcsin S(t)^0.5 - c[alpha]*sigma(t)/2 (S(t)/1-S(t))^0.5])

For the Hall-Wellner bands the confidence coefficient k[alpha] is obtained from the upper a-th fractile of a Brownian bridge.
In this case t_l can be =0.
The intervals are:

- linear

  S(t)+- k[alpha] [1+n*sigma^2(t)]*S(t) / n^0.5

- log transform

  [S(t)^(1/theta), S(t)^theta]

  where

  theta = exp(k[alpha] * [1 + n * sigma^2(t)] / n^0.5 * log(S(t)))

- arcsine-square root transform
  upper:

  sin^2( max[0, arcsin S(t)^0.5 - k[alpha]*[1+n*sigma^2(t)]/(2*n^0.5) (S(t)/1-S(t))^0.5])

  lower:

  sin^2( min[pi/2, arcsin S(t)^0.5 - k[alpha]*[1+n*sigma^2(t)]/(2*n^0.5) (S(t)/1-S(t))^0.5])

### Value

The `ten` object is modified in place by the additional of a `data.table` as an `attribute`.
`attr(x, "ci")` is printed.
This A `survfit` object. The `upper` and `lower` elements in the list (representing confidence intervals) are modified from the original.
Other elements will also be shortened if the time range under consideration has been reduced from the original.

### Note

- For the Nair and Hall-Wellner bands, the function currently relies on the lookup tables in `package:km.ci`.

- Generally, the arcsin-square root transform has the best coverage properties.

- All bands have good coverage properties for samples as small as n=20, except for the Nair / EP bands with a linear transformation, which perform poorly when n < 200.

### Source

The function is loosely based on `km.ci::km.ci`.

### References

Nair V, 1984. Confidence bands for survival functions with censored data: a comparative study. Technometrics. 26(3):265-75. JSTOR.

Hall WJ, Wellner JA, 1980. Confidence bands for a survival curve from censored data. Biometrika. 67(1):133-43. JSTOR.

### See Also

`sf`

`quantile`

### Examples

    ## K&M 2nd ed. Section 4.3. Example 4.2, pg 105.
    data("bmt", package="KMsurv")
    b1 <- bmt[bmt$group==1, ] # ALL patients
    ## K&M 2nd ed. Section 4.4. Example 4.2 (cont.), pg 111.
    ## patients with ALL
    t1 <- ten(Surv(t2, d3) ~ 1, data=bmt[bmt$group==1, ])
    ci(t1, how="nair", trans="lin", tL=100, tU=600)
    ## Table 4.5, pg. 111.
    lapply(list("lin", "log", "asi"),
           function(x) ci(t1, how="nair", trans=x, tL=100, tU=600))
    ## Table 4.6, pg. 111.
    lapply(list("lin", "log", "asi"),
           function(x) ci(t1, how="hall", trans=x, tL=100, tU=600))
    t1 <- ten(Surv(t2, d3) ~ group, data=bmt)
    ci(t1, CI="0.95", how="nair", trans="lin", tL=100, tU=600)
    ## stratified model
    data("pbc", package="survival")
    t1 <- ten(coxph(Surv(time, status==2) ~ log(bili) + age + strata(edema), data=pbc))
    ci(t1)

[Package survMisc version 0.5.4 Index]