Type:	Package
Title:	Additive Cure Survival Model with Time-Varying Covariates
Version:	0.6.6
Maintainer:	Philippe Lambert <p.lambert@uliege.be>
BugReports:	https://github.com/plambertULiege/tvcure/issues
Description:	Fit of a double additive cure survival model with time-varying covariates. The additive terms in the long- and short-term survival submodels, modelling the cure probability and the event timing for susceptible units, are estimated using Laplace P-splines. For more details, see Lambert and Kreyenfeld (2025) <doi:10.1093/jrsssa/qnaf035>.
License:	GPL-3
URL:	<https://github.com/plambertULiege/tvcure>
Encoding:	UTF-8
Imports:	cubicBsplines, Rfast, MASS, Matrix, mgcv
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-04-03 18:11:51 UTC; plambert
Author:	Philippe Lambert [aut, cre]
Repository:	CRAN
Date/Publication:	2025-04-07 16:00:01 UTC

Akaike Information Criterion (AIC) of a tvcure object.

Description

Akaike Information Criterion (AIC) for the fitted tvcure model in a tvcure.object.

Usage

## S3 method for class 'tvcure'
AIC(object, ..., k=2)

Arguments

Details

Akaike information criterion for the fitted model in a tvcure object, with a penalty calculated using the total effective degrees of freedom, -2log(L) + 2*ED.tot, smaller values being preferred during model selection.

Value

The AIC as a numeric value, computed according to the model specified in the input object.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, BIC.tvcure, logEvid

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
AIC(model)

Bayesian Information Criterion (BIC) of a tvcure.object.

Description

Bayesian Information Criterion (BIC) for the fitted tvcure model in a tvcure.object.

Usage

## S3 method for class 'tvcure'
BIC(object, ...)

Arguments

Details

Bayesian (Schwarz) information criterion in a tvcure object, with a penalty calculated using the total effective degrees of freedom and the total number of observed events, -2log(L) + log(d)*ED.tot, smaller values being preferred during model selection.

Value

The BIC as a numeric value, computed according to the model specified in the input object.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, AIC.tvcure, logEvid

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
BIC(model)

Internal function extracting design matrices from formulas in the tvcure function and computing penalty related matrices

Description

Internal function extracting design matrices from formulas in the tvcure function and computing penalty related matrices.

Usage

DesignFormula(
  formula,
  data,
  K = 10,
  pen.order = 2,
  knots.x = NULL,
  n = NULL,
  nointercept = FALSE
)

Arguments

Value

A list with

• J : number of additive terms.

• K : number of B-splines in a basis used to estimate an additive term.

• Z : (n x nfixed) design matrix with fixed effects (including a first column of 1 if nointercept is FALSE).

• X : (n x J) design matrix with the covariates involved in the additive terms.

• Xcal : Z column-stacked with the J centered B-spline bases to yield the full design matrix (with column labels).

• nfixed : number of fixed effect regression parameters.

If additive terms are specified in the formula, the following elements also appear:

• Bcal : column-stacked matrix with the J centered B-spline bases.

• Bx : list with J objects (one per additive term) including (B,Dd,Pd,K,cm).

• Pd.x, Dd.x : penalty and difference penalty matrices applied on the spline parameters of an additive term.

• knots.x : list of length J with the knots associated to each of the J additive terms.

• pen.order : penalty order for the spline parameters in the additive terms.

• additive.lab : labels for the columns in <Bcal> associated to the additive terms.

• lambda.lab : labels for the penalty parameters.

• has.ref : vector of J logicals indicating whether reference values were specified for a given additive term.

• ref.values : specified reference values for the the J additive terms.

• cm.values : list of length J with the values of the B-spline basis at the reference values specified (if any) for each of the additive terms.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Compute the effective degrees freedom in a tvcure model

Description

Compute the effective degrees freedom in a tvcure model

Usage

EDF(model, Wood.test = FALSE, joint.computation = TRUE)

Arguments

Value

A list containing the effective degrees of freedom for the additive terms in the long-term (quantum) and short-term (timing) survival submodels, with the selected statistical test for significance and its P-value.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
EDF(model)

Function to generate a penalty matrix for additive terms.

Description

Compute the penalty matrix associated to a vector containing fixed (non-penalized) parameters and equal-size sub-vectors of penalized spline parameters.

Usage

Pcal.fun(nfixed, lambda, Pd.x)

Arguments

Value

A block diagonal penalty matrix of size (nfixed+pJ) given by Blockdiag(diag(0,nfixed), diag(lambda).kron.Pd.x).

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

Dd = diff(diag(1,5),diff=2) ## Difference penalty matrix for a vector of length 5
Pd = t(Dd) %*% Dd ## Penalty matrix of order 2
nfixed = 2 ## 2 unpenalized parameters
## Global penalty matrix when 2 unpenalized parameters and 2 additive terms with
##   2 vectors of 5 P-splines coefficients with lambda values 10 and 100 respectively.
Pcal.fun(nfixed=2,lambda=c(10,100),Pd)

Extract additive term estimates from a tvcure object.

Description

Extract additive term estimates from a tvcure object.

Usage

additive.tvcure(obj.tvcure, ngrid = 300, ci.level = 0.95)

Arguments

Value

A list with following elements:

• f0 : a function estimate of f_0.

• F0 : a function estimate of F_0.

• T : the follow-up time after which a unit is considered ‘cured’.

• nfixed1 : the number of non-penalized regression parameter in the long-term term (or quantum) submodel.

• J1 : number of additive terms in the long-term term (or quantum) submodel.

• additive.lab1 : labels of the additive terms in the long-term term (or quantum) submodel.

• K1 : number of P-spline parameters per additive term in the long-term term (or quantum) submodel.

• knots1 : list of length J1 containing the knots of the additive term in the long-term term (or quantum) submodel.

• f1.grid : list of length J1 containing for each additive term in the long-term term (or quantum) submodel, a list of length 3 with elements <x>, <y.mat> and <y.mat2>

  • Element <x> is a vector of ngrid equidistant values covering the range of values for the covariate ;

  • <y.mat> is (ngrid x 3) matrix containing in column 1 the estimated values of the additive term at <x> and the bounds of the pointwise credible interval for it in the other 2 columns.

  • <y.mat2> is (ngrid x 3) matrix containing in column 1 the estimated values of the additive term at <x> and the bounds of the simultaneous credible region for it in the other 2 columns.

• f1 : list of length J1 containing the estimated function of the corresponding additive term in the long-term term (or quantum) submodel.

• f1.se : list of length J1 containing the estimated standard error function of the corresponding additive term in the long-term term (or quantum) submodel.

The same definitions applies for nfixed2, J2, additive.lab2, K2, knots2, f2.grid, f2, f2.se with the additive terms in the short-term (or timing) submodel.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)

## Extract additive term estimates from tvcure object
obj = additive.tvcure(model)
names(obj)

Generation of a recentered cubic B-spline basis matrix.

Description

Generation of a cubic B-spline basis matrix with recentered columns to handle the identifiability constraint in additive models. See Wood (CRC Press 2017, pp. 175-176) for more details.

Usage

centeredBasis.gen(x, knots, cm = NULL, pen.order = 2)

Arguments

Value

List containing

• B : centered cubic B-spline matrix obtained by subtracting cm[j] from the jth B-spline in column j of the original B-spline matrix evaluated at x.

• Dd : difference matrix (of order pen.order) for the associated centered B-spline matrix.

• Pd : penalty matrix (of order pen.order) for the associated centered B-spline matrix.

• K : number of centered B-splines in the basis.

• cm : values subtracted from each column of the original B-spline matrix. By default, this is a vector containing the mean of each column in the original B-spline matrix.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

x = seq(0,1,by=.01)
knots = seq(0,1,length=5)
obj = centeredBasis.gen(x,knots)
matplot(x,obj$B,type="l",ylab="Centered B-splines")
colMeans(obj$B)

Deviance of a tvcure.object.

Description

Deviance for the fitted tvcure model in a tvcure.object.

Usage

## S3 method for class 'tvcure'
deviance(object, ...)

Arguments

Details

Deviance -2log(L/L.hat)

Value

The deviance as a numeric value, computed according to the model specified in the input object.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, AIC.tvcure, BIC.tvcure, logEvid

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
deviance(model)

Generic function for computing log-evidence

Description

This is a generic function returning the log-evidence for the class of the input object.

Usage

logEvid(object, ...)

Arguments

Value

The log-evidence as a numeric value, computed according to the model specified in the input object.

Log-evidence of a tvcure object.

Description

The log-evidence of the fitted tvcure model in a tvcure.object.

Usage

## S3 method for class 'tvcure'
logEvid(object, ...)

Arguments

Details

Provides the log-evidence (or log-marginal likelihood) of the fitted tvcure model in a given tvcure.object, where the evidence is the marginal posterior of the penalty parameters at their selected values.

Value

The log-evidence as a numeric value, computed according to the model specified in the input object.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, AIC.tvcure, BIC.tvcure

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
logEvid(model)

Plot visual information related to a tvcure object.

Description

Visualization of the estimated additive terms and of the reference (cumulative) hazard function in a tvcure object.

Usage

## S3 method for class 'tvcure'
plot(x, ngrid=300, ci.level=.95, pages=0, select=NULL,
                             fill=TRUE, pointwise=TRUE, mar=c(4,5,1,1),
                             xlim0=NULL, ylim0=NULL,
                             xlim1=NULL, ylim1=NULL, xlim2=NULL, ylim2=NULL,
                             equal.ylims=TRUE,...)

Arguments

Details

Plot of the fitted additive terms, as well as of the reference hazard f_0(t) and cumulative hazard F_0(t) functions of the fitted tvcure model in x.

Value

In addition to the plots, an invisible list generated by the additive.tvcure function is returned.

Author(s)

Philippe Lambert p.lambert@uliege.be based on the plot.gam function in mgcv for the pages argument.

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, print.tvcure

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
plot(model,pages=1)

Generic function to plot a shaded region around values of a scalar function.

Description

Generic function to plot a shaded region around values of a scalar function.

Usage

plotRegion(x, mat,
           add=FALSE,xlim=range(x),ylim=range(mat),
           colfill="#D9D9D980",lwd=2,xlab="",ylab="",main="",...)

Arguments

Value

No returned value (in addition to the plot).

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
obj = additive.tvcure(model) ## Extract additive terms

## Plot some of the fitted additive terms
## par(mfrow=c(1,2))
with(obj$f1.grid$x1, plotRegion(x=x,mat=y.mat,xlab="x1",ylab="f(x1)"))
with(obj$f1.grid$x2, plotRegion(x=x,mat=y.mat,xlab="x2",ylab="f(x2)"))

Predict method for tvcure model fits

Description

Predicted values based on a tvcure object.

Usage

## S3 method for class 'tvcure'
predict(object, newdata, ci.level=.95, ...)

Arguments

Value

A data frame containing, in addition to the optional newdata entries, the following elements:

• Hp : Matrix containing estimates of the cumulative population hazard H_p(t|x_{1:t}) with its credible interval bounds at time t given the history of covariates.

• lHp : Matrix containing estimates of the log cumulative population hazard \log H_p(t|x_{1:t}) with its standard error and credible interval bounds at time t given the history of covariates.

• se.lHp : Vector containing the standard errors of the estimated log cumulative population hazard at time t given the history of covariates.

• hp : Matrix containing estimates of the population hazard h_p(t|x_{1:t}) with its credible interval bounds at time t given the history of covariates.

• lhp : Matrix containing estimates of the log population hazard \log h_p(t|x_{1:t}) with its standard error and credible interval bounds at time t given the history of covariates.

• se.lhp : Vector containing the standard errors of the estimated log population hazard at time t given the history of covariates.

• Sp : Matrix containing estimates of the population survival fuction S_p(t|x_{1:t})=\exp(-H_p(t|x_{1:t})) with its credible interval bounds at time t given the history of covariates.

• pcure : Matrix containing estimates of the conditional cure probability of a unit still at tisk at time t, P(T=+\infty|T>t,x=x_t), with its credible interval bounds at time t if covariates remain constant from time t.

• llpcure : Matrix containing estimates of the conditional log-log cure probability of a unit still at tisk at time t, \log(-\log P(T=+\infty|T>t,x=x_t)), with its standard error and credible interval bounds at time t if covariates remain constant from time t.

• se.llpcure : Vector containing the standard errors of the estimated conditional log-log cure probability of a unit still at tisk at time t, \log(-\log P(T=+\infty|T>t,x=x_t)), if covariates remain constant from time t.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)

## Covariate profiles for which 'predicted' values are requested
newdata = subset(data, id==1 | id==4)[,-3] ## Focus on units 1 & 4
pred = predict(model,newdata)

## Visualize the estimated population survival fns for units 1 & 4
## par(mfrow=c(1,2))
with(subset(pred,id==1), plotRegion(time,Sp,main="Id=1",
                              ylim=c(0,1),xlab="t",ylab="Sp(t)"))
with(subset(pred,id==4), plotRegion(time,Sp,main="Id=4",
                              ylim=c(0,1),xlab="t",ylab="Sp(t)"))

Print summary information on a tvcure.object.

Description

Print summary information on a tvcure.object generated by tvcure.

Usage

## S3 method for class 'tvcure'
print(x, ci.level=.95,expEst=TRUE,
             digits.est=3,digits.edf=2,digits.tst=2,digits.Pvalue=3,...)

Arguments

Details

Provides summary measures on the estimation of the regression parameters and additive terms in the tvcure model corresponding to a tvcure.object generated by tvcure.

Value

No returned value (just printed summary).

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, tvcure.object, plot.tvcure

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
print(model)

Specification of the knots of a cubic B-spline basis for given data.

Description

Specification of the knots of a cubic B-spline basis for given data.

Usage

qknots(x, xmin=NULL, xmax=NULL,
       equid.knots = TRUE, pen.order=2, K=25)

Arguments

Value

a list containing the following elements:

• xmin : minimum value of the knots.

• xmax : maximum value of the knots.

• knots : vector containing the knots: equidistant if equid.knots is TRUE, based on quantiles of x otherwise.

• Pd : penalty matrix for the B-spline coefficients.

• pen.order : penalty order for the P-spline model.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

x = rnorm(100)
qknots(x)

Specification of smooth terms in formulas in the tvcure function.

Description

Specification of smooth terms in formulas in the tvcure function.

Usage

s(x, ref = NULL)

Arguments

Value

The submitted variable for which an additive term is required.

Show Copyright Information

Description

Displays the copyright information for the package in interactive mode.

Usage

show_c()

Value

No return value, called for its side effects of printing a message.

Show Warranty Disclaimer

Description

Displays a notice that the program comes with absolutely no warranty.

Usage

show_w()

Value

No return value, called for its side effects of printing a message.

Simulation of survival data with a cure fraction and time-varying covariates.

Description

Simulation of cure survival data in a counting process format with time-varying covariates. The population hazard at time t underlying the tvcure model is, for given covariate values,

h_p(t|{\bf v}(t),\tilde{\bf v}(t)) = \mathrm{e}^{\eta_\vartheta({\bf v}(t))+\eta_F(\tilde{\bf v}(t))} f_0(t)S_0(t)^{\exp(\eta_F(\tilde{\bf v}(t)))-1}

with linear predictors

\eta_\vartheta({\bf v}(t)) = \beta_0 + \beta_1 z_1(t) + \beta_2 z_2 + f_1(x_1(t)) + f_2(x_2(t))

\eta_F(\tilde{{\bf v}}(t)) = \gamma_1 z_3(t) + \gamma_2 z_4 + \tilde{f}_1(x_3(t)) + \tilde{f}_2(x_4(t))

where {\bf v}(t)=(z_1(t),z_2,x_1(t),x_2(t)), \tilde{\bf v}(t)=(z_3(t),z_4,x_3(t),x_4(t)), with time-varying covariates x_1(t), x_3(t) assumed identical and shared by the 2 submodels when shared.cov is TRUE.

The density f_0(t) governing the reference cumulative hazard dynamic is, by default, a Weibull with shape parameter 2.65 and scale parameter 100, ensuring that all susceptible units will experience the monitored event by time Tmax=300.

The functions defining the additive terms are

f_1(x_1)= -.63 + .57\arctan(4x_1) ~;~f_2(x_2)= -.5 \cos(2\pi x_2)

\tilde{f}_1(\tilde{x}_3) = .15 - .5 \cos\big(\pi(\tilde{x}_3-.75)\big)~;~ \tilde{f}_2(\tilde{x}_4) = .8\big(\tilde{x}_4-.5\big)

Covariates are generated as follows:

• z_1(t), z_3(t) are recentered time-varying Bernoulli(0.5) on (0,T_{max}) ;

• z_2, z_4 \sim N(0,1) ;

• x_1(t), x_2(t), x_3(t), x_4(t) follow random cubic polynomial trajectories on (0,T_{max}).

More details can be found in Lambert and Kreyenfeld (2024).

Usage

simulateTVcureData(n, seed, Tmax=300,
       f0F0 = list(f0=function(x) dweibull(x, 2.65, 100),
                   F0=function(x) pweibull(x, 2.65, 100)),
       beta, gam, shared.cov=TRUE,
       RC.dist=c("uniform","exponential","Tmax"),
       tRC.min = 120, mu.cens=40, get.details=TRUE)

Arguments

Value

A list with following elements:

• seeds : Seeds used to generate the data for each of the n units.

• tRC.min : Minimum right-censoring time value if the right-censoring time distribution is Uniform.

• RC.dist : Right-censoring distribution ("Uniform", "Exponential" or "Tmax").

• cure.rate : Underlying proportion of cured units (i.e. without an observed event by Tmax if the follow-up is not interrupted by that time due to right-censoring).

• RC.rate : Observed right-censoring rate.

• rawdata : Data frame containing the generated data in a counting process format with the detailed follow-up for each unit until the event or right-censoring occurs:

  • id : Unit identificator for each row.

  • time : Discrete observation times, starting at 1 for a given unit, until the end of its follow-up. The number of rows associated to a given unit corresponds to the follow-up duration.

  • event : Event indicator (1 if it occured, 0 otherwise) for given unit at a given time.

  • z1, z2, z3, z4, x1, x2, x3, x4 : Covariate values for a given unit at a given time.

• data.summary : Data frame with n rows containing summarized information on the generated data for each unit:

  • id : Unit identificator (the ith row corresponding to the ith unit).

  • t.obs : Observed event or right-censoring time.

  • delta : Event indicator (1 if it occured, 0 otherwise).

  • t.true : True (possibly unobserved) event time (Inf for a cured unit).

  • t.cens : True (possibly unobserved) right-censoring time.

  • cured : True (possibly unobserved) cure status.

• parameters : List containing the defining elements of the tvcure model:

  • beta : The regression parameters in the long-term survival (or quantum) submodel.

  • gam : The regression parameters in the short-term survival (or timing) submodel.

  • f.theta : A list of length 2 containing the functions defining the additive terms in the long-term survival (or quantum) submodel.

  • f.gam : A list of length 2 containing the functions defining the additive terms in the short-term survival (or timing) submodel.

  • f0 : Density function governing the dynamic of the reference cumulative hazard on (0,Tmax).

  • F0 : CDF governing the dynamic of the reference cumulative hazard on (0,Tmax).

• call : Function call.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Regression parameters
beta = c(beta0=.4, beta1=-.2, beta2=.15) ##  beta0 tunes the cure rate
gam = c(gam1=.2, gam2=.2)
## Data simulation
temp = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)
head(temp$rawdata) ## Overview of the simulated raw data
head(temp$data.summary) ## Overview of the summarized data
with(temp, c(cure.rate=cure.rate,RC.rate=RC.rate)) ## Cure and RC rates

Simulation of survival data with a cure fraction and time-varying covariates.

Description

Simulation of cure survival data in a counting process format with time-varying covariates. The population hazard at time t underlying the tvcure model is, for given covariate values,

h_p(t|{\bf v}(t),\tilde{\bf v}(t)) = \mathrm{e}^{\eta_\vartheta({\bf v}(t))+\eta_F(\tilde{\bf v}(t))} f_0(t)S_0(t)^{\exp(\eta_F(\tilde{\bf v}(t)))-1}

with linear predictors

\eta_\vartheta({\bf v}(t)) = \beta_0 + \beta_1 z_1(t) + \beta_2 z_2 + \beta_{f_1} f_1(x_1(t)) + \beta_{f_2} f_2(x_2(t))

\eta_F(\tilde{{\bf v}}(t)) = \gamma_1 z_3(t) + \gamma_2 z_4 + \gamma_{f_1} \tilde{f}_1(x_3(t)) + \gamma_{f_2} \tilde{f}_2(x_4(t))

where {\bf v}(t)=(z_1(t),z_2,x_1(t),x_2(t)), \tilde{\bf v}(t)=(z_3(t),z_4,x_3(t),x_4(t)), with time-varying covariates x_1(t), x_3(t) assumed identical and shared by the 2 submodels when shared.cov is TRUE.

The density f_0(t) governing the reference cumulative hazard dynamic is, by default, a Weibull with shape parameter 2.65 and scale parameter 100, ensuring that all susceptible units will experience the monitored event by time Tmax=300.

The functions defining the additive terms are

f_1(x_1)= -.63 + .57\arctan(4x_1) ~;~f_2(x_2)= -.5 \cos(2\pi x_2)

\tilde{f}_1(\tilde{x}_3) = .15 - .5 \cos\big(\pi(\tilde{x}_3-.75)\big)~;~ \tilde{f}_2(\tilde{x}_4) = .8\big(\tilde{x}_4-.5\big)

Covariates are generated as follows:

• z_1(t), z_3(t) are recentered time-varying Bernoulli(0.5) on (0,T_{max}) ;

• z_2, z_4 \sim N(0,1) ;

• x_1(t), x_2(t), x_3(t), x_4(t) follow random cubic polynomial trajectories on (0,T_{max}).

More details can be found in Lambert and Kreyenfeld (2024).

Usage

simulateTVcureData2(n, seed, Tmax=300,
       f0F0 = list(f0=function(x) dweibull(x, 2.65, 100),
                   F0=function(x) pweibull(x, 2.65, 100)),
       beta, gam, beta.f = rep(1,2), gam.f = rep(1,2), shared.cov=TRUE,
       RC.dist=c("uniform","exponential","Tmax"),
       tRC.min = 120, mu.cens=40, get.details=TRUE)

Arguments

Value

A list with following elements:

• seeds : Seeds used to generate the data for each of the n units.

• tRC.min : Minimum right-censoring time value if the right-censoring time distribution is Uniform.

• RC.dist : Right-censoring distribution ("Uniform", "Exponential" or "Tmax").

• cure.rate : Underlying proportion of cured units (i.e. without an observed event by Tmax if the follow-up is not interrupted by that time due to right-censoring).

• RC.rate : Observed right-censoring rate.

• rawdata : Data frame containing the generated data in a counting process format with the detailed follow-up for each unit until the event or right-censoring occurs:

  • id : Unit identificator for each row.

  • time : Discrete observation times, starting at 1 for a given unit, until the end of its follow-up. The number of rows associated to a given unit corresponds to the follow-up duration.

  • event : Event indicator (1 if it occured, 0 otherwise) for given unit at a given time.

  • z1, z2, z3, z4, x1, x2, x3, x4 : Covariate values for a given unit at a given time.

• data.summary : Data frame with n rows containing summarized information on the generated data for each unit:

  • id : Unit identificator (the ith row corresponding to the ith unit).

  • t.obs : Observed event or right-censoring time.

  • delta : Event indicator (1 if it occured, 0 otherwise).

  • t.true : True (possibly unobserved) event time (Inf for a cured unit).

  • t.cens : True (possibly unobserved) right-censoring time.

  • cured : True (possibly unobserved) cure status.

• parameters : List containing the defining elements of the tvcure model:

  • beta : The regression parameters in the long-term survival (or quantum) submodel.

  • gam : The regression parameters in the short-term survival (or timing) submodel.

  • beta.f : The multiplying coefficients of the additive terms in the long-term survival (or quantum) submodel.

  • gam.f : The multiplying coefficients of the additive terms in the short-term survival (or timing) submodel.

  • f.theta : A list of length 2 containing the functions defining the additive terms in the long-term survival (or quantum) submodel.

  • f.gam : A list of length 2 containing the functions defining the additive terms in the short-term survival (or timing) submodel.

  • f0 : Density function governing the dynamic of the reference cumulative hazard on (0,Tmax).

  • F0 : CDF governing the dynamic of the reference cumulative hazard on (0,Tmax).

• call : Function call.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Regression parameters
beta = c(beta0=.4, beta1=-.2, beta2=.15) ##  beta0 tunes the cure rate
gam = c(gam1=.2, gam2=.2)
beta.f = gam.f = rep(1,2) ## Multiply additive terms by 1.0 (by default)
## Data simulation
temp = simulateTVcureData2(n=500, seed=123,
                          beta=beta, gam=gam,
                          beta.f=beta.f, gam.f=gam.f,
                          RC.dist="exponential",mu.cens=550)
head(temp$rawdata) ## Overview of the simulated raw data
head(temp$data.summary) ## Overview of the summarized data
with(temp, c(cure.rate=cure.rate,RC.rate=RC.rate)) ## Cure and RC rates

Significance test of an additive term

Description

Significance test of an additive term relying on the methodology in Wood (Biometrika 2013). It is extracted from a hidden function in the 'mgcv' package. The additive term is estimated using the product of a matrix <X> and a vector <p>.

Usage

testStat(p, X, V, rank = NULL, type = 0, res.df = -1)

Arguments

Value

Returns a list with following elements:

• stat : Value of the test statistics

• pval : P-value of the test for the null hypothesis Ho: p=0

• rank : Effective dimension of <p>

Fit of a tvcure model.

Description

Fit of a double additive cure survival model with exogenous time-varying covariates.

Usage

tvcure(formula1, formula2, data,
       model0=NULL, noestimation=FALSE,
       baseline=c("S0","F0"), K0=20, pen.order0=2,
       K1=10, pen.order1=2, K2=10, pen.order2=2,
       phi.0=NULL, beta.0=NULL, gamma.0=NULL,
       a.tau=1, b.tau=1e-6, a.pen=1, b.pen=1e-4,
       tau.0=NULL, tau.min=1, tau.method = c("LPS","LPS2","Schall","grid","none"),
       psi.method = c("LM","NR","none"),
       lambda1.0=NULL, lambda1.min=1, lambda2.0=NULL, lambda2.min=1,
       lambda.method=c("LPS","LPS2","LPS3","nlminb","none"),
       logscale=FALSE,
       observed.hessian=TRUE, use.Rfast=TRUE, Wood.test=FALSE,
       ci.level=.95,
       criterion=c("logEvid","deviance","lpen","AIC","BIC","gradient"),
       criterion.tol=1e-2, grad.tol=1e-2,
       RDM.tol=1e-4, fun.tol=1e-3, Lnorm=c("Linf","L2"),
       iterlim=50, iter.verbose=FALSE, verbose=FALSE)

Arguments

Value

An object of type tvcure.object.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

Examples

require(tvcure)
## Simulated data generation
beta = c(beta0=.4, beta1=-.2, beta2=.15) ; gam = c(gam1=.2, gam2=.2)
data = simulateTVcureData(n=500, seed=123, beta=beta, gam=gam,
                          RC.dist="exponential",mu.cens=550)$rawdata
## TVcure model fitting
tau.0 = 2.7 ; lambda1.0 = c(40,15) ; lambda2.0 = c(25,70) ## Optional
model = tvcure(~z1+z2+s(x1)+s(x2), ~z3+z4+s(x3)+s(x4), data=data,
               tau.0=tau.0, lambda1.0=lambda1.0, lambda2.0=lambda2.0)
print(model)
plot(model, pages=1)

Object resulting from the fit of a tvcure model using function 'tvcure'.

Description

An object returned by the tvcure function: this is a list with various components related to the fit of such a model.

Value

A tvcure_object is a list with following elements:

• formula1 : A formula describing the linear predictor in the long-term (cure) survival (or quantum) submodel.

• formula2 : A formula describing the linear predictor in the short-term (cure) survival (or timing) submodel.

• baseline : Baseline ("S0" or "F0") used to specify the dependence of the cumulative hazard dynamics on covariates.

• id : the <id> of the unit associated to the data in a given line in the data frame.

• time : the integer time at which the observations are reported. For a given unit, it should be a sequence of CONSECUTIVE integers starting at 1 for the first observation.

• event : a sequence of 0-1 event indicators. For the lines corresponding to a given unit, it starts with 0 values concluded by a 0 in case of right-censoring or by a 1 if the event is observed at the end of the follow-up.

• regr1 : List returned by DesignFormula when evaluated on formula1.

• regr2 : List returned by DesignFormula when evaluated on formula2.

• K0 : Number of B-splines used to specify \log f_0(t).

• fit : A list containing different elements describing the fitted tvcure model:

  • llik : Log likelihood value of the fitted tvcure model at convergence.

  • lpen : Log of the penalized joint posterior at convergence.

  • dev : Deviance of the fitted tvcure model at convergence.

  • mu.ij : Expected value \mu_{ij}=h_p(t_{ij}|z(t_{ij}),x(t_{ij})) for the event indicator of unit i at time t_{ij}.

  • res : Standardized residual (d_{ij}-\mu_{ij})/\sqrt{\mu_{ij}} for unit i at time t_{ij} where \mu_{ij}=h_p(t_{ij}|z(t_{ij}),x(t_{ij})) and d_{ij} is the event indicator.

  • phi : Vector of length K_0 containing the estimated B-splines coefficients in \log f_0(t).

  • marginalized : Marginalization indicator (over penalty parameters) when reporting regression and spline parameter estimates.

  • nbeta : Number of regression and spline parameters in the long-term (cure) survival (or quantum) submodel.

  • ci.level : Selected level for credible intervals.

  • beta : (nbeta x 6) matrix containing the point estimates, standard errors, credible intervals, Z-scores and P-values of the regression and spline parameters in the long-term (cure) survival (or quantum) submodel.

  • ngamma : Number of regression and spline parameters in the short-term (cure) survival (or timing) submodel.

  • gamma : (ngamma x 6) matrix containing the point estimates, standard errors, credible intervals, Z-scores and P-values of the regression and spline parameters in the short-term (cure) survival (or timing) submodel.

  • gam : ngamma-vector with the point estimates of the regression and spline parameters in the short-term (cure) survival (or timing) submodel.

  • grad.beta : Gradient of the log joint posterior of <beta>, the regression and spline parameters in the long-term (cure) survival (or quantum) submodel.

  • Hes.beta : Hessian of the log joint posterior of <beta>.

  • Hes.beta0 : Hessian of the log joint posterior of <beta> (with the roughness penalty part omitted).

  • grad.gamma : Gradient of the log joint posterior of <gamma>, the regression and spline parameters in the short-term (cure) survival (or timing) submodel.

  • Hes.gamma : Hessian of the log joint posterior of <gamma>.

  • Hes.gamma0 : Hessian of the log joint posterior of <gamma> (with the roughness penalty part omitted).

  • Mcal.1 : Hessian of the log joint posterior of the spline parameters in <beta> conditionally on the non-penalized parameters.

  • Mcal.2 : Hessian of the log joint posterior of the spline parameters in <gamma> conditionally on the non-penalized parameters.

  • Hes.betgam : (nbeta x ngamma) matrix with the cross derivatives of the log joint posterior of (<beta>,<gamma>).

  • grad.regr : Gradient of the log joint posterior of <beta,gamma>.

  • Hes.regr : Hessian of the log joint posterior of <beta,gamma>.

  • Hes.regr0 : Hessian of the log joint posterior of <beta,gamma> (with the roughness penalty part omitted).

  • grad.phi : Gradient of the log joint posterior of <phi>, the spline parameters in \log f_0(t).

  • Hes.phi : Hessian of the log joint posterior of <phi>.

  • Hes.phi0 : Hessian of the log joint posterior of <phi> (with the roughness penalty part omitted).

  • T : Follow-up time after which a unit is declared cured in the absence of a past event.

  • t.grid : Grid of discrete time values on (1,T): 1,...,T.

  • f0.grid : Estimated values for f_0(t) on t.grid.

  • F0.grid : Estimated values for F_0(t) on t.grid.

  • S0.grid : Estimated values for S_0(t) on t.grid.

  • dlf0.grid : (ngrid x length(phi)) matrix with the jth line containing the gradient of \log f_0(t_j) w.r.t. <phi>.

  • dlF0.grid : (ngrid x length(phi)) matrix with the jth line containing the gradient of \log F_0(t_j) w.r.t. <phi>.

  • dlS0.grid : (ngrid x length(phi)) matrix with the jth line containing the gradient of \log S_0(t_j) w.r.t. <phi>.

  • k.ref : Index of the reference component in <phi> set to 0.0.

  • a, b : Hyperparameters of the Gamma(a,b) prior for the penalty parameters of the additive terms.

  • criterion : Criterion used to assess convergence of the estimation procedure.

  • grad.psi : Gradient of the log joint posterior of <phi[-k.ref]>, i.e. the spline parameters in \log f_0(t) with the fixed reference component omitted.

  • Hes.psi0 : Hessian of the log joint posterior of <phi[-k.ref]> (with the roughness penalty part omitted).

  • Hes.psi : Hessian of the log joint posterior of <phi[-k.ref]>.

  • tau : Selected value for the penalty parameter \tau tuning the smoothness of \log f_0(t).

  • pen.order0 : Penalty order for the P-splines used to specify \log f_0(t).

  • logscale : Logical: when TRUE, select \lambda_1 or \lambda_2 by maximizing p(\log(\lambda_k)|D), maximize p(\lambda_k|D) otherwise. (Default= TRUE).

  • lambda1 : Selected values for the penalty parameters \lambda_1 tuning the smoothness of the additive terms in the long-term (cure) survival (or quantum) submodel.

  • pen.order1 : Penalty order for the P-splines in the long-term survival (or quantum) submodel.

  • lambda2 : Selected values for the penalty parameters \lambda_2 tuning the smoothness of the additive terms in the short-term (cure) survival (or timing) submodel.

  • pen.order2 : Penalty order for the P-splines in the short-term survival (or timing) submodel.

  • tau.method : Method used to calculate the posterior mode of p(\tau_0|{\cal D}).

  • lambda.method : Method used to select the penalty parameters of the additive terms in the long-term survival (or quantum) submodel.

  • ED1 : Effective degrees of freedom for each of the additive terms in the long-term survival (or quantum) submodel, with the selected statistical test for significance and its P-value.

  • ED2 : Effective degrees of freedom for each of the additive terms in the short-term survival (or timing) submodel, with the selected statistical test for significance and its P-value.

  • ED1.Tr : Effective degrees of freedom for each of the additive terms in the long-term survival (or quantum) submodel, with Wood's statistical test for significance and its P-value.

  • ED2.Tr : Effective degrees of freedom for each of the additive terms in the short-term survival (or timing) submodel, with Wood's statistical test for significance and its P-value.

  • ED1.Chi2 : Effective degrees of freedom for each of the additive terms in the long-term survival (or quantum) submodel, with a Chi-square test for significance and its P-value.

  • ED2.Chi2 : Effective degrees of freedom for each of the additive terms in the short-term survival (or timing) submodel, with a Chi-square test for significance and its P-value.

  • nobs : Total number of observations.

  • n : Total number of units or subjects.

  • d : Total number of observed events.

  • ED1.tot : Total effective degrees of freedom for the long-term survival (or quantum) submodel.

  • ED2.tot : Total effective degrees of freedom for the short-term survival (or timing) submodel.

  • ED.tot : Total effective degrees of freedom for the tvcure model.

  • AIC : Akaike information criterion for the fitted model with a penalty calculated using the total effective degrees of freedom, -2log(L) + 2*ED.tot, larger values being preferred during model selection.

  • BIC : Bayesian (Schwarz) information criterion for the fitted model with a penalty calculated using the total effective degrees of freedom and the total number of observed events, -2log(L) + log(d)*ED.tot, smaller values being preferred during model selection.

  • levidence : Log-evidence of the fitted model, larger values being preferred during model selection.

  • iter : Number of iterations required to achieve convergence.

  • elapsed.time : Total duration (in seconds) of the estimation procedure.

• call : Function call.

• converged : Binary convergence status.

• logLik : Log-likelihood of the fitted model.

Author(s)

Philippe Lambert p.lambert@uliege.be

References

Lambert, P. and Kreyenfeld, M. (2025). Time-varying exogenous covariates with frequently changing values in double additive cure survival model: an application to fertility. Journal of the Royal Statistical Society, Series A. <doi:10.1093/jrsssa/qnaf035>

See Also

tvcure, print.tvcure, plot.tvcure