Type: Package
Title: Win Time Methods for Time-to-Event Data in Clinical Trials
Version: 0.4.0
Description: Performs an analysis of time-to-event clinical trial data using various "win time" methods, including 'ewt', 'ewtr', 'rmt', 'ewtp', 'rewtp', 'ewtpr', 'rewtpr', 'max', 'wtr', 'rwtr', 'pwt', and 'rpwt'. 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."
URL: https://pubmed.ncbi.nlm.nih.gov/38417455/
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
VignetteBuilder: knitr
Imports: survival
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown (≥ 2.0)
Config/testthat/edition: 3
Depends: R (≥ 3.5.0)
NeedsCompilation: no
Packaged: 2025-06-30 18:44:19 UTC; troendlj
Author: James Troendle [aut, cre], Samuel Lawrence [aut]
Maintainer: James Troendle <james.troendle@nih.gov>
Repository: CRAN
Date/Publication: 2025-06-30 19:00:02 UTC

Run composite analysis

Description

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.

Usage

COMP(n, Time, Delta, cov, trt)

Arguments

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).

Value

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.

Expected win time

Description

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.

Usage

EWT(
  m,
  dist_state0,
  dist_state1,
  unique_event_times0,
  unique_event_times1,
  nunique_event_times0,
  nunique_event_times1
)

Arguments

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

Value

A list of the expected win time of the treatment arm, the components of the treatment effect.

Expected win time against trial population

Description

Calculates the combined arm state space probabilities using a Markov model or a Kaplan-Meier model (recommended). This function uses these probabilities to compare each participant's clinical state to a distribution of combined arm states.

Usage

EWTP(
  n,
  m,
  nunique,
  maxfollow,
  untimes,
  Time,
  Delta,
  dist,
  markov_ind,
  cov,
  trt
)

Arguments

n

The total number of trial participants.

m

The number of events in the hierarchy.

nunique

The number of unique combined arm event times (returned from wintime::markov() or wintime::km()).

maxfollow

The max combined arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes

A vector containing unique combined arm 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 combined arm 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).

Value

A list containing: The estimated treatment effect from the linear regression model, the variance, the Z-statistic, the components of the treatment effect, and the variance of the components.

Expected win time against trial population With redistribution to the right

Description

Calculates the combined arm state space probabilities using a Markov model or a Kaplan-Meier model (recommended). This function uses these probabilities to compare each participant's clinical state to a distribution of combined arm states. Calculation is extended by redistribution-to-the-right principles

Usage

EWTPR(
  n,
  m,
  nunique2,
  maxfollow2,
  untimes2,
  Time,
  Delta,
  dist2,
  markov_ind,
  cov,
  trt,
  comkm,
  trans_prob2,
  nunique1,
  maxfollow1,
  untimes1,
  dist1,
  trtkm,
  trans_prob1,
  nunique0,
  maxfollow0,
  untimes0,
  dist0,
  conkm,
  trans_prob0,
  nimp
)

Arguments

n

The total number of trial participants.

m

The number of events in the hierarchy.

nunique2

The number of unique combined arm event times (returned from wintime::markov() or wintime::km()).

maxfollow2

The max combined arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes2

A vector containing unique combined arm 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.

dist2

A matrix of combined arm 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).

comkm

A m x nunique matrix of combined arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob2

A (m x m x number of combined arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th combined arm event time. (returned from wintime::markov() or wintime::km()).

nunique1

The number of unique trt arm event times (returned from wintime::markov() or wintime::km()).

maxfollow1

The max trt arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes1

A vector containing unique trt arm event times (days) (returned from wintime::markov() or wintime::km()).

dist1

A matrix of trt arm state probabilities (returned from wintime::markov() or wintime::km()).

trtkm

A m x nunique matrix of trt arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob1

A (m x m x number of trt arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th trt arm event time. (returned from wintime::markov() or wintime::km()).

nunique0

The number of unique control arm event times (returned from wintime::markov() or wintime::km()).

maxfollow0

The max control arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes0

A vector containing unique control arm event times (days) (returned from wintime::markov() or wintime::km()).

dist0

A matrix of control arm state probabilities (returned from wintime::markov() or wintime::km()).

conkm

A m x nunique matrix of control arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob0

A (m x m x number of control arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th control arm event time. (returned from wintime::markov() or wintime::km()).

nimp

The number of random imputations.

Value

A list containing: The estimated treatment effect from the linear regression model, the variance, the Z-statistic, the components of the treatment effect, and the variance of the components.

Expected win time against reference

Description

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.

Usage

EWTR(
  n,
  m,
  nunique,
  maxfollow,
  untimes,
  Time,
  Delta,
  dist,
  markov_ind,
  cov,
  trt
)

Arguments

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).

Value

A list containing: The estimated treatment effect from the linear regression model, the variance, the Z-statistic, the components of the treatment effect, and the variance of the components.

Pairwise win time

Description

This function calculates the sum of each pair's win time difference divided by the total number of pairs.

Usage

PWT(n, n0, n1, m, Time, Delta, tg, tau)

Arguments

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).

Value

The pairwise win time, and the components of the pairwise win time.

Expected win time against trial population

Description

Calculates the combined arm state space probabilities using a Markov model or a Kaplan-Meier model (recommended). This function uses these probabilities to compare each participant's clinical state to a distribution of combined arm states.

Usage

REWTP(
  n,
  m,
  nunique,
  maxfollow,
  untimes,
  Time,
  Delta,
  dist,
  markov_ind,
  cov,
  trt,
  time_restriction
)

Arguments

n

The total number of trial participants.

m

The number of events in the hierarchy.

nunique

The number of unique combined arm event times (returned from wintime::markov() or wintime::km()).

maxfollow

The max combined arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes

A vector containing unique combined arm 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 combined arm 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).

time_restriction

The time restriction (days) for calculation.

Value

A list containing: The estimated treatment effect from the linear regression model, the variance, the Z-statistic, the components of the treatment effect, and the variance of the components.

Time Restricted Expected win time against trial population With redistribution to the right

Description

Calculates the combined arm state space probabilities using a Markov model or a Kaplan-Meier model (recommended). This function uses these probabilities to compare each participant's clinical state to a distribution of combined arm states. Calculation is extended by redistribution-to-the-right principles and truncated at the user-specified time_restriction (days).

Usage

REWTPR(
  n,
  m,
  nunique2,
  maxfollow2,
  untimes2,
  Time,
  Delta,
  dist2,
  markov_ind,
  cov,
  trt,
  comkm,
  trans_prob2,
  time_restriction,
  nunique1,
  maxfollow1,
  untimes1,
  dist1,
  trtkm,
  trans_prob1,
  nunique0,
  maxfollow0,
  untimes0,
  dist0,
  conkm,
  trans_prob0,
  nimp
)

Arguments

n

The total number of trial participants.

m

The number of events in the hierarchy.

nunique2

The number of unique combined arm event times (returned from wintime::markov() or wintime::km()).

maxfollow2

The max combined arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes2

A vector containing unique combined arm 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.

dist2

A matrix of combined arm 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).

comkm

A m x nunique matrix of combined arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob2

A (m x m x number of combined arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th combined arm event time. (returned from wintime::markov() or wintime::km()).

time_restriction

The time restriction (days) for calculation.

nunique1

The number of unique trt arm event times (returned from wintime::markov() or wintime::km()).

maxfollow1

The max trt arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes1

A vector containing unique trt arm event times (days) (returned from wintime::markov() or wintime::km()).

dist1

A matrix of trt arm state probabilities (returned from wintime::markov() or wintime::km()).

trtkm

A m x nunique matrix of trt arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob1

A (m x m x number of trt arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th trt arm event time. (returned from wintime::markov() or wintime::km()).

nunique0

The number of unique control arm event times (returned from wintime::markov() or wintime::km()).

maxfollow0

The max control arm follow up time (days) (returned from wintime::markov() or wintime::km()).

untimes0

A vector containing unique control arm event times (days) (returned from wintime::markov() or wintime::km()).

dist0

A matrix of control arm state probabilities (returned from wintime::markov() or wintime::km()).

conkm

A m x nunique matrix of control arm survival probabilities (returned from wintime::markov() or wintime::km()).

trans_prob0

A (m x m x number of control arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th control arm event time. (returned from wintime::markov() or wintime::km()).

nimp

The number of random imputations.

Value

A list containing: The estimated treatment effect from the linear regression model, the variance, the Z-statistic, the components of the treatment effect, and the variance of the components.

Restricted mean survival in favor of treatment

Description

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.

Usage

RMT(
  m,
  time_restriction,
  dist_state0,
  dist_state1,
  unique_event_times0,
  unique_event_times1,
  nunique_event_times0,
  nunique_event_times1
)

Arguments

m

The number of events in the hierarchy.

time_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()).

Value

A list containing: The restricted mean survival in favor of the treatment arm, the components of the treatment effect.

Time Restricted Pairwise win time

Description

This function calculates the sum of each pair's win time difference (truncated at the user-specified time_restriction (days)) divided by the total number of pairs.

Usage

RPWT(n, n0, n1, m, Time, Delta, tg, tau, time_restriction)

Arguments

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).

time_restriction

The time restriction (days) for calculation.

Value

The pairwise win time, and the components of the pairwise win time.

Restricted win time ratio

Description

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.

Usage

RWTR(n, m, tau, tg, Time, Delta)

Arguments

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.

Value

A list containing: The ratio of losses to wins on treatment, the total number of wins, and the total number of losses.

Win time ratio

Description

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.

Usage

WTR(n, m, tau, tg, Time, Delta)

Arguments

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.

Value

A list containing: The ratio of losses to wins on treatment, the total number of wins, and the total number of losses.

Resample using bootstraps

Description

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), Pairwise win time (PWT), and Restricted Pairwise win time (RPWT). This function is also recommended for the EWTR_composite max test (MAX).

Usage

bootstrap(
  type,
  time_restriction,
  model,
  n,
  m,
  Time,
  Delta,
  trt,
  cov,
  z_ewtr,
  z_comp,
  resample_num,
  seed,
  nimp
)

Arguments

type

A string value indicating the wintime package method that will run with resampling.

time_restriction

The time 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.

nimp

The number of random imputations for Redistribution-to-the-right.

Value

A list of a vector of length resample_num containing the calculated treatment effect estimates (for type='max' these are z-statistics) for each bootstrap, a m x resample_num matrix of the components of the treatment effect.

Helper functions for package functions

Description

Win time difference

Usage

getWintimeIntegral(m, etimes, time0, time1, delta0, delta1)

Arguments

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.

Details

This function calculates the win time difference integral for a single pair. This function is used in all pairwise win time methods.

Value

A list of the win time difference integral and its components.

Win time difference with time restriction

Description

This function calculates the win time difference integral for a single pair with truncation at time_restriction. This function is used in all pairwise win time methods.

Usage

getWintimeIntegral_rest(
  m,
  etimes,
  time0,
  time1,
  delta0,
  delta1,
  time_restriction
)

Arguments

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.

time_restriction

The time restriction (days) for calculation.

Value

A list of the win time difference integral and its components.

Fit a Kaplan-Meier model

Description

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.

Usage

km(n0, n1, m, Time, Delta)

Arguments

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 ⁠m x (n0 + n1)⁠ 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 (n0 + n1)⁠ matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity.

Value

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), a matrix of combined arm state probabilities, a vector of unique combined arm event times (days), the number of unique combined arm event times, the combined arm max follow time (days), a (m x number unique combined arm event times) matrix of combined arm km survival probabilities, matrix of trt arm km survival probabilities, matrix of control arm km survival probabilities.

Examples

# -----------------------------
# 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)

Fit a Markov model

Description

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.

Usage

markov(n0, n1, m, Time, Delta)

Arguments

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 ⁠m x (n0 + n1)⁠ 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 (n0 + n1)⁠ matrix of event indicators. Rows should represent events and columns should represent participants. Event rows should be in increasing order of clinical severity.

Value

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), a matrix of combined arm state probabilities, a vector of unique combined arm event times (days), the number of unique combined arm event times, the combined arm max follow time (days), a (m x m x number of combined arm event times) matrix where (i,j,k)'th value is transition probability from state i to state j at k'th combined arm event time, matrix where (i,j,k)'th value is transition probability from state i to state j at k'th trt arm event time, matrix where (i,j,k)'th value is transition probability from state i to state j at k'th control arm event time.

Examples

# -----------------------------
# 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)

Resample using permutations

Description

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.

Usage

perm(
  type,
  time_restriction,
  model,
  n,
  m,
  Time,
  Delta,
  trt,
  cov,
  z_ewtr,
  z_comp,
  resample_num,
  seed,
  nimp
)

Arguments

type

A string value indicating the wintime package method that will run with resampling.

time_restriction

The time 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.

nimp

The number of random imputations for Redistribution-to-the-right.

Value

A list of a vector of length resample_num containing the treatment effect estimates (for type='max' these are z-statistics) for each permutation, a m x resample_num matrix of the components of the treatment effect..

Created a sorted vector of event times

Description

This function creates a sorted vector of event times for a pair. This function is used in all pairwise functions.

Usage

setEventTimes(m, delta0, delta1, time0, time1, follow)

Arguments

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).

Value

A sorted vector of event times (days) for a given pair.

Set event times and indicators used in the Kaplan-Meier survival curve calculation

Description

This function creates the time_km and delta_km matrices used for wintime::km().

Usage

setKM(n, m, time, delta)

Arguments

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

Value

A list containing the event time matrix and the event indicator matrix used in wintime::km().

Run a win time calculation

Description

This function runs one of the win time methods on observed and resampled data.

Usage

wintime(
  type,
  Time,
  Delta,
  trt,
  cov = NULL,
  model = NULL,
  resample = NULL,
  resample_num = 0,
  time_restriction = NA,
  seed = NA,
  nimp = 0
)

Arguments

type

A string value indicating the desired win time method. Methods include 'ewt', 'ewtr', 'rmt', 'max', 'wtr', 'rwtr', 'pwt', 'ewtp', 'rewtp', 'ewtpr','rewtpr', and 'rpwt'.

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.

trt

A numeric vector containing treatment arm indicators (1 for treatment, 0 for control).

cov

Optional. A ⁠n x p⁠ matrix of covariate values, where n is the total number of trial participants and p is the number of covariates. Rows should represent participants and columns should represent covariate values.

model

Optional. String value. The type of model used to calculate state distributions. Options include 'km' and 'markov'. Default depends on type.

resample

Optional. String value. The resampling method run after the observed data calculation. Options include 'boot' and 'perm'. Default depends on type.

resample_num

Optional. The number of desired resamples. Default is 0.

time_restriction

Required only for type = 'rmt','rewtp','rewtpr', and 'rpwt'. The cutoff time (days).

seed

Optional. Seed used for random number generation in resampling.

nimp

Required only for type = 'ewtpr','rewtpr'. The number of random imputations for Redistribution-to-the-right.

Details

The type parameter specifies the procedure you would like to run. 'ewt' is Expected Win Time. 'ewtr' is Expected Win Time Against Reference (Control Arm). 'rmt' is Restricted Mean Time in Favor of Treatment. 'max' is the MAX procedure (max(COMP,EWTR)). 'wtr' is Win Time Ratio. 'rwtr' is Restricted Win Time Ratio. 'pwt' is Pairwise Win Time. 'ewtp' is Expected Win Time Against Trial Population. 'ewtpr' is Expected Win Time Against Trial Population With Redistribution. 'rewtp' is Time Restricted Expected Win Time Against Trial Population. 'rewtpr'is Time Restricted Expected Win Time Against Trial Population With Redistribution. 'rpwt' is Time Restricted Pairwise Win Time.

Value

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 vector of length 'm' with the components of the treatment effect, a vector of length 'm' with the variance of the components. A warning message will be printed for combinations of type and model/resample that are not recommended.

Examples

# ------------------------------
# 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)