jointSurroPenalSimul: Simulation studies based on the one-step Joint surrogate...
In frailtypack: Shared, Joint (Generalized) Frailty Models; Surrogate Endpoints
View source: R/jointSurroPenalSimul.R
jointSurroPenalSimul R Documentation
Simulation studies based on the one-step Joint surrogate models for the evaluation of a canditate
surrogate endpoint
Description
This function aims to allow simulation studies, based on the joint frailty surrogate model,
described in jointSurroPenal. Simulation can also be based on the joint frailty-copula
model described in jointSurroCopPenal
Usage
jointSurroPenalSimul(maxit=40, indicator.zeta = 1,
indicator.alpha = 1, frail.base = 1, n.knots = 6, nb.dataset = 1,
nbSubSimul=1000, ntrialSimul=30, LIMparam = 0.001,
LIMlogl = 0.001, LIMderiv = 0.001, nb.mc = 300, nb.gh = 32,
nb.gh2 = 20, adaptatif = 0, int.method = 2, nb.iterPGH = 5,
nb.MC.kendall = 10000, nboot.kendall = 1000, true.init.val = 0,
theta.init = 1, sigma.ss.init = 0.5, sigma.tt.init = 0.5,
sigma.st.init = 0.48, gamma.init = 0.5, alpha.init = 1,
zeta.init = 1, betas.init = 0.5, betat.init = 0.5,
random.generator = 1, equi.subj.trial = 1, prop.subj.trial = NULL,
equi.subj.trt = 1, prop.subj.trt = NULL,
theta2 = 3.5, zeta = 1, gamma.ui = 2.5, alpha.ui = 1,
betas = -1.25, betat = -1.25, lambdas = 1.8, nus = 0.0045,
lambdat = 3, nut = 0.0025, prop.cens = 0, time.cens = 549, R2 = 0.81,
sigma.s = 0.7, sigma.t = 0.7, kappa.use = 4, random = 0,
random.nb.sim = 0, seed = 0, nb.reject.data = 0, init.kappa = NULL,
ckappa = c(0,0), type.joint.estim = 1, type.joint.simul = 1,
mbetast =NULL, mbetast.init = NULL, typecopula =1, theta.copula = 6,
thetacopula.init = 3, filter.surr = c(1), filter.true = c(1),
nb.decimal = 4, pfs = 0, print.times = TRUE, print.iter=FALSE)
Arguments
maxit
maximum number of iterations for the Marquardt algorithm.
Default is 40.
indicator.zeta
A binary, indicates whether the power's parameter \zeta should
be estimated (1) or not (0). It is required if type.joint.estim = 1.
If 0, \zeta will be set to 1 during estimation.
The default is 1. This parameter can be seted to 0 in the event of identification issues.
indicator.alpha
A binary, indicates whether the power's parameter \alpha should
be estimated (1) or not (0). If 0, \alpha will be set to 1 during estimation.
The default is 1. This parameter can be seted to 0 in the event of identification issues.
frail.base
Considered the heterogeneity between trial on the baseline risk (1), using
the shared cluster specific frailties ui , or
not (0). The default is 1.
n.knots
integer giving the number of knots to use. Value required in
the penalized likelihood estimation. It corresponds to the (n.knots+2)
splines functions for the approximation of the hazard or the survival
functions. We estimate I or M-splines of order 4. When the user set a
number of knots equals to k (n.knots=k) then the number of interior knots
is (k-2) and the number of splines is (k-2)+order. Number of knots must be
between 4 and 20. (See frailtyPenal for more details).
nb.dataset
Number of dataset to analyze. The default is 1.
nbSubSimul
Number of subjects.
ntrialSimul
Number of trials.
LIMparam
Convergence threshold of the Marquardt algorithm for the
parameters, 10-3
by default (See frailtyPenal for more details).
LIMlogl
Convergence threshold of the Marquardt algorithm for the
log-likelihood, 10-3
by default (See frailtyPenal for more details).
LIMderiv
Convergence threshold of the Marquardt algorithm for the gradient,
10-3 by default
(See frailtyPenal for more details).
nb.mc
Number of samples considered in the Monte-Carlo integration. Required in the event
int.method is equals to 0, 2 or 4. A value between 100 and 300 most often gives
good results. However, beyond 300, the program takes a lot of time to estimate the parameters.
The default is 300.
nb.gh
Number of nodes for the Gaussian-Hermite quadrature. It can
be chosen among 5, 7, 9, 12, 15, 20 and 32. The default is 32.
nb.gh2
Number of nodes for the Gauss-Hermite quadrature used to re-estimate the model,
in the event of non-convergence, defined as previously. The default is 20.
adaptatif
A binary, indicates whether the pseudo adaptive Gaussian-Hermite quadrature
(1) or the classical Gaussian-Hermite quadrature (0) is used. The default is 0.
int.method
A numeric, indicates the integration method: 0 for Monte carlo,
1 for Gaussian-Hermite quadrature. If type.joint.estim = 1 this parameter can be set to
2 for a combination of both Gaussian-Hermite quadrature to
integrate over the individual-level random effects and Monte carlo to integrate over the trial-level
random effects, 4 for a combination of both Monte carlo to integrate over
the individual-level random effects and Gaussian-Hermite quadrature to integrate over the trial-level
random effects. If type.joint.estim = 3, value 3 indicates integration using Laplace
approximation . The default is 2.
nb.iterPGH
Number of iterations before the re-estimation of the posterior random effects,
in the event of the two-steps pseudo-adaptive Gaussian-hermite quadrature. If set to 0 there is no
re-estimation". The default is 5.
nb.MC.kendall
Number of generated points used with the Monte-Carlo to estimate
integrals in the Kendall's \tau formulation. Beter to use at least 4000 points for
stable results. Required if type.joint.estim = 1, the default is 10000.
nboot.kendall
Number of samples considered in the parametric bootstrap to estimate the confidence
interval of the Kendall's \tau, or R<sup>2</sup><sub>trial</sub>. The default is 1000.
true.init.val
Numerical value. Indicates if the real parameter values
(1), or the given initial values to parameters (0) should be considered.
If set to 2, \alpha and \gamma are initialised using two separed shared frailty model
(see frailtyPenal for more details); \sigma2vS, \sigma2vT and
\sigmavST
are fixed using the default initial values given by the user; \zeta,
\theta, \betaS and \betaT
are initialized using a classical joint
frailty model, considering individual level random effects. If the joint frailty model is
faced to convergence issues, \betaS and \betaT
are initialized using
two shared frailty models. In all others scenarios, if the simplified model does not converge,
default given parameters values are used. Initial values for spline's associated parameters
are fixed to 0.5. The default for this argument is 0.
theta.init
Initial values for \theta, required if true.init.val
is set to 0 or 2, and type.joint.estim = 1. The default is 1.
sigma.ss.init
Initial values for
\sigma2vS, required if true.init.val
is set to 0 or 2. The default is 0.5.
sigma.tt.init
Initial values for
\sigma2vT, required if true.init.val
is set to 0 or 2. The default is 0.5.
sigma.st.init
Initial values for
\sigmavST, required if true.init.val
is set to 0 or 2. The default is 0.48.
gamma.init
Initial values for \gamma, required if true.init.val
is set to 0 or 2. The default is 0.5.
alpha.init
Initial values for \alpha, required if true.init.val
is set to 0 or 2. The default is 1.
zeta.init
Initial values for \zeta, required if true.init.val
is set to 0 or 2 and type.joint.estim = 1. The default is 1.
betas.init
Initial values for \betaS, required if true.init.val
is set to 0 or 2. The default is 0.5.
betat.init
Initial values for \betaT, required if true.init.val
is set to 0 or 2. The default is 0.5.
random.generator
Random number generator used by the Fortran compiler,
1 for the intrinsec subroutine Random_number and 2 for the
subroutine uniran(). The default is 1.
equi.subj.trial
A binary, that indicates if the same proportion of subjects per trial
should be considered in the procces of data generation (1) or not (0). In the event of
different trial sizes, fill in prop.subj.trial the proportions
of subjects to be considered per trial. The default is 1.
prop.subj.trial
Vector of the proportions of subjects to consider per trial.
Requires if the argument equi.subj.trial is different to 1. The size of this vector is equal to the
number of trials.
equi.subj.trt
Indicates if the same proportion of treated subjects per trial should be
considered (1) or not (0). If 0, fill in prop.subj.trt
the proportions of treated subjects to be considered per trial. The default is 1.
prop.subj.trt
Vector of the proportions of treated subjects to consider per trial.
Requires if the argument equi.subj.trt is different to 0.5. The size of this vector is equal to the
number of trials.
theta2
True value for \theta. Require if type.joint.simul = 1, the default is 3.5.
zeta
True value for \zeta in the event of simulation. The default is 1.
gamma.ui
True value for \gamma in the event of simulation. The default is 2.5.
alpha.ui
True value for \alpha in the event of simulation. The default is 1.
betas
True value for \betaS in the event of simulation. The default is -1.25.
betat
True value for \betaT in the event of simulation. The default is -1.25.
lambdas
Desired scale parameter for the Weibull distribution associated with the Surrogate
endpoint. The default is 1.8.
nus
Desired shape parameter for the Weibull distribution associated with the Surrogate
endpoint. The default is 0.0045.
lambdat
Desired scale parameter for the Weibull distribution associated with the True
endpoint.The default is 3.
nut
Desired shape parameter for the Weibull distribution associated with the True endpoint.
The default is 0.0025.
prop.cens
A value between 0 and 1, 1-prop.cens is the minimum proportion of people who are randomly censored.
Represents the quantile to use for generating the random censorship time. In this case, the censorship
time follows a uniform distribution in 1 and (prop.cens)ieme percentile of the
generated death times. If this argument is set to 0, the fix censorship is considered.
The default is 0. Required if type.joint.simul = 3.
time.cens
Censorship time. If argument prop.cens is set to 0, it represents
the administrative censorship time, else it represents the fix censoring time. The default is 549,
for about 40% of fix censored subjects.
R2
Desired
R2trial. The default is 0.81.
sigma.s
True value for \sigma2vS
The default is 0.7.
sigma.t
True value for \sigma2vT. The default is 0.7.
kappa.use
A numeric, that indicates how to manage the smoothing parameters k1
and k2 in the event of convergence issues. If it is set
to 0, the first smoothing parameters that allowed convergence on the first dataset is used
for all simulations. if it is set to 1, a smoothing parameter is estimated by cross-validation
for each dataset generated. If it is set to 2, the same process for chosing kappas as in the event
1 is used, but in the event of convergence issue, the first smoothing parameters that allowed
convergence among the three previous that have worked is used. If it is set to 3, the associated
smoothing parameters are successively divided by 10, in the event of convergence issues until 5 times.
If it is set to 4, the management of the smoothing
parameters is as in the event 2, preceded by the successive division described in the event 3 and
by the changing of the number of nodes for the Gauss-Hermite quadrature. The default is 4.
random
A binary that says if we reset the random number generation with a different environment
at each call (1) or not (0). If it is set to 1, we use the computer clock
as seed. In the last case, it is not possible to reproduce the generated datasets.
The default is 0. Required if random.generator is set to 1.
random.nb.sim
If random is set to 1, a binary that indicates the number
of generations that will be made, equal to nb.dataset in this case.
seed
The seed to use for data generation. Required if random is set to 0.
The default is 0.
nb.reject.data
When the simulations have been split into several packets, this argument
indicates the number of generated datasets to reject before starting the simulations studies.
This prevents to reproduce the same datasets for all simulation packages. It must be set to
0 if just one packet is considered, the default. Otherwise for each packet of simulation
run, this value must be updated.
e.g. If 10 packets are considered for a total of 100 datasets, one can assigned 0 for the first packet run,
10 for the second, 20 for the 3rd, ... , 90 for the 10th. If this argument is different to 0,
the argument nb.dataset must be set to the number of dataset to consider in the packet.
init.kappa
smoothing parameter used to penalized the log-likelihood. By default (init.kappa = NULL) the values used
are obtain by cross-validation.
ckappa
Vector of two constantes to add to the smoothing parameters. By default it is set to (0,0). this argument allows
to well manage the smoothing parameters in the event of convergence issues.
type.joint.estim
Model to considered for the estimation. If this argument is set to 1, the joint surrogate model
is used, the default (see jointSurroPenal). If set to 3, parameters are estimated under the joint frailty-copula model
for surrogacy (see jointSurroCopPenal).
type.joint.simul
Model to considered for data generation. If this argument is set to 1, the joint surrogate model
is used, the default (see jointSurroPenal). If set to 3, data are generated following the joint frailty-copula model
for surrogacy (see jointSurroCopPenal).
mbetast
Matrix or dataframe containing the true fixed traitment effects associated with the covariates. This matrix includes
two columns (first one for surrogate endpoint and second one for true endpoint) and the number of row corresponding
to the number of covariate. Require if type.joint.simul = 3 with more than one covariate. The default
is NULL and assume only the treatment effect
mbetast.init
Matrix or dataframe containing the initial values for the fixed effects associated with the covariates. This matrix include
two columns (first one for surrogate endpoint and second one for true endpoint) and the number of row corresponding
to the number of covariate. Require if type.joint.simul = 3 with more than one covariate. The default
is NULL and assume only the treatment effect
typecopula
The copula function used for estimation: 1 = clayton, 2 = Gumbel. Require if type.joint.simul = 3, the default is 1
theta.copula
The copula parameter. Require if type.joint.simul = 3. The default is 6, for an individual-level
association (kendall's \tau) of 0.75 in the event of Clayton copula
thetacopula.init
Initial value for the copula parameter. Require if type.joint.estim = 3, the default is 3
filter.surr
Vector of size the number of covariates, with the i-th element that indicates if the hazard for
surrogate is adjusted on the i-th covariate (code 1) or not (code 0). By default, only the treatment effect is
considered.
filter.true
Vector defines as filter.surr, for true endpoint. filter.true and filter.surr
should have the same size
nb.decimal
Number of decimal required for results presentation.
pfs
Is used to specified if the time to progression should be censored by the death time (0) or not (1).
The default is 0. In the event with pfs set to 1, death is included in the surrogate endpoint as in the definition of PFS or DFS.
print.times
a logical parameter to print estimation time. Default
is TRUE.
print.iter
a logical parameter to print iteration process. Default
is FALSE.
Details
The estimated parameter are obtained using the robust Marquardt algorithm
(Marquardt, 1963) which is a combination between a Newton-Raphson algorithm
and a steepest descent algorithm. The iterations are stopped when the
difference between two consecutive log-likelihoods was small
(<10-3 ), the estimated coefficients were stable (consecutive
values (<10-3 ),
and the gradient small enough (<10-3 ), by default.
Cubic M-splines of order 4 are used for the hazard function, and I-splines (integrated M-splines) are
used for the cumulative hazard function.
The inverse of the Hessian matrix is the variance estimator and to deal
with the positivity constraint of the variance component and the spline
coefficients, a squared transformation is used and the standard errors are
computed by the \Delta-method (Knight & Xekalaki, 2000). The smooth
parameter can be chosen by maximizing a likelihood cross validation
criterion (Joly and other, 1998).
We proposed based on the joint surrogate model a new definition
of the Kendall's \tau. By cons, for the joint frailty-copula model, we
based the individual-level association on a definition of \tau clause to
that of the classical two-step approch (Burzykowski et al, 2001), but conditional
on the random effects. Moreover, distinct numerical integration methods are available to approximate the
integrals in the marginal log-likelihood.
Non-convergence case management procedure
Special attention must be given to initializing model parameters, the choice of the number of
spline knots, the smoothing parameters and the number of quadrature points to solve convergence
issues. We first initialized parameters using the user's desired strategy, as specified
by the option true.init.val. When numerical or convergence problems are encountered,
with kappa.use set to 4, the model is fitted again using a combination of the following strategies:
vary the number of quadrature point (nb.gh to nb.gh2 or nb.gh2 to nb.gh)
in the event of the use of the Gaussian Hermite quadrature integration (see int.method);
divided or multiplied the smoothing parameters ( k1,
k2) by 10 or 100 according to
their preceding values, or used parameter vectors obtained during the last iteration (with a
modification of the number of quadrature points and smoothing parameters). Using this strategy,
we usually obtained during simulation the rejection rate less than 3%. A sensitivity analysis
was conducted without this strategy, and similar results were obtained on the converged samples,
with about a 23% rejection rate.
Value
This function returns an object of class jointSurroPenalSimul with elements :
theta2
True value for \theta, if type.joint.estim = 1;
theta.copula
Copula parameter, if type.joint.estim = 3;
zeta
true value for \zeta, if type.joint.estim = 1;
gamma.ui
true value for \gamma;
alpha.ui
true value for \alpha;
sigma.s
true value for
\sigma2vS;
sigma.t
true value for
\sigma2vT;
sigma.st
true value for
\sigmavST;
betas
true value for \betaS;
betat
true value for \betaT;
R2
true value for
R2trial;
nb.subject
total number of subjects used;
nb.trials
total number of trials used;
nb.simul
number of simulated datasets;
nb.gh
number of nodes for the Gaussian-Hermite quadrature;
nb.gh2
number of nodes for the Gauss-Hermite quadrature used to re-estimate the model, in the event of non-convergence;
nb.mc
number of samples considered in the Monte-Carlo integration;
kappa.use
a numeric, that indicates how to manage the smoothing parameters
k1 and k2 in the event of convergence issues;
n.knots
number of knots used for splines;
int.method
integration method used;
n.iter
mean number of iterations needed to converge;
dataTkendall
a matrix with nb.dataset line(s) and three columns, of the estimates of Kendall's \tau
and theirs confidence intervals (obtained using parametric bootstrap if type.joint.estim = 1 or
Delta method if type.joint.estim = 3). All non-convergence cases are represented by a line of 0;
dataR2boot
a matrix with nb.dataset line(s) and three columns, of the estimates of
R2trial
and theirs confidence intervals using the parametric bootstrap. All non-convergence cases are represented by a line of 0.
dataParamEstim
a dataframe including all estimates with the associated standard errors, for all simulation.
All non-convergence cases are represented by a line of 0;
dataHessian
Dataframe of the variance-Covariance matrices of the estimates for all simulations
dataHessianIH
Dataframe of the robust estimation of the variance matrices of the estimates for all simulations
datab
Dataframe of the estimates for all simulations which rich convergence
type.joint
the estimation model; 1 for the joint surrogate and 3 for joint frailty-copula model
type.joint.simul
The model used for data generation; 1 for joint surrogate and 3 for joint frailty-copula
true.init.val
Indicates if the real parameter values have been used as initial values for the model (1), or the given initial values (0)
Author(s)
Casimir Ledoux Sofeu casimir.sofeu@u-bordeaux.fr, scl.ledoux@gmail.com and
Virginie Rondeau virginie.rondeau@inserm.fr
References
Burzykowski, T., Molenberghs, G., Buyse, M., Geys, H., and Renard, D. (2001). Validation
of surrogate end points in multiple randomized clinical trials with failure time end points.
Journal of the Royal Statistical Society: Series C (Applied Statistics) 50, 405-422.
Sofeu, C. L., Emura, T., and Rondeau, V. (2019). One-step validation method for surrogate
endpoints using data from multiple randomized cancer clinical trials with failure-time endpoints.
Statistics in Medicine 38, 2928-2942.
See Also
jointSurroPenal, jointSurroCopPenal, summary.jointSurroPenalSimul
, jointSurrSimul, jointSurrCopSimul
Examples
# Surrogacy model evaluation performance study based on 10 generated data
# (Computation takes around 20 minutes using a processor including 40
# cores and a read only memory of 378 Go)
# To realize a simulation study on 100 samples or more (as required), use
# nb.dataset = 100
### joint frailty model
joint.simul <- jointSurroPenalSimul(nb.dataset = 10, nbSubSimul= 600,
ntrialSimul = 30, LIMparam = 0.001, LIMlogl = 0.001,
LIMderiv = 0.001, nb.mc = 200, nb.gh = 20,
nb.gh2 = 32, true.init.val = 1, print.iter = F, pfs = 0)
# results
summary(joint.simul, d = 3, R2boot = 1) # bootstrap
summary(joint.simul, d = 3, R2boot = 0) # Delta-method
### joint frailty copula model
joint.simul.cop.clay <- jointSurroPenalSimul(nb.dataset = 10, nbSubSimul= 600,
ntrialSimul = 30, nb.mc = 1000, type.joint.estim = 3,
typecopula = 1, type.joint.simul = 3, theta.copula = 3,
time.cens = 349, true.init.val = 1, R2 = 0.81, maxit = 40,
print.iter = F)
summary(joint.simul.cop.clay)
frailtypack documentation built on Nov. 25, 2023, 9:06 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/jointSurroPenalSimul.R
| jointSurroPenalSimul | R Documentation |
Simulation studies based on the one-step Joint surrogate models for the evaluation of a canditate surrogate endpoint
Description
This function aims to allow simulation studies, based on the joint frailty surrogate model, described in jointSurroPenal. Simulation can also be based on the joint frailty-copula model described in jointSurroCopPenal
Usage
jointSurroPenalSimul(maxit=40, indicator.zeta = 1,
indicator.alpha = 1, frail.base = 1, n.knots = 6, nb.dataset = 1,
nbSubSimul=1000, ntrialSimul=30, LIMparam = 0.001,
LIMlogl = 0.001, LIMderiv = 0.001, nb.mc = 300, nb.gh = 32,
nb.gh2 = 20, adaptatif = 0, int.method = 2, nb.iterPGH = 5,
nb.MC.kendall = 10000, nboot.kendall = 1000, true.init.val = 0,
theta.init = 1, sigma.ss.init = 0.5, sigma.tt.init = 0.5,
sigma.st.init = 0.48, gamma.init = 0.5, alpha.init = 1,
zeta.init = 1, betas.init = 0.5, betat.init = 0.5,
random.generator = 1, equi.subj.trial = 1, prop.subj.trial = NULL,
equi.subj.trt = 1, prop.subj.trt = NULL,
theta2 = 3.5, zeta = 1, gamma.ui = 2.5, alpha.ui = 1,
betas = -1.25, betat = -1.25, lambdas = 1.8, nus = 0.0045,
lambdat = 3, nut = 0.0025, prop.cens = 0, time.cens = 549, R2 = 0.81,
sigma.s = 0.7, sigma.t = 0.7, kappa.use = 4, random = 0,
random.nb.sim = 0, seed = 0, nb.reject.data = 0, init.kappa = NULL,
ckappa = c(0,0), type.joint.estim = 1, type.joint.simul = 1,
mbetast =NULL, mbetast.init = NULL, typecopula =1, theta.copula = 6,
thetacopula.init = 3, filter.surr = c(1), filter.true = c(1),
nb.decimal = 4, pfs = 0, print.times = TRUE, print.iter=FALSE)
Arguments
maxit |
maximum number of iterations for the Marquardt algorithm.
Default is |
indicator.zeta |
A binary, indicates whether the power's parameter |
indicator.alpha |
A binary, indicates whether the power's parameter |
frail.base |
Considered the heterogeneity between trial on the baseline risk ( |
n.knots |
integer giving the number of knots to use. Value required in
the penalized likelihood estimation. It corresponds to the (n.knots+2)
splines functions for the approximation of the hazard or the survival
functions. We estimate I or M-splines of order 4. When the user set a
number of knots equals to k (n.knots=k) then the number of interior knots
is (k-2) and the number of splines is (k-2)+order. Number of knots must be
between 4 and 20. (See |
nb.dataset |
Number of dataset to analyze. The default is |
nbSubSimul |
Number of subjects. |
ntrialSimul |
Number of trials. |
LIMparam |
Convergence threshold of the Marquardt algorithm for the
parameters, 10-3
by default (See |
LIMlogl |
Convergence threshold of the Marquardt algorithm for the
log-likelihood, 10-3
by default (See |
LIMderiv |
Convergence threshold of the Marquardt algorithm for the gradient,
10-3 by default
(See |
nb.mc |
Number of samples considered in the Monte-Carlo integration. Required in the event
|
nb.gh |
Number of nodes for the Gaussian-Hermite quadrature. It can be chosen among 5, 7, 9, 12, 15, 20 and 32. The default is 32. |
nb.gh2 |
Number of nodes for the Gauss-Hermite quadrature used to re-estimate the model,
in the event of non-convergence, defined as previously. The default is |
adaptatif |
A binary, indicates whether the pseudo adaptive Gaussian-Hermite quadrature
|
int.method |
A numeric, indicates the integration method: |
nb.iterPGH |
Number of iterations before the re-estimation of the posterior random effects,
in the event of the two-steps pseudo-adaptive Gaussian-hermite quadrature. If set to |
nb.MC.kendall |
Number of generated points used with the Monte-Carlo to estimate
integrals in the Kendall's |
nboot.kendall |
Number of samples considered in the parametric bootstrap to estimate the confidence
interval of the Kendall's |
true.init.val |
Numerical value. Indicates if the real parameter values
|
theta.init |
Initial values for |
sigma.ss.init |
Initial values for
|
sigma.tt.init |
Initial values for
|
sigma.st.init |
Initial values for
|
gamma.init |
Initial values for |
alpha.init |
Initial values for |
zeta.init |
Initial values for |
betas.init |
Initial values for |
betat.init |
Initial values for |
random.generator |
Random number generator used by the Fortran compiler,
|
equi.subj.trial |
A binary, that indicates if the same proportion of subjects per trial
should be considered in the procces of data generation (1) or not (0). In the event of
different trial sizes, fill in |
prop.subj.trial |
Vector of the proportions of subjects to consider per trial.
Requires if the argument |
equi.subj.trt |
Indicates if the same proportion of treated subjects per trial should be
considered |
prop.subj.trt |
Vector of the proportions of treated subjects to consider per trial.
Requires if the argument |
theta2 |
True value for |
zeta |
True value for |
gamma.ui |
True value for |
alpha.ui |
True value for |
betas |
True value for |
betat |
True value for |
lambdas |
Desired scale parameter for the |
nus |
Desired shape parameter for the |
lambdat |
Desired scale parameter for the |
nut |
Desired shape parameter for the |
prop.cens |
A value between |
time.cens |
Censorship time. If argument |
R2 |
Desired
|
sigma.s |
True value for |
sigma.t |
True value for |
kappa.use |
A numeric, that indicates how to manage the smoothing parameters k1
and k2 in the event of convergence issues. If it is set
to |
random |
A binary that says if we reset the random number generation with a different environment
at each call |
random.nb.sim |
If |
seed |
The seed to use for data generation. Required if |
nb.reject.data |
When the simulations have been split into several packets, this argument
indicates the number of generated datasets to reject before starting the simulations studies.
This prevents to reproduce the same datasets for all simulation packages. It must be set to
|
init.kappa |
smoothing parameter used to penalized the log-likelihood. By default (init.kappa = NULL) the values used are obtain by cross-validation. |
ckappa |
Vector of two constantes to add to the smoothing parameters. By default it is set to (0,0). this argument allows to well manage the smoothing parameters in the event of convergence issues. |
type.joint.estim |
Model to considered for the estimation. If this argument is set to |
type.joint.simul |
Model to considered for data generation. If this argument is set to |
mbetast |
Matrix or dataframe containing the true fixed traitment effects associated with the covariates. This matrix includes
two columns (first one for surrogate endpoint and second one for true endpoint) and the number of row corresponding
to the number of covariate. Require if |
mbetast.init |
Matrix or dataframe containing the initial values for the fixed effects associated with the covariates. This matrix include
two columns (first one for surrogate endpoint and second one for true endpoint) and the number of row corresponding
to the number of covariate. Require if |
typecopula |
The copula function used for estimation: 1 = clayton, 2 = Gumbel. Require if |
theta.copula |
The copula parameter. Require if |
thetacopula.init |
Initial value for the copula parameter. Require if |
filter.surr |
Vector of size the number of covariates, with the i-th element that indicates if the hazard for surrogate is adjusted on the i-th covariate (code 1) or not (code 0). By default, only the treatment effect is considered. |
filter.true |
Vector defines as |
nb.decimal |
Number of decimal required for results presentation. |
pfs |
Is used to specified if the time to progression should be censored by the death time (0) or not (1). The default is 0. In the event with pfs set to 1, death is included in the surrogate endpoint as in the definition of PFS or DFS. |
print.times |
a logical parameter to print estimation time. Default is TRUE. |
print.iter |
a logical parameter to print iteration process. Default is FALSE. |
Details
The estimated parameter are obtained using the robust Marquardt algorithm (Marquardt, 1963) which is a combination between a Newton-Raphson algorithm and a steepest descent algorithm. The iterations are stopped when the difference between two consecutive log-likelihoods was small (<10-3 ), the estimated coefficients were stable (consecutive values (<10-3 ), and the gradient small enough (<10-3 ), by default. Cubic M-splines of order 4 are used for the hazard function, and I-splines (integrated M-splines) are used for the cumulative hazard function.
The inverse of the Hessian matrix is the variance estimator and to deal
with the positivity constraint of the variance component and the spline
coefficients, a squared transformation is used and the standard errors are
computed by the \Delta-method (Knight & Xekalaki, 2000). The smooth
parameter can be chosen by maximizing a likelihood cross validation
criterion (Joly and other, 1998).
We proposed based on the joint surrogate model a new definition
of the Kendall's \tau. By cons, for the joint frailty-copula model, we
based the individual-level association on a definition of \tau clause to
that of the classical two-step approch (Burzykowski et al, 2001), but conditional
on the random effects. Moreover, distinct numerical integration methods are available to approximate the
integrals in the marginal log-likelihood.
Non-convergence case management procedure
Special attention must be given to initializing model parameters, the choice of the number of
spline knots, the smoothing parameters and the number of quadrature points to solve convergence
issues. We first initialized parameters using the user's desired strategy, as specified
by the option true.init.val. When numerical or convergence problems are encountered,
with kappa.use set to 4, the model is fitted again using a combination of the following strategies:
vary the number of quadrature point (nb.gh to nb.gh2 or nb.gh2 to nb.gh)
in the event of the use of the Gaussian Hermite quadrature integration (see int.method);
divided or multiplied the smoothing parameters ( k1,
k2) by 10 or 100 according to
their preceding values, or used parameter vectors obtained during the last iteration (with a
modification of the number of quadrature points and smoothing parameters). Using this strategy,
we usually obtained during simulation the rejection rate less than 3%. A sensitivity analysis
was conducted without this strategy, and similar results were obtained on the converged samples,
with about a 23% rejection rate.
Value
This function returns an object of class jointSurroPenalSimul with elements :
theta2 |
True value for |
theta.copula |
Copula parameter, if |
zeta |
true value for |
gamma.ui |
true value for |
alpha.ui |
true value for |
sigma.s |
true value for
|
sigma.t |
true value for
|
sigma.st |
true value for
|
betas |
true value for |
betat |
true value for |
R2 |
true value for
|
nb.subject |
total number of subjects used; |
nb.trials |
total number of trials used; |
nb.simul |
number of simulated datasets; |
nb.gh |
number of nodes for the Gaussian-Hermite quadrature; |
nb.gh2 |
number of nodes for the Gauss-Hermite quadrature used to re-estimate the model, in the event of non-convergence; |
nb.mc |
number of samples considered in the Monte-Carlo integration; |
kappa.use |
a numeric, that indicates how to manage the smoothing parameters k1 and k2 in the event of convergence issues; |
n.knots |
number of knots used for splines; |
int.method |
integration method used; |
n.iter |
mean number of iterations needed to converge; |
dataTkendall |
a matrix with |
dataR2boot |
a matrix with |
dataParamEstim |
a dataframe including all estimates with the associated standard errors, for all simulation. All non-convergence cases are represented by a line of 0; |
dataHessian |
Dataframe of the variance-Covariance matrices of the estimates for all simulations |
dataHessianIH |
Dataframe of the robust estimation of the variance matrices of the estimates for all simulations |
datab |
Dataframe of the estimates for all simulations which rich convergence |
type.joint |
the estimation model; 1 for the joint surrogate and 3 for joint frailty-copula model |
type.joint.simul |
The model used for data generation; 1 for joint surrogate and 3 for joint frailty-copula |
true.init.val |
Indicates if the real parameter values have been used as initial values for the model |
Author(s)
Casimir Ledoux Sofeu casimir.sofeu@u-bordeaux.fr, scl.ledoux@gmail.com and Virginie Rondeau virginie.rondeau@inserm.fr
References
Burzykowski, T., Molenberghs, G., Buyse, M., Geys, H., and Renard, D. (2001). Validation of surrogate end points in multiple randomized clinical trials with failure time end points. Journal of the Royal Statistical Society: Series C (Applied Statistics) 50, 405-422.
Sofeu, C. L., Emura, T., and Rondeau, V. (2019). One-step validation method for surrogate endpoints using data from multiple randomized cancer clinical trials with failure-time endpoints. Statistics in Medicine 38, 2928-2942.
See Also
jointSurroPenal, jointSurroCopPenal, summary.jointSurroPenalSimul
, jointSurrSimul, jointSurrCopSimul
Examples
# Surrogacy model evaluation performance study based on 10 generated data
# (Computation takes around 20 minutes using a processor including 40
# cores and a read only memory of 378 Go)
# To realize a simulation study on 100 samples or more (as required), use
# nb.dataset = 100
### joint frailty model
joint.simul <- jointSurroPenalSimul(nb.dataset = 10, nbSubSimul= 600,
ntrialSimul = 30, LIMparam = 0.001, LIMlogl = 0.001,
LIMderiv = 0.001, nb.mc = 200, nb.gh = 20,
nb.gh2 = 32, true.init.val = 1, print.iter = F, pfs = 0)
# results
summary(joint.simul, d = 3, R2boot = 1) # bootstrap
summary(joint.simul, d = 3, R2boot = 0) # Delta-method
### joint frailty copula model
joint.simul.cop.clay <- jointSurroPenalSimul(nb.dataset = 10, nbSubSimul= 600,
ntrialSimul = 30, nb.mc = 1000, type.joint.estim = 3,
typecopula = 1, type.joint.simul = 3, theta.copula = 3,
time.cens = 349, true.init.val = 1, R2 = 0.81, maxit = 40,
print.iter = F)
summary(joint.simul.cop.clay)
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.