ICA_contcont_long_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

The function quantifies surrogacy under linear model with subject-specific random intercepts with separable residual covariance structure. See Details below.

Usage

ICA_contcont_long_ri(
  V0,
  V1,
  D0,
  D1,
  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, D1	Treatment-specific random-intercept 2 x 2 covariance matrices for T,S.
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.

Random intercepts with separable residual covariance structure:

The evolution of y_j over time is defined using a linear model with subject-specific random intercept for each potential outcome.

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}

It can be written as y=x \gamma + b+ \varepsilon where b \sim N(0, D) with D an unstructured 4 \times 4 covariance matrix and \varepsilon \sim N(0, \Sigma). The marginal model follows that y \sim N(0, \Sigma_y) where \Sigma_y= zDz+ \Sigma with \Sigma = R \otimes V. V is assumed to be unstructured and invariant across time, and R reflects a general correlation matrix.

The marginal covariance matrix of the individual causal treatment effects:

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

with \Sigma_u=QVQ^\top and \Sigma_D=QDQ^\top a 2\times 2 matrix. Equivalently, \Sigma_{\Delta} has blocks

\Sigma_{\Delta T\Delta T}=d_{11}(1_{p}1^\top_{p})+u_{11}R,\quad \Sigma_{\Delta T\Delta S}=d_{12}(1_{p}1^\top_{p})+u_{12}R,\quad \Sigma_{\Delta S\Delta S}=d_{22}(1_{p}1^\top_{p})+u_{22}R

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

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

where

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

Here u_{ij} are the entries of \Sigma_{u} and d_{ij} those of \Sigma_{D}.

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.02579325, 0.02514841,
              0.02514841, 0.02872256),
              nrow = 2, byrow = TRUE,
              dimnames = list(c("T", "S"), c("T", "S")))


V1 <- matrix(c(0.02907611, 0.02962312,
               0.02962312, 0.03400179),
               nrow = 2, byrow = TRUE,
               dimnames = list(c("T", "S"), c("T", "S")))

D0 <- matrix(c(0.02587092, 0.02458997,
               0.02458997, 0.02405581),
               nrow = 2, byrow = TRUE,
               dimnames = list(c("T", "S"), c("T", "S")))

D1 <- matrix(c(0.03649246, 0.03225987,
              0.03225987, 0.02897932),
              nrow = 2, byrow = TRUE,
              dimnames = list(c("T", "S"), c("T", "S")))

# Example run
ica_ri<- ICA_contcont_long_ri(V0 = V0,  V1 = V1,
                     D0 = D0,  D1 = D1,
                     times=c(1,2,4,6,8),
                     correlation  = "exponential",
                     temporal_rho = 0.7117544 ,
                     grid_V = seq(-1, 1, by = 0.5),
                     grid_D = seq(-1, 1, by = 0.5),
                     return_candidates = FALSE,
                     tol = 1e-12)

summary_longitudinal_ica(ica_ri)

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