Learn R Programming

Surrogate (version 3.4.4)

ICA_contcont_long_ri_nested: 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 examines how the ICA changes as surrogate endpoint measurements are added sequentially when the true-endpoint treatment-effect trajectory is fixed. See Details below.

Usage

ICA_contcont_long_ri_nested(
  V0,
  V1,
  D0,
  D1,
  times_T,
  times_S,
  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,
  progress = FALSE
)

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_T

Clinical evaluation time points for T.

times_S

Clinical evaluation time points for S.

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.

progress

Logical. If TRUE, progress messages are printed while processing residual covariance completion candidates.

Details

ICA for progressively enlarged surrogate grids under endpoint-specific RI: It keeps the complete true endpoint treatment-effect trajectory fixed on times_T and examine how the ICA changes as surrogate endpoint measurements are added sequentially for specified surrogate grid in times_S. The objective is to determine how much information the first k surrogate endpoint treatment effects provide about the complete true endpoint treatment-effect trajectory.

Consider the vector \((\Delta T1,...,\Delta Tp, \Delta S1,...\Delta Sk )\) for \(k=1,...,p\). Its covariance matrix, denoted by \(\Sigma_{\Delta,p}(k)\) is obtained by retaining the corresponding rows and columns of the original \(2p \times 2p\) covariance matrix. Thus, \(\Sigma_{\Delta,p}(k)\) is the \(5+k \times 5+k\) principal submatrix associated with the complete PANSS trajectory and the first k surrogate treatment effects. For any value of \(k\), partition the selected covariance matrix as

$$ \Sigma_{\Delta,p}(k) = \begin{pmatrix} \Sigma_{\Delta_{TT,p} } & \Sigma_{\Delta_{TS,p}(k)} \\ \Sigma_{\Delta_{TS,p}(k)} & \Sigma_{\Delta_{SS,p}(k) } \end{pmatrix} $$

The ICA for covariance completion \(p\) and surrogate endpoint grid size \(k\) is $$ R_{\Lambda, n}^{2}=1- \frac{\Sigma_{\Delta,p}}{\Delta_{TT,p}\Delta_{SS,p}(k)} $$

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")))

times_S <- list(week1 = c(1),
                        week1_2 = c(1, 2),
                        week1_2_4 = c(1, 2, 4),
                        week1_2_4_6 = c(1, 2, 4, 6),
                        week1_2_4_6_8 = c(1, 2, 4, 6, 8))


# Example run
ica_nested<- ICA_contcont_long_ri_nested(V0 = V0,  V1 = V1,
                            D0 = D0,  D1 = D1,
                            times_T = c(1,2,4,6,8),
                            times_S = times_S,
                            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(list(R2_Lambda = ica_nested$R2_Lambda[, "week1_2_4"]))

Run the code above in your browser using DataLab