<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Calculates the proportion of treatment effect explained by...</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for R.s.surv.estimate"><tr><td>R.s.surv.estimate</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>

Calculates the proportion of treatment effect explained by the surrogate marker information measured at a specified time and primary outcome information up to that specified time
</h2>

<h3>Description</h3>


<p>This function calculates the proportion of treatment effect on the primary outcome explained by the surrogate marker information measured at <i>t_0</i> and primary outcome information up to <i>t_0</i>.  The user can also request a variance estimate, estimated using perturbating-resampling, and a 95% confidence interval. If a confidence interval is requested three versions are provided: a normal approximation based interval, a quantile based interval and Fieller's confidence interval, all using perturbation-resampling. The user can also request an estimate of the incremental value of surrogate marker information. 
</p>


<h3>Usage</h3>

<pre>
R.s.surv.estimate(xone, xzero, deltaone, deltazero, sone, szero, t, 
weight.perturb = NULL, landmark, extrapolate = FALSE, transform = FALSE, 
conf.int = FALSE, var = FALSE, incremental.value = FALSE, approx = T)
</pre>


<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>xone</code></td>
<td>


<p>numeric vector, the observed event times in the treatment group, X = min(T,C) where T is the time of the primary outcome and C is the censoring time.
</p>
</td></tr>
<tr valign="top"><td><code>xzero</code></td>
<td>


<p>numeric vector, the observed event times in the control group, X = min(T,C) where T is the time of the primary outcome and C is the censoring time.
</p>
</td></tr>
<tr valign="top"><td><code>deltaone</code></td>
<td>


<p>numeric vector, the event indicators for the treatment group, D = I(T&lt;C) where T is the time of the primary outcome and C is the censoring time.
</p>
</td></tr>
<tr valign="top"><td><code>deltazero</code></td>
<td>


<p>numeric vector, the event indicators for the control group, D = I(T&lt;C) where T is the time of the primary outcome and C is the censoring time.
</p>
</td></tr>
<tr valign="top"><td><code>sone</code></td>
<td>


<p>numeric vector; surrogate marker measurement at <i>t_0</i> for treated observations, assumed to be continuous. If <i>X_{1i}&lt;t_0</i>, then the surrogate marker measurement should be NA. 
</p>
</td></tr>
<tr valign="top"><td><code>szero</code></td>
<td>


<p>numeric vector; surrogate marker measurement at <i>t_0</i> for control observations, assumed to be continuous. If <i>X_{1i}&lt;t_0</i>, then the surrogate marker measurement should be NA.
</p>
</td></tr>
<tr valign="top"><td><code>t</code></td>
<td>


<p>the time of interest.
</p>
</td></tr>
<tr valign="top"><td><code>weight.perturb</code></td>
<td>


<p>weights used for perturbation resampling.
</p>
</td></tr>
<tr valign="top"><td><code>landmark</code></td>
<td>


<p>the landmark time <i>t_0</i> or time of surrogate marker measurement.
</p>
</td></tr>
<tr valign="top"><td><code>extrapolate</code></td>
<td>


<p>TRUE or FALSE; indicates whether the user wants to use extrapolation.
</p>
</td></tr>
<tr valign="top"><td><code>transform</code></td>
<td>


<p>TRUE or FALSE; indicates whether the user wants to use a transformation for the surrogate marker. 
</p>
</td></tr>
<tr valign="top"><td><code>conf.int</code></td>
<td>


<p>TRUE or FALSE; indicates whether a 95% confidence interval for delta is requested, default is FALSE.
</p>
</td></tr>
<tr valign="top"><td><code>var</code></td>
<td>


<p>TRUE or FALSE; indicates whether a variance estimate is requested, default is FALSE.
</p>
</td></tr>
<tr valign="top"><td><code>incremental.value</code></td>
<td>


<p>TRUE or FALSE; indicates whether the user would like to see the incremental value of the surrogate marker information, default is FALSE.
</p>
</td></tr>
<tr valign="top"><td><code>approx</code></td>
<td>

<p>TRUE or FALSE indicating whether an approximation should be used when calculating the probability of censoring; most relevant in settings where the survival time of interest for the primary outcome is greater than the last observed event but before the last censored case, default is TRUE.
</p>
</td></tr>
</table>


<h3>Details</h3>


<p>Let <i>G</i> be the binary treatment indicator with <i>G=1</i> for treatment and <i>G=0</i> for control and we assume throughout that subjects are randomly assigned to a treatment group at baseline. Let <i>T^{(1)}</i> and <i>T^{(0)}</i> denote the time of the primary outcome of interest, death for example, under the treatment and under the control, respectively. Let <i>S^{(1)}</i> and <i>S^{(0)}</i> denote the surrogate marker measured at time <i>t_0</i> under the treatment and the control, respectively.
</p>
<p>The residual treatment effect is defined as
</p>
<p style="text-align: center;"><i> &Delta;_S(t,t_0) = P(T^{(0)} &gt; t_0) &le;ft \{\int &psi;_1(t | s, t_0) dF_0(s | t_0)-P(T^{(0)}&gt; t| T^{(0)}&gt; t_0) \right \}</i></p>
<p> where <i>F_0(\cdot |  t_0)</i> is the cumulative distribution function of <i>S^{(0)}</i> conditional on <i>T^{(0)}&gt; t_0</i> and <i>&psi;_1(t |  s,t_0) = P(T^{(1)}&gt; t |  S^{(1)}=s, T ^{(1)} &gt; t_0)</i>. The proportion of treatment effect explained by the surrogate marker information measured at <i>t_0</i> and primary outcome information up to <i>t_0</i>, which we denote by <i>R_S(t,t_0)</i>, can be expressed using a contrast between <i>&Delta;_S(t,t_0)</i> and <i>&Delta;(t)</i>:
</p>
<p style="text-align: center;"><i>R_S(t,t_0)=\{&Delta;(t)-&Delta;_S(t,t_0)\}/&Delta;(t)=1-&Delta;_S(t,t_0)/&Delta;(t).</i></p>
<p>   The definition and estimation of <i>&Delta;(t)</i> is described in the delta.surv.estimate documentation.
</p>
<p>Due to censoring, our data consist of <i>n_1</i> observations <i>\{(X_{1i}, &delta;_{1i}, S_{1i}), i=1,...,n_1\}</i> from the treatment group <i>G=1</i> and <i>n_0</i> observations <i>\{(X_{0i}, &delta;_{0i}, S_{0i}), i=1,...,n_0\}</i> from the control group <i>G=0</i> where <i>X_{gi} = \min(T_{gi}, C_{ gi})</i>,  <i>&delta;_{gi} = I(T_{gi} &lt; C_{gi})</i>, <i>C_{gi}</i> denotes the censoring time, and <i>S_{gi}</i> denotes the surrogate marker information measured at time <i>t_0</i>, for <i>g= 1,0</i>, for individual <i>i</i>. Note that if <i>X_{gi} &lt; t_0</i>, then <i>S_{gi}</i> should be NA (not available).
</p>
<p>To estimate <i>&Delta;_S(t,t_0)</i>, we use a nonparametric kernel Nelson-Aalen estimator to estimate <i>&psi;_1(t | s,t_0)</i> as <i>\hat{&psi;}_1(t| s,t_0)  = \exp\{-\hat{&Lambda;}_1(t| s,t_0) \}</i>, where
</p>
<p style="text-align: center;"><i>\hat{&Lambda;}_1(t| s,t_0) = \int_{t_0}^t \frac{&sum;_{i=1}^{n_1} I(X_{1i}&gt;t_0) K_h\{&gamma;(S_{1i}) - &gamma;(s)\}dN_{1i}(z)}{&sum;_{i=1}^{n_1}  I(X_{1i}&gt;t_0) K_h\{&gamma;(S_{1i}) - &gamma;(s)\} Y_{1i}(z)},</i></p>

<p>is a consistent estimate of <i>&Lambda;_1(t| s,t_0 ) =  -\log [&psi;_1(t| s,t_0)], Y_{1i}(t) = I(X_{1i} &ge;q t),  N_{1i}(t) = I(X_{1i} &le;q t) &delta;_i,  K(\cdot)</i> is a smooth symmetric density function, <i>K_h(x) = K(x/h)/h, &gamma;(\cdot)</i> is a given monotone transformation function, and <i>h</i> is a specified bandwidth. To obtain an appropriate <i>h</i> we first use bw.nrd to obtain <i>h_{opt}</i>; and then we let <i>h = h_{opt}n_1^{-c_0}</i>  with <i>c_0 = 0.11</i>.
</p>
<p>Since <i>F_0(s | t_0) = P(S_{0i} &le; s | X_{0i} &gt; t_0)</i>, we empirically estimate <i>F_0(s | t_0)</i> using all subjects with <i>X_{0i} &gt; t_0</i> as </p>
<p style="text-align: center;"><i>
\hat{F}_0(s | t_0) = \frac{&sum;_{i=1}^{n_0} I(S_{0i} &le; s, X_{0i} &gt; t_0)}{&sum;_{i=1}^{n_0} I(X_{0i} &gt; t_0)}.</i></p>

<p>Subsequently, we construct an estimator for <i>&Delta;_{S}(t,t_0)</i> as
</p>
<p style="text-align: center;"><i>\hat{&Delta;}_S(t,t_0) = n_0^{-1} &sum;_{i=1}^{n_0} &le;ft[\hat{&psi;}_1(t| S_{0i},t_0) \frac{I(X_{0i} &gt; t_0)}{\hat{W}^C_0(t_0)}  -   \frac{I(X_{0i} &gt; t)}{\hat{W}^C_0(t)}\right]</i></p>

<p>where <i>\hat{W}^C_g(\cdot)</i> is the Kaplan-Meier estimator of survival for censoring for <i>g=1,0.</i> Finally, we estimate <i>R_S(t,t_0)</i> as <i>\hat{R}_S(t,t_0) =1- \hat{&Delta;}_S(t,t_0)/\hat{&Delta;}(t).</i> 
</p>
<p>Variance estimation and confidence interval construction are performed using perturbation-resampling. Specifically, let <i>&le;ft \{ V^{(b)} = (V_{11}^{(b)}, ...V_{1n_1}^{(b)}, V_{01}^{(b)}, ...V_{0n_0}^{(b)})^T, b=1,....,D \right \}</i> be <i>n \times D</i> independent copies of a positive random variables <i>V</i> from a known distribution with unit mean and unit variance. Let
</p>
<p style="text-align: center;"><i>\hat{&Delta;}^{(b)}(t) = \frac{  &sum;_{i=1}^{n_1} V_{1i}^{(b)} I(X_{1i}&gt;t)}{ &sum;_{i=1}^{n_1} V_{1i}^{(b)} \hat{W}_1^{C(b)}(t)}  -\frac{  &sum;_{i=1}^{n_0} V_{0i}^{(b)} I(X_{0i}&gt;t)}{ &sum;_{i=1}^{n_0} V_{0i}^{(b)} \hat{W}_0^{C(b)}(t)}.</i></p>
<p> In this package, we use weights generated from an Exponential(1) distribution and use <i>D=500</i>. The variance of <i>\hat{&Delta;}(t)</i> is obtained as the empirical variance of <i>\{\hat{&Delta;}(t)^{(b)}, b = 1,...,D\}</i>. Variance estimates for <i>\hat{&Delta;}_S(t,t_0)</i> and <i>\hat{R}_S(t,t_0)</i> are calculated similarly. We construct two versions of the <i>95\%</i> confidence interval for each estimate: one based on a normal approximation confidence interval using the estimated variance and another taking the 2.5th and 97.5th empirical percentile of the perturbed quantities.  In addition, we use Fieller's method to obtain a third confidence interval for <i>R_S(t,t_0)</i> as
</p>
<p style="text-align: center;"><i>&le;ft\{1-r:  \frac{(\hat{&Delta;}_S(t,t_0)-r\hat{&Delta;}(t))^2}{\hat{&sigma;}_{11}-2r\hat&sigma;_{12}+r^2\hat&sigma;_{22}} &le; c_{&alpha;}\right\},</i></p>

<p>where <i>\hat{&Sigma;}=(\hat&sigma;_{ij})_{1&le; i,j&le; 2}</i> and <i>c_&alpha;</i> is the <i>(1-&alpha;)</i>th percentile of
</p>
<p style="text-align: center;"><i>&le;ft\{\frac{\{\hat{&Delta;}^{(b)}_S(t)-(1-\hat R_S(t,t_0))\hat{&Delta;}(t)^{(b)}\}^2}{\hat{&sigma;}_{11}-2(1-\hat R_S(t,t_0))\hat&sigma;_{12}+(1-\hat R_S(t,t_0))^2\hat&sigma;_{22}}, b=1, \cdots, C\right\}</i></p>

<p>where <i>&alpha;=0.05</i>.
</p>
<p>Since the definition of <i>R_S(t,t_0)</i> considers the surrogate information as a combination of both <i>S</i> information and <i>T</i> information up to <i>t_0</i>, a logical inquiry would be how to assess the incremental value of the <i>S</i> information in terms of the proportion of treatment effect explained, when added to <i>T</i> information up to <i>t_0</i>. The proportion of treatment effect explained by <i>T</i> information up to <i>t_0</i> only is denoted as <i>R_T(t,t_0)</i> and is described in the documentation for R.t.surv.estimate. The incremental value of <i>S</i> information is defined as:
</p>
<p style="text-align: center;"><i>
IV_S(t,t_0) = R_S(t,t_0) - R_T(t,t_0) = \frac{&Delta;_T(t,t_0) - &Delta;_S(t,t_0)}{&Delta; (t)}.</i></p>

<p>For estimation of <i>R_T(t_0)</i>, see documentation for R.t.surv.estimate. The quantity <i>IV_S(t,t_0)</i>  is then estimated by <i>\hat{IV}_S(t,t_0) = \hat{R}_S(t,t_0) - \hat{R}_T(t,t_0)</i>. Perturbation-resampling is used for variance estimation and confidence interval construction for this quantity, similar to the other quantities in this package.
</p>
<p>Note that if the observed supports for S are not the same, then <i>\hat{&Lambda;}_1(t| s,t_0)</i> for <i>S_{0i} = s</i> outside the support of <i>S_{1i}</i> may return NA (depending on the bandwidth). If extrapolation = TRUE, then the   <i>\hat{&Lambda;}_1(t| s,t_0)</i> values for these surrogate values are set to the closest non-NA value. If transform = TRUE, then <i>S_{1i}</i> and <i>S_{0i}</i> are transformed such that the new transformed values, <i>S^{tr}_{1i}</i> and <i>S^{tr}_{0i}</i> are defined as: <i>S^{tr}_{gi} = F([S_{gi} - &mu;]/&sigma;)</i> for <i>g=0,1</i> where <i>F(\cdot)</i> is the cumulative distribution function for a standard normal random variable, and <i>&mu;</i> and <i>&sigma;</i> are the sample mean and standard deviation, respectively, of <i>\{(S_{1i}, S_{0i})^T, i \quad s.t. X_{gi} &gt; t_0\}</i>.
</p>


<h3>Value</h3>






<p>A list is returned:
</p>
<table summary="R valueblock">
<tr valign="top"><td><code>delta </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}(t)</i>, described in delta.estimate documentation.</p>
</td></tr>
<tr valign="top"><td><code>delta.s </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}_S(t,t_0)</i>, described above.</p>
</td></tr>
<tr valign="top"><td><code>R.s </code></td>
<td>
<p>the estimate, <i>\hat{R}_S(t,t_0)</i>, described above.</p>
</td></tr>
<tr valign="top"><td><code>delta.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}(t)</i>; if var = TRUE or conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>delta.s.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}_S(t,t_0)</i>; if var = TRUE or conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>R.s.var </code></td>
<td>
<p>the variance estimate of <i>\hat{R}_S(t,t_0)</i>; if var = TRUE or conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.normal.delta</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}(t)</i> based on a normal approximation; if conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.delta</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}(t)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.normal.delta.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_S(t,t_0)</i> based on a normal approximation; if conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.delta.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_S(t,t_0)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.normal.R.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_S(t,t_0)</i> based on a normal approximation; if conf.int = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.R.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_S(t,t_0)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.fieller.R.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_S(t,t_0)</i> based on Fieller's approach, described above; if conf.int = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>delta.t </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}_T(t,t_0)</i>, described above; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>R.t </code></td>
<td>
<p>the estimate, <i>\hat{R}_T(t,t_0)</i>, described above; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>incremental.value</code></td>
<td>
<p>the estimate, <i>\hat{IV}_S(t,t_0)</i>, described above; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>delta.t.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}_T(t,t_0)</i>; if var = TRUE or conf.int = TRUE and  incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>R.t.var </code></td>
<td>
<p>the variance estimate of <i>\hat{R}_T(t,t_0)</i>; if var = TRUE or conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>incremental.value.var </code></td>
<td>
<p>the variance estimate of <i>\hat{IV}_S(t,t_0)</i>; if var = TRUE or conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.normal.delta.t</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_T(t,t_0)</i> based on a normal approximation; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.delta.t</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_T(t,t_0)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.normal.R.t</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_T(t,t_0)</i> based on a normal approximation; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.R.t</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_T(t,t_0)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.fieller.R.t</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_T(t,t_0)</i> based on Fieller's approach, described above; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.normal.iv</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{IV}_S(t,t_0)</i> based on a normal approximation; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.iv</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{IV}_S(t,t_0)</i> based on sample quantiles of the perturbed values, described above; if conf.int = TRUE and incremental.vaue = TRUE.</p>
</td></tr> 
</table>


<h3>Note</h3>

<p>If the treatment effect is not significant, the user will receive the following message: &quot;Warning: it looks like the treatment effect is not significant; may be difficult to interpret the residual treatment effect in this setting&quot;. If the observed support of the surrogate marker for the control group is outside the observed support of the surrogate marker for the treatment group, the user will receive the following message: &quot;Warning: observed supports do not appear equal, may need to consider a transformation or extrapolation&quot;.</p>


<h3>Author(s)</h3>


<p>Layla Parast
</p>


<h3>References</h3>


<p>Parast, L., Cai, T., &amp; Tian, L. (2017). Evaluating surrogate marker information using censored data. Statistics in Medicine, 36(11), 1767-1782.
</p>


<h3>Examples</h3>

<pre>
data(d_example_surv)
names(d_example_surv)








</pre>


</body></html>
