| Type: | Package |
| Title: | Rank Preserving Structural Failure Time Models |
| Version: | 1.2.9 |
| Date: | 2024-03-12 |
| Description: | Implements methods described by the paper Robins and Tsiatis (1991) <doi:10.1080/03610929108830654>. These use g-estimation to estimate the causal effect of a treatment in a two-armed randomised control trial where non-compliance exists and is measured, under an assumption of an accelerated failure time model and no unmeasured confounders. |
| Depends: | R (≥ 2.10) |
| License: | GPL-2 |
| Imports: | ggplot2, stats, survival |
| LazyData: | true |
| RoxygenNote: | 7.3.1 |
| Suggests: | knitr, rmarkdown, tableone, testthat |
| VignetteBuilder: | knitr |
| Language: | en-GB |
| Encoding: | UTF-8 |
| NeedsCompilation: | no |
| Packaged: | 2024-03-12 16:54:57 UTC; rstudio |
| Author: | Simon Bond [aut, cre] (primary author of code, secondary author of vignette), Annabel Allison [aut] (primary author of vignette, secondary author of code) |
| Maintainer: | Simon Bond <simon.bond7@nhs.net> |
| Repository: | CRAN |
| Date/Publication: | 2024-03-12 17:10:02 UTC |
rpsftm: a package to fit Rank Preserving Structural Failure Time Model
Description
This implements the method of Robins JM, Tsiatis AA.
The key function is rpsftm, which provides estimates of the causal parameter of interest.
Details
rpfstm: a package to fit Rank Preserving Structural Failure Time Model
Author(s)
Maintainer: Simon Bond simon.bond7@nhs.net (primary author of code, secondary author of vignette)
Authors:
Annabel Allison (primary author of vignette, secondary author of code)
References
Robins JM, Tsiatis AA. Correcting for non-compliance in randomized trials using rank preserving structural failure time models. Communications in Statistics–Theory and Methods 1991; 20: 2609–2631
See Also
Test the proportional hazards assumption of an RPSFTM/Cox Regression
Description
If the the fit inherits *both* rpsftm and coxph then this pulls out the genuine
survival::coxph object that is deeply nested in the object, and then runs survival::cox.zph on it.
Or it avoids overwriting the function from survival by calling survival::cox.zph directly if the object
does not inherit rpsftm. Or it fails.
Usage
cox.zph(fit, ...)
Arguments
fit |
the result of fitting a rpsftm model using |
... |
any other arguments to pass to |
Note
This does rely on the order of loading packages. The rpsftm package must be loaded after survival,
if both are required, to avoid the masking of synonymous functions causing errors.
See Also
Estimating Equations for rpsftm()
Description
Calculates the Estimating Equation to be solved in RPSFTM models
Usage
est_eqn(psi, data, formula, target = 0, test = "survdiff", autoswitch, ...)
Arguments
psi |
the parameter that measures how more rapidly the lifetime is expended under treatment |
data |
the data set that contains the variables. Must contain columns named: time, censor_time,rx, arm. Optionally a column named: treat_modifier |
formula |
a formula object of covariates to adjust for: |
target |
the value to subtract off from the z-statistic |
test |
the survival regression function to calculate the z-statistic: survdiff, coxph, survreg |
autoswitch |
a logical to autodetect cases of no switching. If TRUE, then if all observations in an arm have perfect compliance then recensoring is not applied in that arm. If FALSE the recensoring is applied regardless of perfect compliance. |
... |
arguments to supply to the test function. |
Value
A scalar value of the estimating equation: the z-statistics from a test minus a target value
Author(s)
Simon Bond
See Also
Extracting the z-statistic from a survival object
Description
Generic S3 methods to extract the z-statistic from a set of survival fit objects
Usage
extract_z(fit, ...)
## S3 method for class 'survdiff'
extract_z(fit, ...)
## S3 method for class 'coxph'
extract_z(fit, arm, ...)
## S3 method for class 'survreg'
extract_z(fit, arm, ...)
Arguments
fit |
a fitted survival object : survdiff, coxph, survreg |
... |
extendible arguments to the S3 method |
arm |
a character vector giving the name of the covariate representing the treatment arm. |
Value
a numeric value, the z statistic for the independence test of the treatment arm
Methods (by class)
-
extract_z(survdiff): Method for survdiff -
extract_z(coxph): Method for coxph objects -
extract_z(survreg): Method for survreg objects
Author(s)
Simon Bond
immdef
Description
Simulated data to use with the rpsftm function.
Usage
immdef
Format
A simulated data frame with 9 variables and 1000 observations representing a study where participants were randomly assigned to receive treatment immediately or deferred. Participants in the deferred arm could crossover and receive treatment. The primary endpoint was time to disease progression.
The data are based on a randomized controlled trial Concorde doi:10.1016/S0140-6736(94)90006-X
- id
participant ID number
- def
indicator that the participant was assigned to the Deferred treatment arm
- imm
indicator that the participant was assigned to the Immediate treatment arm
- censyrs
censoring time, in years, corresponding to the close of study minus the time of entry for each participant
- xo
an indicator that crossover occurred
- xoyrs
the time, in years, from entry to switching, or 0 for participants in the Immediate arm
- prog
an indicator of disease progression (1), or censoring (0)
- progyrs
time, in years, from entry to disease progression or censoring
- entry
the time of entry into the study, measured in years from the date of randomisation
Plot Method
Description
Function used to plot the KM curves of the treatment-free transformed times
Usage
## S3 method for class 'rpsftm'
plot(x, ...)
Arguments
x |
an object returned from the |
... |
further arguments passed to or from other methods. |
Value
a ggplot plot of the fitted KM curves. The underlying data.frame has variables
time: failure time
survival: estimated treatment-free survival probability
upper: upper confidence interval at level defined by alpha in the call to rpsftm
lower: lower confidence interval at level defined by alpha in the call to rpsftm
group: randomised treatment arm
Author(s)
Simon Bond
Examples
fit <- rpsftm(Surv(progyrs, prog)~rand(imm,1-xoyrs/progyrs),immdef, censyrs)
plot(fit)
library(ggplot2)
plot(fit)+
scale_linetype_discrete(labels=c("Control","Experimental"))+
ylim(0.5,1)+
geom_ribbon(aes(ymin=lower, ymax=upper, fill=group), alpha=0.3)+
labs(x="Time (years)", title=NULL, lty="Arm", fill="Arm")
Print method
Description
print method for rand() objects - to display the summary of rx, by arm
Usage
## S3 method for class 'rand'
print(x, ...)
Arguments
x |
a rand() object |
... |
further arguments passed to or from other methods. |
Value
a summary of rx values broken down by arm for a rand() object
Author(s)
Simon Bond
See Also
Print Method
Description
Function used to print of the underlying test object at the point estimate of a rpsftm object
Usage
## S3 method for class 'rpsftm'
print(x, ...)
Arguments
x |
an object returned from the |
... |
further arguments passed to or from other methods. |
Value
a print of the underlying test object at the point estimate.
Author(s)
Simon Bond
modified version of print.coxph
Description
this drops the "arm" term as this is not a real parameter
Usage
## S3 method for class 'rpsftm.coxph'
print(x, digits = max(options()$digits - 4, 3), ...)
Arguments
x |
an coxph() |
digits |
the number of digits to print out |
... |
further arguments |
modified version of print.summary.coxph
Description
this drops the "arm" term as this is not a real parameter
Usage
## S3 method for class 'rpsftm.summary.coxph'
print(
x,
digits = max(getOption("digits") - 3, 3),
signif.stars = getOption("show.signif.stars"),
...
)
Arguments
x |
the result of a call to |
digits |
significant digits to print |
signif.stars |
show star to highlight small p-values |
... |
further arguments for future methods |
modified version of print.summary.survreg
Description
this drops the "arm" term as this is not a real parameter
Usage
## S3 method for class 'rpsftm.summary.survreg'
print(x, digits = max(options()$digits - 4, 3), ...)
Arguments
x |
the result of a call to |
digits |
significant digits to print |
... |
further arguments for future methods |
modified version of print.survreg
Description
this drops the "arm" term as this is not a real parameter
Usage
## S3 method for class 'rpsftm.survreg'
print(x, ...)
Arguments
x |
a survreg() object |
... |
further arguments |
rand functions to use in the rpsftm() formula
Description
A function that is defined to be used in the formula argument, and identified as specials in the terms() object
Usage
rand(arm, rx)
Arguments
arm |
the randomised treatment arm. a factor with 2 levels, or numeric variable with values 0/1. |
rx |
the proportion of time on active treatment (arm=1 or the non-reference level of the factor) |
Value
matrix with two columns named arm and rx. These can be used in the formula argument to rpsftm()
Author(s)
Simon Bond
See Also
Examples
x <- with(immdef, rand(imm , 1 - xoyrs / progyrs ) )
x
class(x)
y <- as.data.frame(x)
head(y)
residual() method for rpsftm objects
Description
Function to apply residual method to rpsftm objects
Usage
## S3 method for class 'rpsftm'
residuals(object, ...)
Arguments
object |
an object returned from the |
... |
further arguments passed to or from other methods. |
Value
a residuals object.
Author(s)
Simon Bond
See Also
residuals residuals.coxph residuals.survreg
Rank Preserving Structural Failure Time Model
Description
Main Function used for estimating causal parameters under the Rank Preserving Structural Failure Time Model
Usage
rpsftm(
formula,
data,
censor_time,
subset,
na.action,
test = survdiff,
low_psi = -1,
hi_psi = 1,
alpha = 0.05,
treat_modifier = 1,
autoswitch = TRUE,
n_eval_z = 100,
...
)
Arguments
formula |
a formula with a minimal structure of |
data |
an optional data frame that contains variables |
censor_time |
variable or constant giving the time at which censoring would, or has occurred. This should be provided for all observations unlike standard Kaplan-Meier or Cox regression where it is only given for censored observations. If no value is given then re-censoring is not applied. |
subset |
expression indicating which subset of the rows of data should be used in the fit. This can be a logical vector (which is replicated to have length equal to the number of observations), a numeric vector indicating which observation numbers are to be included (or excluded if negative), or a character vector of row names to be included. All observations are included by default. |
na.action |
a missing-data filter function. This is applied to the model.frame after any subset argument has been used. Default is options()$na.action. |
test |
the survival regression function to calculate the z-statistic: survdiff, coxph, survreg |
low_psi |
the lower limit of the range to search for the causal parameter |
hi_psi |
the upper limit of the range to search for the causal parameter |
alpha |
the significance level used to calculate confidence intervals |
treat_modifier |
an optional variable that psi is multiplied by on an individual observation level to give differing impact to treatment. |
autoswitch |
a logical to autodetect cases of no switching. If TRUE, then if all observations in an arm have perfect compliance then recensoring is not applied in that arm. If FALSE the recensoring is applied regardless of perfect compliance. |
n_eval_z |
The number of points between hi_psi and low_psi at which to evaluate the Z-statistics in the estimating equation. Default is 100. |
... |
arguments to supply to the test function. |
Details
the formula object Surv(time, status)~rand(arm,rx). rand() stands
for randomisation, both the randomly assigned and actual observed treatment.
arm: the randomised treatment arm. a factor with 2 levels, or numeric variable with values 0/1.
rx: the proportion of time on active treatment (arm=1 or the non-reference level of the factor)
Further adjustment terms can be added on the right hand side of the formula if desired, included strata()
or cluster() terms.
Value
a rpsftm method object that is a list of the following:
psi: the estimated parameter
fit: a survdiff object to produce Kaplan-Meier curves of the estimated counterfactual untreated failure times for each treatment arm
CI: a vector of the confidence interval around psi
Sstar: the recensored
Surv()data using the estimate value of psi to give counterfactual untreated failure times.rand: the rand() object used to specify the allocated and observed amount of treatment.
ans: the values from
uniroot_allused to solve the estimating equation, but embedded within a list as peruniroot, with an extra elementroot_all, a vector of all roots found in the case of multiple solutions. The first element ofroot_allis subsequently used.eval_z: a data frame with the Z-statistics from the estimating equation evaluated at a sequence of values of psi. Used to plot and check if the range of values to search for solution and limits of confidence intervals need to be modified.
Further elements corresponding to either a
survdiff,coxph, orsurvregobject. This will always include:call: the R call object
formula: a formula representing any adjustments, strata or clusters- used for the
update()functionterms: a more detailed representation of the model formula
Author(s)
Simon Bond
See Also
survdiff, coxph.object, survreg.object
Examples
?immdef
fit <- rpsftm(Surv(progyrs, prog)~rand(imm,1-xoyrs/progyrs),immdef, censyrs)
print(fit)
summary(fit)
plot(fit)
summary Method
Description
Function used to summarise the fitted model to an rpsftm object
Usage
## S3 method for class 'rpsftm'
summary(object, ...)
Arguments
object |
an object returned from the |
... |
further arguments passed to or from other methods. |
Value
a summary of the fitted regression model.
Author(s)
Simon Bond
survfit() method for rpsftm objects
Description
Function to apply survfit method to rpsftm objects
Usage
## S3 method for class 'rpsftm'
survfit(formula, ...)
Arguments
formula |
an object returned from the |
... |
further arguments passed to or from other methods. |
Value
a survfit object.
Author(s)
Simon Bond
See Also
termsinner
Description
A function taken from the survival library - it is not exported from there hence a local copy
Usage
termsinner(x, ...)
Arguments
x |
an R object |
... |
extendible arguments to the S3 method |
Value
a list of variables referred to in a formula or call object
a character vector
Finds many (all) roots of one equation within an interval
Description
The function uniroot_all searches the interval from lower to upper for several roots of a function f with respect to its first argument.
Usage
uniroot_all(
f,
interval,
lower = min(interval),
upper = max(interval),
tol = .Machine$double.eps^0.2,
maxiter = 1000,
trace = 0,
n = 100,
...
)
Arguments
f |
the function for which the root is sought. This function needs to accept a vector of input values. |
interval |
a vector containing the end-points of the interval to be searched for the root. |
lower |
the lower end point of the interval to be searched. |
upper |
the upper end poitn of the interval to be searched. |
tol |
the desired accuracy (convergence tolerance). Passed to function |
trace |
integer numberl if positive, tracing information is produced. Higher values giving more details. Passed to function |
n |
number of subintervals in which the root is sought. |
... |
additional named or unnamed arguments to be passed to |
Details
this is a copy taken from the package rootSolve but imported here to avoid dependency
Value
a vector with the roots found in the interval.
Author(s)
Karline Soetaert <karline.soetaert@nioz.nl> - original . Copied by Simon Bond.
See Also
Untreated Event Time
Description
Calculates the counterfactual untreated event time, possibly using the recensoring method, assuming a given parameter value and returns a Surv() object
Usage
untreated(psi, time, delta, censor_time, rx, arm, autoswitch)
Arguments
psi |
the parameter that measures how more rapidly the lifetime is expended under treatment |
time |
the observed failure or censoring time. |
delta |
the status of the time: 1 = observed, 0 = censored. |
censor_time |
the theoretical censoring time, either observed or set after time. Set to Inf to ignore recensoring. |
rx |
the proportion of time spent on treatment |
arm |
the randomised arm. Either a numerical indicator, with 0 as the placebo, or a factor with the lowest level as placebo. |
autoswitch |
a logical to autodetect cases of no switching. If TRUE, then if all observations in an arm have perfect compliance then recensoring is not applied in that arm. If FALSE the recensoring is applied regardless of perfect compliance. |
Value
A Surv() object
Author(s)
Simon Bond