Learn R Programming

Surrogate (version 3.4.4)

ICA_contcont_long_cre: 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 a linear model with common random-effects with separable residual covariance structure. See Details below.

Usage

ICA_contcont_long_cre(
  p,
  time_points,
  R_structure = c("AR1", "CS"),
  R_rho = numeric(),
  VT0S0,
  VT1S1,
  VT0T0,
  VT1T1,
  VS0S0,
  VS1S1,
  VT0T1 = seq(-1, 1, by = 0.1),
  VT0S1 = seq(-1, 1, by = 0.1),
  VT1S0 = seq(-1, 1, by = 0.1),
  VS0S1 = seq(-1, 1, by = 0.1),
  D,
  N,
  M = 10000,
  prob = NULL,
  Seed = 123,
  Show.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\).

Arguments

p

(numeric) number of time points

time_points

Numeric vector of measurement times. Its length must be p.

R_structure

Residual correlation structure for R. Supported values are "AR1" and "CS".

R_rho

(numeric) correlation parameter for R. It must be a single value in (-1, 1).

VT0S0

A scalar that specifies the covariance between the surrogate and the true endpoint in the control treatment condition for the V matrix.

VT1S1

A scalar that specifies the covariance between the surrogate and the true endpoint in the experimental treatment condition for the V matrix.

VT0T0

A scalar that specifies the variance of the true endpoint in the control treatment condition for the V matrix.

VT1T1

A scalar that specifies the variance of the true endpoint in the experimental treatment condition for the V matrix.

VS0S0

A scalar that specifies the variance of the surrogate endpoint in the control treatment condition for the V matrix.

VS1S1

A scalar that specifies the variance of the surrogate endpoint in the experimental treatment condition for the V matrix.

VT0T1

A scalar or vector that contains the correlation(s) between the counterfactuals T0 and T1 for the V matrix.

VT0S1

A scalar or vector that contains the correlation(s) between the counterfactuals T0 and S1 for the V matrix.

VT1S0

A scalar or vector that contains the correlation(s) between the counterfactuals T1 and S0 for the V matrix.

VS0S1

A scalar or vector that contains the correlation(s) between the counterfactuals S0 and S1 for the V matrix.

D

An 8 x 8 covariance-matrix for the random effects. Observed entries from the SAS output fit should be supplied on the covariance scale and unidentified entries should be coded as NA. The row/column order must be (bT0, aT0, bT1, aT1, bS0, aS0, bS1, aS1), where b denotes the random intercept and a denotes the random slope.

N

Sample size used by ICA.ContCont.MultS.MPC() when generating positive definite D-matrices.

M

Number of Monte Carlo draws used by ICA.ContCont.MultS.MPC().

prob

Optional probability vector passed to ICA.ContCont.MultS.MPC().

Seed

Random seed passed to ICA.ContCont.MultS.MPC().

Show.Progress

Logical; should ICA.ContCont.MultS.MPC() display progress information.

Common random-effects with separable residual covariance structure:

The evolution of \(y_j\) over time is defined using a linear mixed-effects model. It is considered the important special case in which all four potential-outcome models share the same random-effects structure, for instance a random intercept and slope.

$$T_{0j} = x_{T0j} \gamma_{T0} + z_{T0j}b_{T0} + \varepsilon_{T0j}$$ $$T_{1j} = x_{T1j} \gamma_{T1} + z_{T1j}b_{T1} + \varepsilon_{T1j}$$ $$S_{0j} = x_{S0j} \gamma_{S0} + z_{S0j}b_{S0} + \varepsilon_{S0j}$$ $$S_{1j} = x_{S1j} \gamma_{S1} + z_{S1j}b_{S1} + \varepsilon_{S1j}$$

In this setting, the row vectors of covariates associated with the random effects satisfy \(\mathbf{z}_{kzj} = \mathbf{z}_j\) for \(k = T, S\) and \(z = 0, 1\), and we write \(\dim(\mathbf{z}_j) = q\). Moreover, \(\mathbf{Z}_{kz} = \mathbf{Z}\) for \(k = T, S\).

Within this framework, the vector of individual causal treatment effects \(\mathbf{\Delta}\) can be expressed as $$ \mathbf{\Delta} = \mathbf{\mu}_{\Delta} + (\mathbf{I}_2 \otimes \mathbf{Z}) \, \boldsymbol{\delta b} + \boldsymbol{\varepsilon}_{\Delta}, $$ where \(\boldsymbol{\delta b}\) denotes the vector of random-effect differences $$ \boldsymbol{\delta b} = (\boldsymbol{\delta b}_T^{\top}, \boldsymbol{\delta b}_S^{\top})^{\top}, \qquad \boldsymbol{\delta b}_k = \mathbf{b}_{k1} - \mathbf{b}_{k0}, \quad k = T, S. $$

It follows that \(\boldsymbol{\delta b} \sim N(\mathbf{0}, \mathbf{D}_L)\), \(\boldsymbol{\varepsilon}_{\Delta} \sim N(\mathbf{0}, \mathbf{\Sigma}_{\varepsilon_{\Delta}})\), and \(\mathbf{\Sigma}_{\varepsilon_{\Delta}} = \mathbf{\Sigma}_u \otimes \mathbf{R}\). Therefore, the marginal covariance matrix is given by $$ \mathbf{\Sigma}_{\Delta} = \mathbf{\Sigma}_u \otimes \mathbf{R} + (\mathbf{I}_2 \otimes \mathbf{Z}) \, \mathbf{D}_L \, (\mathbf{I}_2 \otimes \mathbf{Z})^{\top}, $$ where $$ \mathbf{D}_L = \left( \begin{array}{cc} \mathbf{D}_{TT} & \mathbf{D}_{TS} \\ \mathbf{D}_{TS}^{\top} & \mathbf{D}_{SS} \end{array} \right), $$ with \(\mathbf{D}_{TT} = \mathrm{Var}(\boldsymbol{\delta b}_T)\), \(\mathbf{D}_{TS} = \mathrm{Cov}(\boldsymbol{\delta b}_T, \boldsymbol{\delta b}_S)\), and \(\mathbf{D}_{SS} = \mathrm{Var}(\boldsymbol{\delta b}_S)\).

Equivalently, $$ \mathbf{\Sigma}_{\Delta} = \left( \begin{array}{cc} \mathbf{\Sigma}_{\Delta T \Delta T} & \mathbf{\Sigma}_{\Delta T \Delta S} \\ \mathbf{\Sigma}_{\Delta T \Delta S}^{\top} & \mathbf{\Sigma}_{\Delta S \Delta S} \end{array} \right), $$ where $$ \mathbf{\Sigma}_{\Delta T \Delta T} = \mathbf{Z} \mathbf{D}_{TT} \mathbf{Z}^{\top} + u_{11}\mathbf{R}, $$ $$ \mathbf{\Sigma}_{\Delta T \Delta S} = \mathbf{Z} \mathbf{D}_{TS} \mathbf{Z}^{\top} + u_{12}\mathbf{R}, $$ $$ \mathbf{\Sigma}_{\Delta S \Delta S} = \mathbf{Z} \mathbf{D}_{SS} \mathbf{Z}^{\top} + u_{22}\mathbf{R}. $$

The closed-form expression for \(\Lambda\) is $$ \Lambda = (1 - \rho_u^2)^p \frac{ \left| \mathbf{I}_{2q} + \mathbf{D}_L (\mathbf{\Sigma}_u^{-1} \otimes \mathbf{E}) \right| }{ \left| \mathbf{I}_q + u_{11}^{-1}\mathbf{D}_{TT}\mathbf{E} \right| \left| \mathbf{I}_q + u_{22}^{-1}\mathbf{D}_{SS}\mathbf{E} \right| }, $$ where $$ \rho_u^2 = 1 - \frac{|\mathbf{\Sigma}_u|}{u_{11}u_{22}} = \frac{u_{12}^2}{u_{11}u_{22}}, \qquad \mathbf{E} = \mathbf{Z}^{\top}\mathbf{R}^{-1}\mathbf{Z} \in \mathbb{R}^{q \times q}. $$ The ICA metric is given by \(R_{\Lambda}^2 = 1 - \Lambda.\)

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 structure of V matrix for the random-effects model (4x4 V matrix)
# V = | VT0T0  VT0T1  VT0S0  VT0S1 |
#     | VT0T1  VT1T1  VT1S0  VT1S1 |
#     | VT0S0  VT1S0  VS0S0  VS0S1 |
#     | VT0S1  VT1S1  VS0S1  VS1S1 |

# Example structure of D matrix for the random-effects model (8x8 D matrix)
# D = | d(bT0,bT0)  d(bT0,aT0)  ...  d(bT0,bS1)  d(bT0,aS1) |
#     | d(aT0,bT0)  d(aT0,aT0)  ...  d(aT0,bS1)  d(aT0,aS1) |
#     | ...                                           ...   |
#     | d(aS1,bT0)  d(aS1,aT0)  ...  d(aS1,bS1)  d(aS1,aS1) |

# The SAS outputs are inserted as follows:

D <- matrix(NA_real_, nrow = 8, ncol = 8)
un11 <- D[1, 1] <- 0.04162
un22 <- D[3, 3] <- 0.04140
un31 <- D[5, 1] <- D[1, 5] <- 0.02306
un33 <- D[5, 5] <- 0.03991
un42 <- D[7, 3] <- D[3, 7] <- 0.02896
un44 <- D[7, 7] <- 0.04811
un51 <- D[1, 2] <- D[2, 1] <- 0.001000
un53 <- D[2, 5] <- D[5, 2] <- 0.001224
un55 <- D[2, 2] <- 0.001086
un62 <- D[3, 4] <- D[4, 3] <- 0.000439
un64 <- D[4, 7] <- D[7, 4] <- 0.000025
un66 <- D[4, 4] <- 0.001452
un71 <- D[1, 6] <- D[6, 1] <- 0.001114
un73 <- D[5, 6] <- D[6, 5] <- 0.000374
un75 <- D[2, 6] <- D[6, 2] <- 0.000684
un77 <- D[6, 6] <- 0.000919
un82 <- D[3, 8] <- D[8, 3] <- 0.000918
un84 <- D[7, 8] <- D[8, 7] <- -0.00053
un86 <- D[4, 8] <- D[8, 4] <- 0.001472
un88 <- D[8, 8] <- 0.002100
if (FALSE) {
model <- ICA_contcont_long_cre(
  p = 6,
  time_points = c(0, 1, 2, 4, 6, 8),
  R_structure = "CS",
  R_rho = 0.000236,
  VT0S0 = 0.009203,
  VT1S1 = 0.008759,
  VT0T0 = 0.01365,
  VT1T1 = 0.01379,
  VS0S0 = 0.01819,
  VS1S1 = 0.01854,
  VT0T1 = seq(-1, 1, by = 0.2),
  VT0S1 = seq(-1, 1, by = 0.2),
  VT1S0 = seq(-1, 1, by = 0.2),
  VS0S1 = seq(-1, 1, by = 0.2),
  D = D,
  N = 568,
  M = 100,
  Seed = 123
)}



Run the code above in your browser using DataLab