ICA_contcont_long_cre: Assess surrogacy in the information-theoretic...
In Surrogate: Evaluation of Surrogate Endpoints in Clinical Trials
View source: R/ICA_contcont_long_cre.R
ICA_contcont_long_cre R Documentation
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
)
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.
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.
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
# 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
## Not run:
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
)
## End(Not run)
Surrogate documentation built on Oct. 16, 2026, 9:07 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/ICA_contcont_long_cre.R
| ICA_contcont_long_cre | R Documentation |
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
)
Arguments
p |
(numeric) number of time points |
time_points |
Numeric vector of measurement times. Its length must be |
R_structure |
Residual correlation structure for |
R_rho |
(numeric) correlation parameter for |
VT0S0 |
A scalar that specifies the covariance between the surrogate and
the true endpoint in the control treatment condition for the |
VT1S1 |
A scalar that specifies the covariance between the surrogate and
the true endpoint in the experimental treatment condition for the |
VT0T0 |
A scalar that specifies the variance of the true endpoint in the
control treatment condition for the |
VT1T1 |
A scalar that specifies the variance of the true endpoint in the
experimental treatment condition for the |
VS0S0 |
A scalar that specifies the variance of the surrogate endpoint in
the control treatment condition for the |
VS1S1 |
A scalar that specifies the variance of the surrogate endpoint in
the experimental treatment condition for the |
VT0T1 |
A scalar or vector that contains the correlation(s) between the
counterfactuals |
VT0S1 |
A scalar or vector that contains the correlation(s) between the
counterfactuals |
VT1S0 |
A scalar or vector that contains the correlation(s) between the
counterfactuals |
VS0S1 |
A scalar or vector that contains the correlation(s) between the
counterfactuals |
D |
An |
N |
Sample size used by |
M |
Number of Monte Carlo draws used by |
prob |
Optional probability vector passed to
|
Seed |
Random seed passed to |
Show.Progress |
Logical; should |
Value
Num.Pos.Def.V: An object of class numeric that contains the number of positive definite
Vmatrices.Num.Pos.Def.D: An object of class numeric that contains the number of positive definite
Dmatrices.Num.Pos.Def.Pairs: An object of class numeric that contains the number of valid
V-Dpairs used in the final calculations.R2_Lambda: A scalar or vector that contains the individual causal association
R_{\Lambda}^2.
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
# 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
## Not run:
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
)
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.