Package 'rpsftm'

Title: Rank Preserving Structural Failure Time Models
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.
Authors: 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 <[email protected]>
License: GPL-2
Version: 1.2.9
Built: 2024-12-08 06:56:21 UTC
Source: CRAN

Help Index

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 [email protected] (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

survdiff

coxph

survreg

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 coxph as the inner estimation tool.
...

any other arguments to pass to cox.zph.

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

cox.zph

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 rpsftm function.
...

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

rand, rpsftm

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 rpsftm function.
...

further arguments passed to or from other methods.

Value

a print of the underlying test object at the point estimate.

Author(s)

Simon Bond

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

print.rand, rpsftm

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 rpsftm() function.
...

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 Surv(time, status)~rand(arm,rx). Further terms can be added to the right hand side to adjust for covariates and use strata or cluster arguments.
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_all used to solve the estimating equation, but embedded within a list as per uniroot, with an extra element root_all, a vector of all roots found in the case of multiple solutions. The first element of root_all is 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, or survreg object. This will always include:

    • call: the R call object

    • formula: a formula representing any adjustments, strata or clusters- used for the update() function

    • terms: 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 rpsftm() function.
...

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 rpsftm() function. (with the name "formula" to agree with generic argument names)
...

further arguments passed to or from other methods.

Value

a survfit object.

Author(s)

Simon Bond

See Also

survfit