Learn R Programming

Surrogate (version 3.4.4)

ICA_contcont_long_shared_ri: 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
)

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.

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.

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

Run this code
#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)



Run the code above in your browser using DataLab