% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wintime.R
\name{wintime}
\alias{wintime}
\title{Run a win time calculation}
\usage{
wintime(
  type,
  Time,
  Delta,
  trt,
  cov = NULL,
  model = NULL,
  resample = NULL,
  resample_num = 0,
  time_restriction = NA,
  seed = NA,
  nimp = 1
)
}
\arguments{
\item{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'.}

\item{Time}{A \verb{m x n} matrix of event times (days), where \code{m} is the number of events in the hierarchy, and \code{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.}

\item{Delta}{A \verb{m x n} matrix of event indicators, where \code{m} is the number of events in the hierarchy, and \code{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.}

\item{trt}{A numeric vector containing treatment arm indicators (1 for treatment, 0 for control).}

\item{cov}{Optional. A \verb{n x p} matrix of covariate values, where \code{n} is the total number of trial participants and \code{p} is the number of covariates.
Rows should represent participants and columns should represent covariate values.}

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

\item{resample}{Optional. String value. The resampling method run after the observed data calculation. Options include 'boot' and 'perm'.  Default depends on \code{type}.}

\item{resample_num}{Optional. The number of desired resamples. Default is 0.}

\item{time_restriction}{Required only for \code{type} = 'rmt','rewtp','rewtpr', and 'rpwt'. The cutoff time (days).}

\item{seed}{Optional. Seed used for random number generation in resampling.}

\item{nimp}{Required only for \code{type} = 'ewtpr','rewtpr'. The number of random imputations for Redistribution-to-the-right.}
}
\value{
A list containing: the observed treatment effect, a vector of length \code{resample_num} containing resampled treatment effects, a message
indicating the method ran and the type of resampling done, the variance, the p-value (one-sided for treatment benefit), 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, the maximum time used in the comparisons (for EWT, RMT, EWTP, REWTP, EWTPR, REWTPR).
A warning message will be printed for combinations of \code{type} and \code{model}/\code{resample}
that are not recommended.
}
\description{
This function runs one of the win time methods on observed and resampled data.
}
\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.

The maximum time used in comparisons for EWT, RMT, EWTP, REWTP, EWTPR, and REWTPR are defined below.

First define separately for each arm the maximum valid time for estimating the multi-state distribution
(max_valid_time0 and max_valid_time1) from either a Markov or KM model as follows.
max_valid_time0 is the smallest time for the control arm when the estimated multi-state distribution has a
positive probability of a state but there is nobody still at-risk in that state (If this never occurs
then max_valid_time0 is defined to be the largest event time of the control arm (max_time0)).
max_valid_time1 is the smallest time for the treatment arm when the estimated multi-state distribution has a
positive probability of a state but there is nobody still at-risk in that state (If this never occurs
then max_valid_time1 is defined to be the largest event time of the treatment arm(max_time1)).
Also define the maximum valid time for the combined arms for estimating the multi-state distribution
(max_valid_time2) from either a Markov or KM model as follows.
max_valid_time2 is the smallest time for the combined arms when the estimated multi-state distribution has a
positive probability of a state but there is nobody still at-risk in that state (If this never occurs
then max_valid_time2 is defined to be the largest event time of the combined arms (max_time2)).

EWT: There are two cases:
(1) the arm with the smaller maximum valid time has an estimated multi-state distribution that is degenerate
in the absorbing (highest) state at that time.
(2) the arm with the smaller maximum valid time has an estimated multi-state distribution that is not degenerate
in the absorbing (highest) state at that time.
For case (1) the maximum time used in comparison is the max(max_valid_time0,max_valid_time1).
For case (2) the maximum time used in comparison is the min(max_valid_time0,max_valid_time1).

RMT: the maximum time used in comparison is min(the maximum time used in comparison for EWT, time_restriction).

EWTP: There are two cases:
(1) the combined arms have an estimated multi-state distribution that is degenerate in the absorbing (highest) state
at max_valid_time2.
(2) the combined arms have an estimated multi-state distribution that is not degenerate in the absorbing (highest) state
at max_valid_time2.
For case (1) the maximum time used in comparison is the max(max_valid_time2,max_time2).
For case (2) the maximum time used in comparison is the min(max_valid_time2,max_time2).

REWTP: the maximum time used in comparison is min(the maximum time used in comparison for EWTP, time_restriction).

EWTPR: There are 8 cases based on which of the three (control arm, treatment arm, combined arms) estimated multi-state
distributions are degenerate in the absorbing (highest) state at the maximum valid time.
The maximum time used in comparison is the minimum of the max_valid_times over the arms (control, treatment, combined)
that do not have degenerate estimated multi-state distibutions in the absorbing (highest) state at the maximum valid time
(If all have a degenerate estimated multi-state distibutions in the absorbing (highest) state at the maximum valid time
the maximum time used in comparison is defined as the maximum of the three max_valid_times).

REWTPR: the maximum time used in comparison is min(the maximum time used in comparison for EWTPR, time_restriction).
}
\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)

}
