Learn R Programming

Surrogate (version 3.4.4)

ICA_contcont_long_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

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
)

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, 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.

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

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

Run the code above in your browser using DataLab