R: Assess surrogacy in the causal-inference single-trial setting...

ICA.BinCont {Surrogate}

R Documentation

Assess surrogacy in the causal-inference single-trial setting in the binary-continuous case

Description

The function ICA.BinCont quantifies surrogacy in the single-trial setting within the causal-inference framework (individual causal association) when the surrogate endpoint is continuous (normally distributed) and the true endpoint is a binary outcome. For details, see Alonso Abad et al. (2023).

Usage

ICA.BinCont(Dataset, Surr, True, Treat, 
  BS=FALSE,
  G_pi_10=c(0,1), 
  G_rho_01_00=c(-1,1), 
  G_rho_01_01=c(-1,1), 
  G_rho_01_10=c(-1,1), 
  G_rho_01_11=c(-1,1), 
  Theta.S_0, 
  Theta.S_1, 
  M=1000, Seed=123, 
  Monotonicity=FALSE,
  Independence=FALSE,
  HAA=FALSE,
  Cond_ind=FALSE,
  Plots=TRUE, Save.Plots="No", Show.Details=FALSE)

Arguments

`Dataset`	A `data.frame` that should consist of one line per patient. Each line contains (at least) a surrogate value, a true endpoint value, and a treatment indicator.
`Surr`	The name of the variable in `Dataset` that contains the surrogate endpoint values.
`True`	The name of the variable in `Dataset` that contains the true endpoint values.
`Treat`	The name of the variable in `Dataset` that contains the treatment indicators. The treatment indicator should be coded as `1` for the experimental group and `-1` for the control group.
`BS`	Logical. If `BS=TRUE`, the sampling variability is accounted for in the analysis by using a bootstrap procedure. Default `BS=FALSE`.
`G_pi_10`	The lower and upper limits of the uniform distribution from which the probability parameter `\pi_{10}` is sampled. Default `c(0,1)`. When `Monotonicity=TRUE` the values of these limits are set as `c(0,0)`.
`G_rho_01_00`	The lower and upper limits of the uniform distribution from which the association parameter `\rho_{01}^{00}` is sampled. Default `c(-1,1)`.
`G_rho_01_01`	The lower and upper limits of the uniform distribution from which the association parameter `\rho_{01}^{01}` is sampled. Default `c(-1,1)`.
`G_rho_01_10`	The lower and upper limits of the uniform distribution from which the association parameter `\rho_{01}^{10}` is sampled. Default `c(-1,1)`.
`G_rho_01_11`	The lower and upper limits of the uniform distribution from which the association parameter `\rho_{01}^{11}` is sampled. Default `c(-1,1)`.
`Theta.S_0`	The starting values of the means and standard deviations for the mixture distribution of the surrogate endpoint in the control group. The argument should contain eight values, where the first four values represent the starting values for the means and the last four values represent the starting values for the standard deviations. These starting values should be approximated based on the data on hand. Example: `Theta.S_0=c(-10,-5,5,10,10,10,10,10)`.
`Theta.S_1`	The starting values of the means and standard deviations for the mixture distribution of the surrogate endpoint in the treatment group. The argument should contain eight values, where the first four values represent the starting values for the means and the last four values represent the starting values for the standard deviations. These starting values should be approximated based on the data on hand. Example: `Theta.S_1=c(-10,-5,5,10,10,10,10,10)`.
`M`	The number of Monte Carlo iterations. Default `M=1000`.
`Seed`	The random seed to be used in the analysis (for reproducibility). Default `Seed=123`.
`Monotonicity`	Logical. If `Monotonicity=TRUE`, the analysis is performed assuming monotonicity, i.e. `P(T_1 < T_0) = 0`. Default `Monotonicity=FALSE`.
`Independence`	Logical. If `Independence=TRUE`, the analysis is performed assuming independence between the treatment effect in both groups, i.e. `\pi_{ij} = \pi_{i.} \times \pi_{.j}`. Default `Independence=FALSE`.
`HAA`	Logical. If `HAA=TRUE`, the analysis is performed assuming homogeneous association, i.e. `\rho_{01}^{ij} = \rho_{01}`. Default `HAA=FALSE`.
`Cond_ind`	Logical. If `Cond_ind=TRUE`, the analysis is performed assuming conditional independence, i.e. `\rho_{01} = 0`. Default `Cond_ind=FALSE`.
`Plots`	Logical. Should histograms of `S_0` (surrogate endpoint in control group) and `S_1` (surrogate endpoint in experimental treatment group) be provided together with density of fitted mixtures? Default `Plots=TRUE`.
`Save.Plots`	Should the plots (see previous item) be saved? If `Save.Plots="No"`, no plots are saved. If plots have to be saved, replace `"No"` by the desired location, e.g., `Save.Plots="C:/"`. Default `Save.Plots="No"`.
`Show.Details`	Should some details regarding the availability of some output from the function be displayed in the console when the analysis is running? Setting `Show.Details=TRUE` could be useful for debugging procedure (if any). Default `Show.Details=FALSE`.

Value

An object of class ICA.BinCont with components,

`R2_H`	The vector of the `R_H^2` values.
`pi_00`	The vector of `\pi_{00}^T` values.
`pi_01`	The vector of `\pi_{01}^T` values.
`pi_10`	The vector of `\pi_{10}^T` values.
`pi_11`	The vector of `\pi_{11}^T` values.
`G_rho_01_00`	The vector of the `\rho_{01}^{00}` values.
`G_rho_01_01`	The vector of the `\rho_{01}^{01}` values.
`G_rho_01_10`	The vector of the `\rho_{01}^{10}` values.
`G_rho_01_11`	The vector of the `\rho_{01}^{11}` values.
`pi_Delta_T_min1`	The vector of the `\pi_{-1}^{\Delta T}` values.
`pi_Delta_T_0`	The vector of the `\pi_{0}^{\Delta T}` values.
`pi_Delta_T_1`	The vector of the `\pi_{1}^{\Delta T}` values.
`pi_0_00`	The vector of `\pi_{00}` values of `f(S_0)`.
`pi_0_01`	The vector of `\pi_{01}` values of `f(S_0)`.
`pi_0_10`	The vector of `\pi_{10}` values of `f(S_0)`.
`pi_0_11`	The vector of `\pi_{11}` values of `f(S_0)`.
`mu_0_00`	The vector of mean `\mu_{0}^{00}` values of `f(S_0)`.
`mu_0_01`	The vector of mean `\mu_{0}^{01}` values of `f(S_0)`.
`mu_0_10`	The vector of mean `\mu_{0}^{10}` values of `f(S_0)`.
`mu_0_11`	The vector of mean `\mu_{0}^{11}` values of `f(S_0)`.
`sigma2_00_00`	The vector of variance `\sigma_{00}^{00}` values of `f(S_0)`.
`sigma2_00_01`	The vector of variance `\sigma_{00}^{01}` values of `f(S_0)`.
`sigma2_00_10`	The vector of variance `\sigma_{00}^{10}` values of `f(S_0)`.
`sigma2_00_11`	The vector of variance `\sigma_{00}^{11}` values of `f(S_0)`.
`pi_1_00`	The vector of `\pi_{00}` values of `f(S_1)`.
`pi_1_01`	The vector of `\pi_{01}` values of `f(S_1)`.
`pi_1_10`	The vector of `\pi_{10}` values of `f(S_1)`.
`pi_1_11`	The vector of `\pi_{11}` values of `f(S_1)`.
`mu_1_00`	The vector of mean `\mu_{1}^{00}` values of `f(S_1)`.
`mu_1_01`	The vector of mean `\mu_{1}^{01}` values of `f(S_1)`.
`mu_1_10`	The vector of mean `\mu_{1}^{10}` values of `f(S_1)`.
`mu_1_11`	The vector of mean `\mu_{1}^{11}` values of `f(S_1)`.
`sigma2_11_00`	The vector of variance `\sigma_{11}^{00}` values of `f(S_1)`.
`sigma2_11_01`	The vector of variance `\sigma_{11}^{01}` values of `f(S_1)`.
`sigma2_11_10`	The vector of variance `\sigma_{11}^{10}` values of `f(S_1)`.
`sigma2_11_11`	The vector of variance `\sigma_{11}^{11}` values of `f(S_1)`.
`mean_Y_S0`	The vector of mean `\mu_{0}` values of `f(S_0)`.
`mean_Y_S1`	The vector of mean `\mu_{1}` values of `f(S_1)`.
`var_Y_S0`	The vector of variance `\sigma_{00}` values of `f(S_0)`.
`var_Y_S1`	The vector of variance `\sigma_{11}` values of `f(S_1)`.
`dev_S0`	The vector of deviance values of the normal mixture for `f(S_0)`.
`dev_S1`	The vector of deviance values of the normal mixture for `f(S_1)`.
`code_nlm_0`	An integer indicating why the optimization process to estimate the mixture normal parameters of `f(S_0)` terminated: 1) relative gradient is close to zero, current iterate is probably solution; 2) successive iterates within tolerance, current iterate is probably solution; 3) last global step failed to locate a point lower than the estimate, the estimate might be an approximate local minimum of the function.
`code_nlm_1`	An integer indicating why the optimization process to estimate the mixture normal parameters of `f(S_1)` terminated: 1) relative gradient is close to zero, current iterate is probably solution; 2) successive iterates within tolerance, current iterate is probably solution; 3) last global step failed to locate a point lower than the estimate, the estimate might be an approximate local minimum of the function.
`mean.S0`	The mean of `S_0`.
`var.S0`	The variance of `S_0`.
`mean.S1`	The mean of `S_1`.
`var.S1`	The variance of `S_1`.

Author(s)

Wim Van der Elst, Fenny Ong, Ariel Alonso, and Geert Molenberghs

References

Alonso Abad, A., Ong, F., Stijven, F., Van der Elst, W., Molenberghs, G., Van Keilegom, I., Verbeke, G., & Callegaro, A. (2023). An information-theoretic approach for the assessment of a continuous outcome as a surrogate for a binary true endpoint based on causal inference: Application to vaccine evaluation.

Examples

## Not run: # Time consuming code part
data(Schizo)
Fit <- ICA.BinCont(Dataset = Schizo, Surr = BPRS, True = PANSS_Bin, 
Theta.S_0=c(-10,-5,5,10,10,10,10,10), Theta.S_1=c(-10,-5,5,10,10,10,10,10), 
Treat=Treat, M=50, Seed=1)

summary(Fit)
plot(Fit)

## End(Not run)

[Package Surrogate version 3.3.0 Index]