ICA_contcont_long_shared_ri: Assess surrogacy in the information-theoretic...

In Surrogate: Evaluation of Surrogate Endpoints in Clinical Trials

Assess surrogacy in the information-theoretic causal-inference framework (Individual Causal Association, ICA) for a continuous surrogate and true endpoint measured repeatedly over time in a single-trial setting

Description

This function quantifies surrogacy under linear model with shared random intercepts with separable residual covariance structure. See Details below.

Usage

ICA_contcont_long_shared_ri(
  V0,
  V1,
  D0_variance,
  D1_variance,
  times,
  correlation = c("exponential", "compound_symmetry", "independence"),
  temporal_rho = NULL,
  grid_V = seq(-1, 1, by = 0.1),
  grid_D = seq(-1, 1, by = 0.1),
  return_candidates = FALSE,
  tol = 1e-12
)

Arguments

V0, V1	Treatment-specific residual 2 x 2 covariance matrices for T,S.
D0_variance, D1_variance	Treatment-specific shared random-intercept variances.
times	Clinical evaluation time points.
correlation	Temporal correlation structures such as exponential, compound_symmetry, and independence.
temporal_rho	Temporal-correlation parameter. Ignored when correlation = "independence"
grid_V	Sensitivity grid for unidentified residual correlations.
grid_D	Sensitivity grid for unidentified random-intercept correlations.
return_candidates	Logical. If TRUE, the retained admissible covariance completion candidates for the residual and random-intercept components are returned.
tol	Numerical tolerance used when checking positive definiteness and validating ICA values.

Value

• Num.Pos.Def.V: An object of class numeric that contains the number of positive definite V matrices.

• Num.Pos.Def.D: An object of class numeric that contains the number of positive definite D matrices.

• Num.Pos.Def.Pairs: An object of class numeric that contains the number of valid V-D pairs used in the final calculations.

• R2_Lambda: A scalar or vector that contains the individual causal association R_{\Lambda}^2.

• V_candidates: retained residual covariance candidates, if requested.

• D_candidates: retained random-intercept covariance candidates, if requested.

Shared random intercepts within treatment arm:

T_{0j} = x_{T0j} \gamma_{T0} + b_{T0}+ \varepsilon_{T0j}

T_{1j} = x_{T1j} \gamma_{T1} + b_{T1}+ \varepsilon_{T1j}

S_{0j} = x_{S0j} \gamma_{S0} + b_{S0}+ \varepsilon_{S0j}

S_{1j} = x_{S1j} \gamma_{S1} + b_{S1}+ \varepsilon_{S1j}

with d = (b_0, b_1)^\top. Let \delta b=b_1-b_0 and d_\delta=\mathrm{Var}(\delta b)=d_{00}+d_{11}-2d_{01}.

The marginal covariance matrix of the individual causal treatment effects:

\Sigma_\Delta= \Sigma_u \otimes \R + d_\delta 1_p 1_p^\top

Under the shared-intercept model specified, the ICA metric is given by:

R_{\Lambda}^{2}=1-(1-\rho_{u}^{2})^{p-1}\,(1-\rho_{u\delta}^{2})

where

\rho_{u}^{2} =\frac{u_{12}^{2}}{u_{11}\,u_{22}}, \qquad \rho_{u\delta}^{2} =\frac{(u_{12}+\alpha\,d_{\delta})^{2}} {(u_{11}+\alpha\,d_{\delta})(u_{22}+\alpha\,d_{\delta})}, \qquad\mbox{and}\qquad \alpha=1_{p}^{\top}R^{-1}1_{p}

References

Deliorman, G., Pardo, M. C., Van der Elst W., Molenberghs G., & Alonso, A. (submitted in 2026). Assessing Surrogate Endpoints in Longitudinal Studies: An Information-Theoretic Causal Inference Approach.

Examples

#Example outputs

V0 <- matrix(c(0.03025730, 0.02925077,
               0.02925077, 0.03327464 ),
              nrow = 2, byrow = TRUE,
              dimnames = list(c("T", "S"), c("T", "S")))


V1 <- matrix(c(0.03397819, 0.03390776,
               0.03390776, 0.03849923),
               nrow = 2, byrow = TRUE,
               dimnames = list(c("T", "S"), c("T", "S")))

# Example run
ica_shared_ri<- ICA_contcont_long_shared_ri(V0 = V0,  V1 = V1,
                            D0_variance = 0.02160313,
                            D1_variance = 0.03115772,
                            times = c(1,2,4,6,8),
                            correlation  = "exponential",
                            temporal_rho = 0.7629443,
                            grid_V = seq(-1, 1, by = 1),
                            grid_D = seq(-1, 1, by = 1),
                            return_candidates = FALSE,
                            tol = 1e-12)

summary_longitudinal_ica(ica_shared_ri)

Surrogate documentation built on Oct. 16, 2026, 9:07 a.m.