frailtypack (version 3.4.0)

predict.jointSurroPenal: S3method predict for the one-step Joint surrogate models for the evaluation of a canditate surrogate endpoint.

Description

Predict the treatment effect on the true endpoint ( \(\beta\)), based on the treatment effect observed on the surrogate endpoint ( \(\beta\)).

Usage

# S3 method for jointSurroPenal
predict(object, datapred = NULL, betaS.obs = NULL, 
betaT.obs = NULL, ntrial0 = NULL, var.used = "error.estim", alpha. = 0.05, 
dec = 3, colCI = "red", from = -2, to = 2, type = "Coef", ...)

Arguments

object

An object inheriting from jointSurroPenal class (output from calling the function jointSurroPenal or jointSurroCopPenal).

datapred

Dataset to use for the prediction. If this argument is specified, the data structure must be the same as the parameter data in the function jointSurroPenal or jointSurroCopPenal. However, if observation on the true endpoint are not available, columns timeT and statusT can be absent. In this case, the \(\beta\) are calculated using Cox proportional hazards models.

betaS.obs

Observed treatment effect on the surrogate endpoint, to use for the prediction of the treatment effect on the true endpoint. If not null, this value is used for prediction instead of datapred. The default is NULL.

betaT.obs

Observed treatment effect on the true endpoint. Used to assess the prediction if not null. The defaut is NULL.

ntrial0

Number of subjects include in the new trial. Required if betaS.obs is not null. The default is NULL.

var.used

This argument can take two values. The first one is "error.estim" and indicates if the prediction error take into account the estimation error of the estimates of the parameters. If the estimates are supposed to be known or if the dataset includes a high number of trials with a high number of subject per trial, value No.error can be used. The default is error.estim (highly recommended).

alpha.

The confidence level for the prediction interval. The default is 0.05

dec

The desired number of digits after the decimal point for parameters and confidence intervals. Default of 3 digits is used.

colCI

The color used to display the confidence interval.

from

The range (with to) over which the function will be plotted. The default is from -2 to 2

to

The range (with from) over which the function will be plotted. The default is from -2 to 2

type

The type of graphic, "Coef" for the log HR or "HR" for hazard ratio. If set to HR, the arguments from and to must take positive values. The default is "Coef".

...

other unused arguments. See the function (plotTreatPredJointSurro)

Value

Returns and display a dataframe including for each trial the number of included subjects (if available), the observed treatment effect on surrogate endpoint, the observed treatment effect on true endpoint (if available) and the predicted treatment effect on true enpoint with the associated prediction intervals. If the observe treatment effect on true endpoint (if available) is included into the prediction interval, the last columns contains "*". This function also produces a plot of predicted treatment effects on the true endpoint according to the given values of the treatment effects on the surrogate endpoint, with the prediction intervals.

Details

Prediction is based on the formulas described in (Burzikwosky et al., 2006). We do not consider the case in which the prediction take into account estimation error on the estimate of the treatment effect on the surrogate endpoint in the new trial.

References

Burzykowski T, Buyse M (2006). "Surrogate threshold effect: an alternative measure for meta-analytic surrogate endpoint validation." Pharmaceutical Statistics, 5(3), 173-186.ISSN 1539-1612.

Sofeu, C. L. and Rondeau, V. (2020). How to use frailtypack for validating failure-time surrogate endpoints using individual patient data from meta-analyses of randomized controlled trials. PLOS ONE; 15, 1-25.

See Also

jointSurroPenal, jointSurroCopPenal

Examples

# NOT RUN {

# }
# NOT RUN {

###--- Joint surrogate model ---###
###---evaluation of surrogate endpoints---###

data(dataOvarian)
joint.surro.ovar <- jointSurroPenal(data = dataOvarian, n.knots = 8, 
                init.kappa = c(2000,1000), indicator.alpha = 0, 
                nb.mc = 200, scale = 1/365)

# prediction of the treatment effects on the true endpoint in each trial of 
# the dataOvarian dataset
predict(joint.surro.ovar)

# prediction of the treatment effect on the true endpoint from an observed 
# treatment effect on the surrogate endpoint in a given trial

# in log HR
predict(joint.surro.ovar, betaS.obs = -0.797, betaT.obs = -1.018)
predict(joint.surro.ovar, type = "Coef", betaS.obs = -1, leg.y = 0, leg.x = 0.3, to = 2.3)
predict(joint.surro.ovar, type = "Coef", leg.y = 3.5, add.accept.area.betaS = F, to = 2.3)

# in HR
predict(joint.surro.ovar, betaS.obs = exp(-0.797), betaT.obs = exp(-1.018))
predict(joint.surro.ovar, type = "HR", betaS.obs = log(0.65), leg.y = 5, to = 2.3)
predict(joint.surro.ovar, type = "HR", leg.y = 5, add.accept.area.betaS = F, to = 2.3)
# }
# NOT RUN {

# }