# c onfidence i ntervals for survival curves. ## Source The function is loosely based on `km.ci::km.ci`. ```r 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`. - `...`: Additional arguments (not implemented). - `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`: L ower time point. Used in construction of confidence bands. - `tU`: U pper time point. Used in construction of confidence bands. - `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. ## Returns 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. ## Details In the equations below $$ \sigma^2_s(t) = \frac{\hat{V}[\hat{S}(t)]}{\hat{S}^2(t)}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 $$ \hat{S}(t) \pm Z_{1- \alpha} \sigma (t) \hat{S}(t)S(t)+- Z(1-alpha) sigma(t) S(t) $$ * log transform $$ [ \hat{S}(t)^{\frac{1}{\theta}}, \hat{S}(t)^{\theta} ][S(t)^(1/theta), S(t)^theta] $$ where $$ \theta = \exp{ \frac{Z_{1- \alpha} \sigma (t)}{ \log{\hat{S}(t)}}}theta = exp ( Z(1-alpha)sigma(t) / log(S(t)) ) $$ * arcsine-square root transform upper: $$ \sin^2(\max[0, \arcsin{\sqrt{\hat{S}(t)}} -\frac{Z_{1- \alpha}\sigma(t)}{2}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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[\frac{\pi}{2}, \arcsin{\sqrt{\hat{S}(t)}} +\frac{Z_{1- \alpha}\sigma(t)}{2}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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 = \frac{n\sigma^2_s(t_l)}{1+n\sigma^2_s(t_l)}a_l = n*sigma^2(t_l) / [1+n*sigma^2(t_l)] $$ $$ a_u = \frac{n\sigma^2_s(t_u)}{1+n\sigma^2_s(t_u)}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^o(x)\sqrt{[x(1-x)]}|, \quad a_l \leq x \leq a_u}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 $$ \hat{S}(t) \pm c_{\alpha} \sigma_s(t) \hat{S}(t)S(t)+- c[alpha] sigma(t) S(t) $$ * log transform (the default) This uses $theta$ as below: $$ \theta = \exp{ \frac{c_{\alpha} \sigma_s(t)}{ \log{\hat{S}(t)}}}theta = exp (c[alpha] * sigma(t) / log(S(t))) $$ And is given by: $$ [\hat{S}(t)^{\frac{1}{\theta}}, \hat{S}(t)^{\theta}][S(t)^(1/theta), S(t)^theta] $$ * arcsine-square root transform upper: $$ \sin^2(\max[0, \arcsin{\sqrt{\hat{S}(t)}}- \frac{c_{\alpha}\sigma_s(t)}{2}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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[\frac{\pi}{2}, \arcsin{\sqrt{\hat{S}(t)}}+ \frac{c_{\alpha}\sigma_s(t)}{2}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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 $$ \hat{S}(t) \pmk_{\alpha} \frac{1+n\sigma^2_s(t)}{\sqrt{n}} \hat{S}(t)S(t)+- k[alpha] [1+n*sigma^2(t)]*S(t) / n^0.5 $$ * log transform $$ [\hat{S}(t)^{\frac{1}{\theta}}, \hat{S}(t)^{\theta}][S(t)^(1/theta), S(t)^theta] $$ where $$ \theta = \exp{ \frac{k_{\alpha}[1+n\sigma^2_s(t)]}{\sqrt{n}\log{\hat{S}(t)}}}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{\sqrt{\hat{S}(t)}}- \frac{k_{\alpha}[1+n\sigma_s(t)]}{2\sqrt{n}}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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[\frac{\pi}{2}, \arcsin{\sqrt{\hat{S}(t)}}+ \frac{k_{\alpha}[1+n\sigma^2_s(t)]}{2\sqrt{n}}\sqrt{ \frac{\hat{S}(t)}{1-\hat{S}(t)}}])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]) $$ ## 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$. ## Examples ```r ## 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) ``` ## References Nair V, 1984. Confidence bands for survival functions with censored data: a comparative study. **Technometrics**. 26 (3):265-75. http://www.jstor.org/stable/1267553 JSTOR Hall WJ, Wellner JA, 1980. Confidence bands for a survival curve from censored data. **Biometrika**. 67 (1):133-43. http://www.jstor.org/stable/2335326 JSTOR ## See Also `sf` `quantile`

ci function