Aug.R.s.surv.estimate: Calculates the augmented estimator of the proportion of...
In Rsurrogate: Robust Estimation of the Proportion of Treatment Effect Explained by Surrogate Marker Information
Description
Usage
Arguments
Details
Value
Note
Author(s)
References
Examples
View source: R/Functions_Rsurrogate.R
Description
This function calculates the augmented version of the proportion of treatment effect on the primary outcome explained by the surrogate marker information measured at t_0 and primary outcome information up to t_0. 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.
Usage
1
2
3
4
Arguments
xone
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.
xzero
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.
deltaone
numeric vector, the event indicators for the treatment group, D = I(T<C) where T is the time of the primary outcome and C is the censoring time.
deltazero
numeric vector, the event indicators for the control group, D = I(T<C) where T is the time of the primary outcome and C is the censoring time.
sone
numeric vector; surrogate marker measurement at t_0 for treated observations, assumed to be continuous. If X_{1i}<t_0, then the surrogate marker measurement should be NA.
szero
numeric vector; surrogate marker measurement at t_0 for control observations, assumed to be continuous. If X_{1i}<t_0, then the surrogate marker measurement should be NA.
t
the time of interest.
weight.perturb
weights used for perturbation resampling.
landmark
the landmark time t_0 or time of surrogate marker measurement.
extrapolate
TRUE or FALSE; indicates whether the user wants to use extrapolation.
transform
TRUE or FALSE; indicates whether the user wants to use a transformation for the surrogate marker.
basis.delta.one
either a vector of length n_1 or a matrix with n_1 rows; this is the basis transformation used for augmentation of \hat{Δ}(t) for treated observations only, all values must be numeric
basis.delta.zero
either a vector of length n_0 or a matrix with n_0 rows; this is the basis transformation used for augmentation of \hat{Δ}(t) for control observations only, all values must be numeric
basis.delta.s.one
either a vector of length n_1 or a matrix with n_1 rows; this is the basis transformation used for augmentation of \hat{Δ}_S(t,t_0) 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
basis.delta.s.zero
either a vector of length n_0 or a matrix with n_0 rows; this is the basis transformation used for augmentation of \hat{Δ}_S(t,t_0) 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
incremental.value
TRUE or FALSE; indicates whether the user would like to see the incremental value of the surrogate marker information, default is FALSE.
approx
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.
Details
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 Z, and the primary outcome. This function calculates the augmented estimates of the quantities of interest. For example, the augmented version of \hat{Δ}(t) is defined as:
\hat{Δ}(t)^{AUG} = \hat{Δ}(t) + γ \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \}
where Z_{gi}, i=1, 2, \cdots, n_g are i.i.d. random vectors of baseline covariates from treatment group g and h(\cdot) is a basis transformation given a priori. Due to treatment randomization, \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \} 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 γ is selected such that the variance of \hat{Δ}(t)^{AUG} is minimized. That is, γ = (Ξ_{12}) ( Ξ_{22} ) ^{-1} where
Ξ_{12} = \mbox{cov} \{ \hat{Δ}(t), n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \},
Ξ_{22} = \mbox{var} \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i})\}
and thus we can obtain \hat{Δ}(t)^{AUG} by replacing γ with a consistent estimator, \hat{γ} obtained using perturbation-resampling. A similar approach is used to obtain \hat{Δ}_S(t)^{AUG} and thus construct
\hat{R}_S(t,t_0)^{AUG}=1-\frac{\hat{Δ}_S(t,t_0)^{AUG}}{\hat{Δ}(t)^{AUG}}.
When only a single Z_{gi} is provided in the basis argument, the following basis is used in this function: h(Z_{gi}) = (1, Z_{gi}, Z_{gi}^2)'.
Value
A list is returned:
aug.delta
the estimate, \hat{Δ}(t)^{AUG}.
aug.delta.s
the estimate, \hat{Δ}_S(t,t_0)^{AUG}.
aug.R.s
the estimate, \hat{R}_S(t,t_0)^{AUG}.
aug.delta.var
the variance estimate of \hat{Δ}(t)^{AUG}.
aug.delta.s.var
the variance estimate of \hat{Δ}_S(t,t_0)^{AUG}.
aug.R.s.var
the variance estimate of \hat{R}_S(t,t_0)^{AUG}.
conf.int.normal.aug.delta
a vector of size 2; the 95% confidence interval for \hat{Δ}(t)^{AUG} based on a normal approximation.
conf.int.quantile.aug.delta
a vector of size 2; the 95% confidence interval for \hat{Δ}(t)^{AUG} based on sample quantiles of the perturbed values.
conf.int.normal.aug.delta.s
a vector of size 2; the 95% confidence interval for \hat{Δ}_S(t,t_0)^{AUG} based on a normal approximation.
conf.int.quantile.aug.delta.s
a vector of size 2; the 95% confidence interval for \hat{Δ}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values.
conf.int.normal.R.s
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on a normal approximation.
conf.int.quantile.aug.R.s
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values..
conf.int.fieller.aug.R.s
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on Fieller's approach.
aug.delta.t
the estimate, \hat{Δ}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.R.t
the estimate, \hat{R}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.incremental.value
the estimate, \hat{IV}_S(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.delta.t.var
the variance estimate of \hat{Δ}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.R.t.var
the variance estimate of \hat{R}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.incremental.value.var
the variance estimate of \hat{IV}_S(t,t_0)^{AUG}; if incremental.vaue = TRUE.
aug.conf.int.normal.delta.t
a vector of size 2; the 95% confidence interval for \hat{Δ}_T(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE.
aug.conf.int.quantile.delta.t
a vector of size 2; the 95% confidence interval for \hat{Δ}_T(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE.
aug.conf.int.normal.R.t
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE.
aug.conf.int.quantile.R.t
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE.
aug.conf.int.fieller.R.t
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on Fieller's approach, described above; if incremental.vaue = TRUE.
aug.conf.int.normal.iv
a vector of size 2; the 95% confidence interval for \hat{IV}_S(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE.
aug.conf.int.quantile.iv
a vector of size 2; the 95% confidence interval for \hat{IV}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE.
Note
If the treatment effect is not significant, the user will receive the following message: "Warning: it looks like the treatment effect is not significant; may be difficult to interpret the residual treatment effect in this setting". 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: "Warning: observed supports do not appear equal, may need to consider a transformation or extrapolation".
Author(s)
Layla Parast
References
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.
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.
Zhang M, Tsiatis AA, Davidian M. Improving efficiency of inferences in randomized clinical trials using auxiliary covariates. Biometrics 2008; 64(3): 707-715.
Parast, L., Cai, T., & Tian, L. (2017). Evaluating surrogate marker information using censored data. Statistics in Medicine, 36(11), 1767-1782.
Examples
1
2
3
4
5
#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)
Rsurrogate documentation built on Nov. 14, 2021, 9:07 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Note Author(s) References Examples
View source: R/Functions_Rsurrogate.R
Description
This function calculates the augmented version of the proportion of treatment effect on the primary outcome explained by the surrogate marker information measured at t_0 and primary outcome information up to t_0. 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.
Usage
1 2 3 4 |
Arguments
xone |
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. |
xzero |
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. |
deltaone |
numeric vector, the event indicators for the treatment group, D = I(T<C) where T is the time of the primary outcome and C is the censoring time. |
deltazero |
numeric vector, the event indicators for the control group, D = I(T<C) where T is the time of the primary outcome and C is the censoring time. |
sone |
numeric vector; surrogate marker measurement at t_0 for treated observations, assumed to be continuous. If X_{1i}<t_0, then the surrogate marker measurement should be NA. |
szero |
numeric vector; surrogate marker measurement at t_0 for control observations, assumed to be continuous. If X_{1i}<t_0, then the surrogate marker measurement should be NA. |
t |
the time of interest. |
weight.perturb |
weights used for perturbation resampling. |
landmark |
the landmark time t_0 or time of surrogate marker measurement. |
extrapolate |
TRUE or FALSE; indicates whether the user wants to use extrapolation. |
transform |
TRUE or FALSE; indicates whether the user wants to use a transformation for the surrogate marker. |
basis.delta.one |
either a vector of length n_1 or a matrix with n_1 rows; this is the basis transformation used for augmentation of \hat{Δ}(t) for treated observations only, all values must be numeric |
basis.delta.zero |
either a vector of length n_0 or a matrix with n_0 rows; this is the basis transformation used for augmentation of \hat{Δ}(t) for control observations only, all values must be numeric |
basis.delta.s.one |
either a vector of length n_1 or a matrix with n_1 rows; this is the basis transformation used for augmentation of \hat{Δ}_S(t,t_0) 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 |
basis.delta.s.zero |
either a vector of length n_0 or a matrix with n_0 rows; this is the basis transformation used for augmentation of \hat{Δ}_S(t,t_0) 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 |
incremental.value |
TRUE or FALSE; indicates whether the user would like to see the incremental value of the surrogate marker information, default is FALSE. |
approx |
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. |
Details
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 Z, and the primary outcome. This function calculates the augmented estimates of the quantities of interest. For example, the augmented version of \hat{Δ}(t) is defined as:
\hat{Δ}(t)^{AUG} = \hat{Δ}(t) + γ \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \}
where Z_{gi}, i=1, 2, \cdots, n_g are i.i.d. random vectors of baseline covariates from treatment group g and h(\cdot) is a basis transformation given a priori. Due to treatment randomization, \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \} 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 γ is selected such that the variance of \hat{Δ}(t)^{AUG} is minimized. That is, γ = (Ξ_{12}) ( Ξ_{22} ) ^{-1} where
Ξ_{12} = \mbox{cov} \{ \hat{Δ}(t), n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i}) \},
Ξ_{22} = \mbox{var} \{n_1^{-1}∑_{i=1}^{n_1}h(Z_{1i})-n_0^{-1}∑_{i=1}^{n_0}h(Z_{0i})\}
and thus we can obtain \hat{Δ}(t)^{AUG} by replacing γ with a consistent estimator, \hat{γ} obtained using perturbation-resampling. A similar approach is used to obtain \hat{Δ}_S(t)^{AUG} and thus construct
\hat{R}_S(t,t_0)^{AUG}=1-\frac{\hat{Δ}_S(t,t_0)^{AUG}}{\hat{Δ}(t)^{AUG}}.
When only a single Z_{gi} is provided in the basis argument, the following basis is used in this function: h(Z_{gi}) = (1, Z_{gi}, Z_{gi}^2)'.
Value
A list is returned:
aug.delta |
the estimate, \hat{Δ}(t)^{AUG}. |
aug.delta.s |
the estimate, \hat{Δ}_S(t,t_0)^{AUG}. |
aug.R.s |
the estimate, \hat{R}_S(t,t_0)^{AUG}. |
aug.delta.var |
the variance estimate of \hat{Δ}(t)^{AUG}. |
aug.delta.s.var |
the variance estimate of \hat{Δ}_S(t,t_0)^{AUG}. |
aug.R.s.var |
the variance estimate of \hat{R}_S(t,t_0)^{AUG}. |
conf.int.normal.aug.delta |
a vector of size 2; the 95% confidence interval for \hat{Δ}(t)^{AUG} based on a normal approximation. |
conf.int.quantile.aug.delta |
a vector of size 2; the 95% confidence interval for \hat{Δ}(t)^{AUG} based on sample quantiles of the perturbed values. |
conf.int.normal.aug.delta.s |
a vector of size 2; the 95% confidence interval for \hat{Δ}_S(t,t_0)^{AUG} based on a normal approximation. |
conf.int.quantile.aug.delta.s |
a vector of size 2; the 95% confidence interval for \hat{Δ}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values. |
conf.int.normal.R.s |
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on a normal approximation. |
conf.int.quantile.aug.R.s |
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values.. |
conf.int.fieller.aug.R.s |
a vector of size 2; the 95% confidence interval for \hat{R}_S(t,t_0)^{AUG} based on Fieller's approach. |
aug.delta.t |
the estimate, \hat{Δ}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.R.t |
the estimate, \hat{R}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.incremental.value |
the estimate, \hat{IV}_S(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.delta.t.var |
the variance estimate of \hat{Δ}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.R.t.var |
the variance estimate of \hat{R}_T(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.incremental.value.var |
the variance estimate of \hat{IV}_S(t,t_0)^{AUG}; if incremental.vaue = TRUE. |
aug.conf.int.normal.delta.t |
a vector of size 2; the 95% confidence interval for \hat{Δ}_T(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE. |
aug.conf.int.quantile.delta.t |
a vector of size 2; the 95% confidence interval for \hat{Δ}_T(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE. |
aug.conf.int.normal.R.t |
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE. |
aug.conf.int.quantile.R.t |
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE. |
aug.conf.int.fieller.R.t |
a vector of size 2; the 95% confidence interval for \hat{R}_T(t,t_0)^{AUG} based on Fieller's approach, described above; if incremental.vaue = TRUE. |
aug.conf.int.normal.iv |
a vector of size 2; the 95% confidence interval for \hat{IV}_S(t,t_0)^{AUG} based on a normal approximation; if incremental.vaue = TRUE. |
aug.conf.int.quantile.iv |
a vector of size 2; the 95% confidence interval for \hat{IV}_S(t,t_0)^{AUG} based on sample quantiles of the perturbed values; if incremental.vaue = TRUE. |
Note
If the treatment effect is not significant, the user will receive the following message: "Warning: it looks like the treatment effect is not significant; may be difficult to interpret the residual treatment effect in this setting". 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: "Warning: observed supports do not appear equal, may need to consider a transformation or extrapolation".
Author(s)
Layla Parast
References
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.
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.
Zhang M, Tsiatis AA, Davidian M. Improving efficiency of inferences in randomized clinical trials using auxiliary covariates. Biometrics 2008; 64(3): 707-715.
Parast, L., Cai, T., & Tian, L. (2017). Evaluating surrogate marker information using censored data. Statistics in Medicine, 36(11), 1767-1782.
Examples
1 2 3 4 5 | #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)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.