<!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 augmented estimator of the proportion of...</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 Aug.R.s.surv.estimate"><tr><td>Aug.R.s.surv.estimate</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>
Calculates the augmented estimator of 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 augmented version of 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>.  Variance estimates and 95 % confidence intervals for the augmented estimates are provided automatically;  three versions of the confidence interval 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>
Aug.R.s.surv.estimate(xone, xzero, deltaone, deltazero, sone, szero, t, 
weight.perturb = NULL, landmark, extrapolate = FALSE, transform = FALSE, 
basis.delta.one, basis.delta.zero, basis.delta.s.one = NULL, 
basis.delta.s.zero = NULL, 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>basis.delta.one</code></td>
<td>

<p>either a vector of length <i>n_1</i> or a matrix with <i>n_1</i> rows; this is the basis transformation used for augmentation of <i>\hat{&Delta;}(t)</i> for treated observations only, all values must be numeric
</p>
</td></tr>
<tr valign="top"><td><code>basis.delta.zero</code></td>
<td>

<p>either a vector of length <i>n_0</i> or a matrix with <i>n_0</i> rows; this is the basis transformation used for augmentation of <i>\hat{&Delta;}(t)</i> for control observations only, all values must be numeric
</p>
</td></tr>
<tr valign="top"><td><code>basis.delta.s.one</code></td>
<td>

<p>either a vector of length <i>n_1</i> or a matrix with <i>n_1</i> rows; this is the basis transformation used for augmentation of <i>\hat{&Delta;}_S(t,t_0)</i> for treated observations only, all values must be numeric; default is to assume this is the same as basis.delta.one i.e. that the same basis transformation is used for both quantities
</p>
</td></tr>
<tr valign="top"><td><code>basis.delta.s.zero</code></td>
<td>

<p>either a vector of length <i>n_0</i> or a matrix with <i>n_0</i> rows; this is the basis transformation used for augmentation of <i>\hat{&Delta;}_S(t,t_0)</i> for control observations only, all values must be numeric; default is to assume this is the same as basis.delta.zero i.e. that the same basis transformation is used for both quantities
</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>Please see R.s.surv.estimate documention for details about the estimates before augmentation is performed. Recent work has shown that augmentation can lead to improvements in efficiency by taking advantage of the association between baseline information, denoted here as <i>Z</i>, and the primary outcome. This function calculates the augmented estimates of the quantities of interest. For example, the augmented version of <i> \hat{&Delta;}(t)</i> is defined as:
</p>
<p style="text-align: center;"><i> \hat{&Delta;}(t)^{AUG} =   \hat{&Delta;}(t) + &gamma; \{n_1^{-1}&sum;_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}&sum;_{i=1}^{n_0}h(Z_{0i}) \} </i></p>
 
<p>where <i>Z_{gi}, i=1, 2, \cdots, n_g</i> are i.i.d. random vectors of baseline covariates from treatment group <i>g</i> and <i>h(\cdot)</i> is a basis transformation given a priori.  Due to treatment randomization, <i> \{n_1^{-1}&sum;_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}&sum;_{i=1}^{n_0}h(Z_{0i}) \}</i> converges to zero in probability as the sample size goes to infinity and thus the augmented estimator converges to the same limit as the original counterparts.  The quantity <i>&gamma;</i> is selected such that the variance of <i> \hat{&Delta;}(t)^{AUG}</i> is minimized.  That is,  <i>&gamma; = (&Xi;_{12}) ( &Xi;_{22} ) ^{-1}</i> where
</p>
<p style="text-align: center;"><i> &Xi;_{12} = \mbox{cov}  \{ \hat{&Delta;}(t), n_1^{-1}&sum;_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}&sum;_{i=1}^{n_0}h(Z_{0i}) \},</i></p>

<p style="text-align: center;"><i>  &Xi;_{22} = \mbox{var}  \{n_1^{-1}&sum;_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}&sum;_{i=1}^{n_0}h(Z_{0i})\}</i></p>

<p>and thus we can obtain <i>\hat{&Delta;}(t)^{AUG}</i> by replacing <i>&gamma;</i> with a consistent estimator, <i>\hat{&gamma;}</i> obtained using perturbation-resampling. A similar approach is used to obtain  <i>\hat{&Delta;}_S(t)^{AUG}</i> and thus construct
</p>
<p style="text-align: center;"><i>\hat{R}_S(t,t_0)^{AUG}=1-\frac{\hat{&Delta;}_S(t,t_0)^{AUG}}{\hat{&Delta;}(t)^{AUG}}.</i></p>
<p> When only a single <i>Z_{gi}</i> is provided in the basis argument, the following basis is used in this function: <i>h(Z_{gi}) = (1, Z_{gi}, Z_{gi}^2)'.</i>
</p>


<h3>Value</h3>

<p>A list is returned:
</p>
<table summary="R valueblock">
<tr valign="top"><td><code>aug.delta </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}(t)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>aug.delta.s </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}_S(t,t_0)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>aug.R.s </code></td>
<td>
<p>the estimate, <i>\hat{R}_S(t,t_0)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>aug.delta.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}(t)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>aug.delta.s.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}_S(t,t_0)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>aug.R.s.var </code></td>
<td>
<p>the variance estimate of <i>\hat{R}_S(t,t_0)^{AUG}</i>.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.normal.aug.delta</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}(t)^{AUG}</i> based on a normal approximation.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.aug.delta</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}(t)^{AUG}</i> based on sample quantiles of the perturbed values.</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.normal.aug.delta.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_S(t,t_0)^{AUG}</i> based on a normal approximation.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.aug.delta.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{&Delta;}_S(t,t_0)^{AUG}</i> based on sample quantiles of the perturbed values.</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)^{AUG}</i> based on a normal approximation.</p>
</td></tr>
<tr valign="top"><td><code>conf.int.quantile.aug.R.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_S(t,t_0)^{AUG}</i> based on sample quantiles of the perturbed values..</p>
</td></tr> 
<tr valign="top"><td><code>conf.int.fieller.aug.R.s</code></td>
<td>
<p>a vector of size 2; the 95% confidence interval for <i>\hat{R}_S(t,t_0)^{AUG}</i> based on Fieller's approach.</p>
</td></tr> 
<tr valign="top"><td><code>aug.delta.t </code></td>
<td>
<p>the estimate, <i>\hat{&Delta;}_T(t,t_0)^{AUG}</i>; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.R.t </code></td>
<td>
<p>the estimate, <i>\hat{R}_T(t,t_0)^{AUG}</i>; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.incremental.value</code></td>
<td>
<p>the estimate, <i>\hat{IV}_S(t,t_0)^{AUG}</i>; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.delta.t.var </code></td>
<td>
<p>the variance estimate of <i>\hat{&Delta;}_T(t,t_0)^{AUG}</i>; if  incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.R.t.var </code></td>
<td>
<p>the variance estimate of <i>\hat{R}_T(t,t_0)^{AUG}</i>; if  incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>aug.incremental.value.var </code></td>
<td>
<p>the variance estimate of <i>\hat{IV}_S(t,t_0)^{AUG}</i>; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on a normal approximation; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on sample quantiles of the perturbed values; if  incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on a normal approximation; if  incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on sample quantiles of the perturbed values; if  incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on Fieller's approach, described above; if incremental.vaue = TRUE.</p>
</td></tr> 
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on a normal approximation; if incremental.vaue = TRUE.</p>
</td></tr>
<tr valign="top"><td><code>aug.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)^{AUG}</i> based on sample quantiles of the perturbed values; if  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>Tian L, Cai T, Zhao L,Wei L. On the covariate-adjusted estimation for an overall treatment difference with data from a randomized comparative clinical trial. Biostatistics 2012; 13(2): 256-273.
</p>
<p>Garcia TP, Ma Y, Yin G. Efficiency improvement in a class of survival models through model-free covariate incorporation. Lifetime Data Analysis 2011; 17(4): 552-565. 
</p>
<p>Zhang M, Tsiatis AA, Davidian M. Improving efficiency of inferences in randomized clinical trials using auxiliary covariates. Biometrics 2008; 64(3): 707-715.
</p>
<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>
#computationally intensive
#Aug.R.s.surv.estimate(xone = d_example_surv$x1, xzero = d_example_surv$x0,  
#deltaone = d_example_surv$delta1, deltazero = d_example_surv$delta0, 
#sone = d_example_surv$s1, szero = d_example_surv$s0, t=3, landmark = 1, 
#basis.delta.one = d_example_surv$z1 , basis.delta.zero = d_example_surv$z0)

</pre>


</body></html>
