| Title: | Win Time Methods for Time-to-Event Data in Clinical Trials |
|---|---|
| Description: | Performs an analysis of time-to-event clinical trial data using various "win time" methods, including 'ewt', 'ewtr', 'rmt', 'max', 'wtr', 'rwtr', and 'pwt'. These methods are used to calculate and compare treatment effects on ordered composite endpoints. The package handles event times, event indicators, and treatment arm indicators and supports calculations on observed and resampled data. Detailed explanations of each method and usage examples are provided in "Use of win time for ordered composite endpoints in clinical trials," by Troendle et al. (2024)<https://pubmed.ncbi.nlm.nih.gov/38417455/>. For more information, see the package documentation or the vignette titled "Introduction to wintime." |
| Authors: | James Troendle [aut, cre], Samuel Lawrence [aut] |
| Maintainer: | James Troendle <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.3.0 |
| Built: | 2024-12-01 08:26:36 UTC |
| Source: | CRAN |
This function reruns the desired wintime package method on a given number of bootstrap samples. This resampling method is recommended for all pairwise wintime methods including Win time ratio (WTR), Restricted win time ratio (RWTR), and Pairwise win time (PWT). This function is also recommended for the EWTR_composite max test (MAX).
bootstrap( type, rmst_restriction, model, n, m, Time, Delta, trt, cov, z_ewtr, z_comp, resample_num, seed )bootstrap( type, rmst_restriction, model, n, m, Time, Delta, trt, cov, z_ewtr, z_comp, resample_num, seed )
type |
A string value indicating the wintime package method that will run with resampling. |
rmst_restriction |
The RMT cutoff value (days). |
model |
A string value indicating the model used on observed data ('markov' or 'km'). |
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
Time |
A m x n matrix of event times (days). Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
trt |
A numeric vector of treatment arm indicators (1 for treatment, 0 for control). |
cov |
A n x p matrix of covariate values, where p is the number of covariates. Rows should represent participants and columns should represent covariate values. |
z_ewtr |
The Z-statistic of EWTR. |
z_comp |
The Z-statistic of the composite event approach. |
resample_num |
The number of desired bootstraps. |
seed |
The seed used for random number generation. |
A vector of length resample_num containing the calculated treatment effect estimates (for type='max' these are z-statistics) for each bootstrap.
This function fits a Cox Model to time-to-event data and calculates the z statistic. In the wintime package, this function is used for the EWTR-composite max test (MAX) method.
COMP(n, Time, Delta, cov, trt)COMP(n, Time, Delta, cov, trt)
n |
The total number of trial participants. |
Time |
A m x n matrix of event times (days), where m is the number of events in the hierarchy. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators, where m is the number of events in the hierarchy. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
cov |
A n x p matrix of covariate values, where p is the number of covariates. Rows should represent participants and columns should represent covariate values. |
trt |
A vector of length n containing treatment arm indicators (1 for treatment, 0 for control). |
A list containing: The z-statistic of the treatment effect from the Cox Model fit, the treatment effect estimate, the variance of the treatment effect estimate, the p-value for treatment effect.
Calculates the state space probabilities using a Kaplan-Meier model (recommended) or a Markov model. This function uses these probabilities to compare both arms and calculate the expected win time of the treatment arm.
EWT( m, dist_state0, dist_state1, unique_event_times0, unique_event_times1, nunique_event_times0, nunique_event_times1 )EWT( m, dist_state0, dist_state1, unique_event_times0, unique_event_times1, nunique_event_times0, nunique_event_times1 )
m |
The number of events in the hierarchy. |
dist_state0 |
A matrix of control arm state probabilities (returned from wintime::km() or wintime::markov()). |
dist_state1 |
A matrix of treatment arm state probabilities (returned from wintime::km() or wintime::markov()). |
unique_event_times0 |
A vector of unique control arm event times (days) (returned from wintime::km() or wintime::markov()). |
unique_event_times1 |
A vector of unique treatment arm event times (days) (returned from wintime::km() or wintime::markov()). |
nunique_event_times0 |
The number of unique control arm event times (returned from wintime::km() or wintime::markov()). |
nunique_event_times1 |
The number of unique treatment arm event times (returned from wintime::km() or wintime::markov()). |
The expected win time of the treatment arm.
Calculates the control group state space probabilities using a Markov model (recommended) or a Kaplan-Meier model. This function uses these probabilities to compare each participant's clinical state to a distribution of control group states.
EWTR( n, m, nunique, maxfollow, untimes, Time, Delta, dist, markov_ind, cov, trt )EWTR( n, m, nunique, maxfollow, untimes, Time, Delta, dist, markov_ind, cov, trt )
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
nunique |
The number of unique control group event times (returned from wintime::markov() or wintime::km()). |
maxfollow |
The max control group follow up time (days) (returned from wintime::markov() or wintime::km()). |
untimes |
A vector containing unique control group event times (days) (returned from wintime::markov() or wintime::km()). |
Time |
A m x n matrix of event times (days). Rows should represent events and columns should represent participants. Rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators Rows should represent events and columns should represent participants. Rows should be in increasing order of clinical severity. |
dist |
A matrix of control group state probabilities (returned from wintime::markov() or wintime::km()). |
markov_ind |
An indicator of the model type used (1 for Markov, 0 for Kaplan-Meier). |
cov |
A n x p matrix of covariate values, where p is the number of covariates. |
trt |
A vector of length n containing treatment arm indicators (1 for treatment, 0 for control). |
A list containing: The estimated treatment effect from the linear regression model, the variance, and the Z-statistic.
Win time difference
getWintimeIntegral(m, etimes, time0, time1, delta0, delta1)getWintimeIntegral(m, etimes, time0, time1, delta0, delta1)
m |
The number of events in the hierarchy. |
etimes |
A sorted vector of event times (days) (returned from wintime::setEventTimes()). |
time0 |
A vector containing the control person's event times (days). |
time1 |
A vector containing the treatment person's event times (days). |
delta0 |
A vector containing the control person's event indicators. |
delta1 |
A vector containing the treatment person's event indicators. |
This function calculates the win time difference integral for a single pair. This function is used in all pairwise win time methods.
The win time difference integral.
This function fits Kaplan-Meier models to calculate the state probabilities for each arm. In the wintime package, the returned state probability distributions are used in all non-pairwise methods. The Kaplan-Meier model is recommended for the Expected win time (EWT) method and the Restricted mean survival in favor of treatment (RMT) method.
km(n0, n1, m, Time, Delta)km(n0, n1, m, Time, Delta)
n0 |
The number of participants in the control arm. |
n1 |
The number of participants in the treatment arm. |
m |
The number of events in the hierarchy. |
Time |
A |
Delta |
A |
A list containing: a matrix of control arm state probabilities, a matrix of treatment arm state probabilities, a vector of unique control arm event times (days), a vector of unique treatment arm event times (days), the number of unique control arm event times, the number of unique treatment arm event times, the control arm max follow time (days), the treatment arm max follow time (days).
# ----------------------------- # Example inputs # ----------------------------- # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Number of control arm patients n0 <- sum(trt == 0) # Number of treatment arm patients n1 <- sum(trt == 1) # Number of events in the hierarchy m <- nrow(Time) # ------------------------ # km Examples # ------------------------ z <- km(n0, n1, m, Time, Delta) print(z)# ----------------------------- # Example inputs # ----------------------------- # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Number of control arm patients n0 <- sum(trt == 0) # Number of treatment arm patients n1 <- sum(trt == 1) # Number of events in the hierarchy m <- nrow(Time) # ------------------------ # km Examples # ------------------------ z <- km(n0, n1, m, Time, Delta) print(z)
This function fits an extended Markov model to calculate the state probabilities for each arm. In the wintime package, the returned state probability distributions are used in all non-pairwise methods. The extended Markov model is recommended for the Expected win time against reference (EWTR) method and the EWTR-composite max test (MAX) method.
markov(n0, n1, m, Time, Delta)markov(n0, n1, m, Time, Delta)
n0 |
The number of participants in the control arm. |
n1 |
The number of participants in the active treatment arm. |
m |
The number of events in the hierarchy. |
Time |
A |
Delta |
A |
A list containing: a matrix of control arm state probabilities, a matrix of treatment arm state probabilities, a vector of unique control arm event times (days), a vector of unique treatment arm event times (days), the number of unique control arm event times, the number of unique treatment arm event times, the control arm max follow time (days), the treatment arm max follow time (days).
# ----------------------------- # Example inputs # ----------------------------- # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Number of control arm patients n0 <- sum(trt == 0) # Number of treatment arm patients n1 <- sum(trt == 1) # Number of events in the hierarchy m <- nrow(Time) # ------------------------- # markov Examples # ------------------------- z <- markov(n0, n1, m, Time, Delta) print(z)# ----------------------------- # Example inputs # ----------------------------- # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Number of control arm patients n0 <- sum(trt == 0) # Number of treatment arm patients n1 <- sum(trt == 1) # Number of events in the hierarchy m <- nrow(Time) # ------------------------- # markov Examples # ------------------------- z <- markov(n0, n1, m, Time, Delta) print(z)
This function reruns the desired wintime package method on a given number of permutations. This resampling method is recommended for the Expected win time (EWT) and Restricted mean survival in favor of treatment (RMT) methods.
perm( type, rmst_restriction, model, n, m, Time, Delta, trt, cov, z_ewtr, z_comp, resample_num, seed )perm( type, rmst_restriction, model, n, m, Time, Delta, trt, cov, z_ewtr, z_comp, resample_num, seed )
type |
A string value indicating the wintime package method that will run with resampling. |
rmst_restriction |
The RMT cutoff value (days). |
model |
A string value indicating the model used on observed data ('markov' or 'km'). |
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
Time |
A m x n matrix of event times (days). Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
trt |
A numeric vector of treatment arm indicators (1 for treatment, 0 for control). |
cov |
A n x p matrix of covariate values, where p is the number of covariates. Rows should represent participants and columns should represent covariate values. |
z_ewtr |
The Z-statistic of EWTR. |
z_comp |
The Z-statistic of the composite event approach. |
resample_num |
The number of desired permutations. |
seed |
The seed used for random number generation. |
A vector of length resample_num containing the treatment effect estimates (for type='max' these are z-statistics) for each permutation.
This function calculates the sum of each pair's win time difference divided by the total number of pairs.
PWT(n, n0, n1, m, Time, Delta, tg, tau)PWT(n, n0, n1, m, Time, Delta, tg, tau)
n |
The total number of trial participants. |
n0 |
The number of control arm patients. |
n1 |
The number of treatment arm patients. |
m |
The number of events in the hierarchy. |
Time |
A m x n matrix of event time (days). Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
tg |
A numeric vector containing treatment arm indicators (1 for treatment, 0 for control). |
tau |
The maximum follow up time (days). |
The pairwise win time.
Calculates the state space probabilities using a Kaplan-Meier model (recommended) or a Markov model. This function uses these probabilities to compare both arms and calculate the expected win time of the treatment arm up to a given time point.
RMT( m, rmst_restriction, dist_state0, dist_state1, unique_event_times0, unique_event_times1, nunique_event_times0, nunique_event_times1 )RMT( m, rmst_restriction, dist_state0, dist_state1, unique_event_times0, unique_event_times1, nunique_event_times0, nunique_event_times1 )
m |
The number of events in the hierarchy. |
rmst_restriction |
The cutoff time point (days) for the calculation. |
dist_state0 |
A matrix of control arm state probabilities (returned from wintime::km() or wintime::markov()). |
dist_state1 |
A matrix of treatment arm state probabilities (returned from wintime::km() or wintime::markov()). |
unique_event_times0 |
A vector of unique control arm event times (days) (returned from wintime::km() or wintime::markov()). |
unique_event_times1 |
A vector of unique treatment arm event times (days) (returned from wintime::km() or wintime::markov()). |
nunique_event_times0 |
The number of unique control arm event times (returned from wintime::km() or wintime::markov()). |
nunique_event_times1 |
The number of unique treatment arm event times (returned from wintime::km() or wintime::markov()). |
The restricted mean survival in favor of the treatment arm.
This function calculates the ratio of losses to wins on treatment. It iterates through all pairs of treatment and control patients and uses their time-to-death (or most severe clinical event) to determine a win or loss. If death is inconclusive, then a winner is determined based on wintime.
RWTR(n, m, tau, tg, Time, Delta)RWTR(n, m, tau, tg, Time, Delta)
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
tau |
The maximum follow up time (days). |
tg |
A numeric vector containing treatment arm indicators (1 for treatment, 0 for control). |
Time |
A m x n matrix of event times (days), where m is the number of events in the hierarchy, and n is the total number of trial participants. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators, where m is the number of events in the hierarchy, and n is the total number of trial participants. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
A list containing: The ratio of losses to wins on treatment, the total number of wins, and the total number of losses.
This function creates a sorted vector of event times for a pair. This function is used in all pairwise functions.
setEventTimes(m, delta0, delta1, time0, time1, follow)setEventTimes(m, delta0, delta1, time0, time1, follow)
m |
The number of events in the hierarchy. |
delta0 |
A vector of event indicators for the control person. |
delta1 |
A vector of event indicators for the treatment person. |
time0 |
A vector of event times (days) for the control person. |
time1 |
A vector of event times (days) for the treatment person. |
follow |
The maximum follow up time (days). |
A sorted vector of event times (days) for a given pair.
This function creates the time_km and delta_km matrices used for wintime::km().
setKM(n, m, time, delta)setKM(n, m, time, delta)
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
time |
The row reversal of the Time matrix (days) (created inside wintime::km()). |
delta |
The row reversal of the Delta matrix (created inside wintime::km()). |
A list containing the event time matrix and the event indicator matrix used in wintime::km().
This function runs one of the win time methods on observed and resampled data.
wintime( type, Time, Delta, trt, cov = NULL, model = NULL, resample = NULL, resample_num = 0, rmst_restriction = NA, seed = NA )wintime( type, Time, Delta, trt, cov = NULL, model = NULL, resample = NULL, resample_num = 0, rmst_restriction = NA, seed = NA )
type |
A string value indicating the desired win time method. Methods include 'ewt', 'ewtr', 'rmt', 'max', 'wtr', 'rwtr', and 'pwt'. |
Time |
A |
Delta |
A |
trt |
A numeric vector containing treatment arm indicators (1 for treatment, 0 for control). |
cov |
Optional. A |
model |
Optional. String value. The type of model used to calculate state distributions. Options include 'km' and 'markov'. Default depends on |
resample |
Optional. String value. The resampling method run after the observed data calculation. Options include 'boot' and 'perm'. Default depends on |
resample_num |
Optional. The number of desired resamples. Default is 0. |
rmst_restriction |
Required only for |
seed |
Optional. Seed used for random number generation in resampling. |
A list containing: the observed treatment effect, a vector of length resample_num containing resampled treatment effects, a message
indicating the method ran and the type of resampling done, the variance, the p-value, the total wins on treatment (pairwise methods only),
the total losses on treatment (pairwise methods only). A warning message will be printed for combinations of type and model/resample
that are not recommended.
# ------------------------------ # Example Inputs # ------------------------------ # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Covariate vectors cov1 <- c(54,53,55,61,73,65,63,63,82,58,66,66) cov2 <- c(34.4,32.1,34.7,54.1,55.7,43.6,32.1,44.8,85.2,12.5,33.4,21.4) # Covariate vectors cov1 <- c(66,67,54,68,77,65,55,66,77,54) cov2 <- c(3,6,4,2,3,5,8,5,3,5) cov3 <- c(34.6,543.6,45.8,54.7,44.3,55.6,65.9,54.7,77.9,31.2) # Covariate matrix cov <- cbind(cov1, cov2, cov3) # ------------------------ # wintime Examples # ------------------------ # Run WTR z <- wintime("wtr", Time, Delta, trt) print(z) # Run EWT with default settings and 10 resamples z <- wintime("ewt", Time, Delta, trt, resample_num = 10) print(z) # Run EWTR with default settings z <- wintime("ewtr", Time, Delta, trt, cov = cov) print(z) # Run EWTR with KM model (This will produce a warning message) z <- wintime("ewtr", Time, Delta, trt, cov = cov, model = "km") print(z)# ------------------------------ # Example Inputs # ------------------------------ # Event time vectors TIME_1 <- c(256,44,29,186,29,80,11,380,102,33) TIME_2 <- c(128,44,95,186,69,66,153,380,117,33) TIME_3 <- c(435,44,95,186,69,270,1063,380,117,33) # Event time matrix Time <- rbind(TIME_1, TIME_2, TIME_3) # Event indicator vectors DELTA_1 <- c(1,0,1,0,1,1,1,0,1,0) DELTA_2 <- c(1,0,0,0,0,1,1,0,0,0) DELTA_3 <- c(0,0,0,0,0,0,0,0,0,0) # Event indicator matrix Delta <- rbind(DELTA_1, DELTA_2, DELTA_3) # Treatment arm indicator vector trt <- c(1,1,1,1,1,0,0,0,0,0) # Covariate vectors cov1 <- c(54,53,55,61,73,65,63,63,82,58,66,66) cov2 <- c(34.4,32.1,34.7,54.1,55.7,43.6,32.1,44.8,85.2,12.5,33.4,21.4) # Covariate vectors cov1 <- c(66,67,54,68,77,65,55,66,77,54) cov2 <- c(3,6,4,2,3,5,8,5,3,5) cov3 <- c(34.6,543.6,45.8,54.7,44.3,55.6,65.9,54.7,77.9,31.2) # Covariate matrix cov <- cbind(cov1, cov2, cov3) # ------------------------ # wintime Examples # ------------------------ # Run WTR z <- wintime("wtr", Time, Delta, trt) print(z) # Run EWT with default settings and 10 resamples z <- wintime("ewt", Time, Delta, trt, resample_num = 10) print(z) # Run EWTR with default settings z <- wintime("ewtr", Time, Delta, trt, cov = cov) print(z) # Run EWTR with KM model (This will produce a warning message) z <- wintime("ewtr", Time, Delta, trt, cov = cov, model = "km") print(z)
This function calculates the ratio of losses to wins on treatment. It iterates through all pairs of treatment and control patients and uses their win time difference as the deciding factor of a win or loss.
WTR(n, m, tau, tg, Time, Delta)WTR(n, m, tau, tg, Time, Delta)
n |
The total number of trial participants. |
m |
The number of events in the hierarchy. |
tau |
The maximum follow up time (days). |
tg |
A numeric vector containing treatment arm indicators (1 for treatment, 0 for control). |
Time |
A m x n matrix of event times (days). Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
Delta |
A m x n matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity. |
A list containing: The ratio of losses to wins on treatment, the total number of wins, and the total number of losses.