Package 'WR' reference manual

Title:	Win Ratio Analysis of Composite Time-to-Event Outcomes
Description:	Implements various win ratio methodologies for composite endpoints of death and non-fatal events, including the (stratified) proportional win-fractions (PW) regression models (Mao and Wang, 2020 <doi:10.1111/biom.13382>), (stratified) two-sample tests with possibly recurrent nonfatal event, and sample size calculation for standard win ratio test (Mao et al., 2021 <doi:10.1111/biom.13501>).
Authors:	Lu Mao and Tuo Wang
Maintainer:	Lu Mao <[email protected]>
License:	GPL (>= 2)
Version:	1.0
Built:	2024-11-04 05:36:08 UTC
Source:	https://github.com/cran/WR

Compute the baseline parameters needed for sample size calculation for standard win ratio test

Description

Compute the baseline parameters $\zeta_0^2$ and $\boldsymbol\delta_0$ needed for sample size calculation for standard win ratio test (see WRSS). The calculation is based on a Gumbel–Hougaard copula model for survival time $D^{(a)}$ and nonfatal event time $T^{(a)}$ for group $a$ (1: treatment; 0: control):

${P}(D^{(a)}>s, T^{(a)}>t) =\exp\left(-\left[\left\{\exp(a\xi_1)\lambda_Ds\right\}^\kappa+ \left\{\exp(a\xi_2)\lambda_Ht\right\}^\kappa\right]^{1/\kappa}\right),$

where $\xi_1$ and $\xi_2$ are the component-wise log-hazard ratios to be used as effect size in WRSS. We also assume that patients are recruited uniformly over the period $[0, \tau_b]$ and followed until time $\tau$ ( $\tau\geq\tau_b$ ), with an exponential loss-to-follow-up hazard $\lambda_L$ .

Usage

base(lambda_D, lambda_H, kappa, tau_b, tau, lambda_L, N = 1000, seed = 12345)
base(lambda_D, lambda_H, kappa, tau_b, tau, lambda_L, N = 1000, seed = 12345)

Arguments

`lambda_D`	Baseline hazard $\lambda_D$ for death.
`lambda_H`	Baseline hazard $\lambda_H$ for nonfatal event.
`kappa`	Gumbel–Hougaard copula correlation parameter $\kappa$ .
`tau_b`	Length of the initial (uniform) accrual period $\tau_b$ .
`tau`	Total length of follow-up $\tau$ .
`lambda_L`	Exponential hazard rate $\lambda_L$ for random loss to follow-up.
`N`	Simulated sample size for monte-carlo integration.
`seed`	Seed for monte-carlo simulation.

Value

A list containing real number zeta2 for $\zeta_0^2$ and bivariate vector delta for $\boldsymbol\delta_0$ .

References

Mao, L., Kim, K. and Miao, X. (2021). Sample size formula for general win ratio analysis. Biometrics, https://doi.org/10.1111/biom.13501.

Examples

# see the example for WRSS
# see the example for WRSS

A subset of the German Breast Cancer study data

Description

These are a subset of the German Breast Cancer study data.

Usage

gbc
gbc

Format

A data frame with 985 rows and 12 variables:

id: subject IDs
time: event times (months)
status: event status; 0:censoring, 1:death, 2:cancer recurrence
hormone: treatment indicator: 1=Hormone therapy; 2=standard therapy
age: age at diagnosis (years)
menopause: menopausal Status; 1=No; 2=Yes
size: tumor size
grade: tumor grade, 1-3
nodes: number of nodes involved
prog_recp: number of progesterone receptors
estrg_recp: number of estrogen receptors

References

Sauerbrei, W., Royston, P., Bojar, H., Schmoor, C. and Schumacher, M. (1999). Modelling the effects of standard prognostic factors in node-positive breast cancer. German Breast Cancer Study Group (GBSG). British Journal of Cancer, 79, 1752–1760.

Hosmer, D.W. and Lemeshow, S. and May, S. (2008) Applied Survival Analysis: Regression Modeling of Time to Event Data: Second Edition, John Wiley and Sons Inc., New York, NY

Estimate baseline parameters in the Gumbel–Hougaard model for sample size calculation using pilot data

Description

Estimate baseline parameters in the Gumbel–Hougaard model described in base for sample size calculation using pilot study data.

Usage

gumbel.est(id, time, status)
gumbel.est(id, time, status)

Arguments

`id`	A vector of unique patient identifiers.
`time`	A numeric vector of event times.
`status`	A vector of event type variable; 2 = nonfatal event, 1 = death, and 0 = censoring.

Value

A list containing lambda_D for $\lambda_D$ , lambda_H for $\lambda_H$ , and kappa for $\kappa$ in the Gumbel–Hougaard model.

References

Mao, L., Kim, K. and Miao, X. (2021). Sample size formula for general win ratio analysis. Biometrics, https://doi.org/10.1111/biom.13501.

Examples

# see the example for WRSS
# see the example for WRSS

A subset of the HF-ACTION study data on high-risk non-ischemic heart failure patients

Description

These are data on a subgroup of 426 high-risk non-ischemic patients in the HF-ACTION study.

Usage

hfaction_cpx9
hfaction_cpx9

Format

A data frame with 1,448 rows and 5 variables:

patid: patient ID
time: event times (months)
status: event status; 0:censoring, 1:death, 2:hospitalization
trt_ab: treatment indicator: 1: exercise training, 0: usual care
age60: 1: 60 years or older, 0: less than 60 years old

References

O'Connor, C. M., Whellan, D. J., Lee, K. L., Keteyian, S. J., Cooper, L. S., Ellis, S. J., Leifer, E. S., Kraus, W. E., Kitzman, D. W., Blumenthal, J. A. et al. (2009). Efficacy and safety of exercise training in patients with chronic heart failure: HF-ACTION randomized controlled trial. Journal of the American Medical Association, 301, 1439–1450.

A subset of the HF-ACTION study data on non-ischemic heart failure patients with full covariate measurement.

Description

These are a subset of the data on 451 non-ischemic patients in the HF-ACTION study will complete baseline covariates.

Usage

non_ischemic
non_ischemic

Format

A data frame with 751 rows and 16 variables:

ID: subject IDs
time: event times (days)
status: event status; 0:censoring, 1:death, 2:hospitalization
trt_ab: treatment indicator: 1=exercise training; 0=usual care
age: patient age in years
sex: 1=female; 2=male
Black.vs.White: 1=black; 0=otherwise
Other.vs.White: 1=race other than black or white; 0=otherwise
bmi: body mass index
bipllvef: (biplane) left-ventricular ejection fraction
hyperten: indicator for history of hypertension
COPD: indicator for history of COPD
diabetes: indicator for history of diabetes
acei: indicator for current use of ACE inhibitors
betab: indicator for current use of beta blockers
smokecurr: indicator for current smoker

References

Plot the standardized score processes

Description

Plot the standardized score processes.

Usage

## S3 method for class 'pwreg.score'
plot(
  x,
  k,
  xlab = "Time",
  ylab = "Standardized score",
  lty = 1,
  frame.plot = TRUE,
  add = FALSE,
  ylim = c(-3, 3),
  xlim = NULL,
  lwd = 1,
  ...
)
## S3 method for class 'pwreg.score'
plot(
  x,
  k,
  xlab = "Time",
  ylab = "Standardized score",
  lty = 1,
  frame.plot = TRUE,
  add = FALSE,
  ylim = c(-3, 3),
  xlim = NULL,
  lwd = 1,
  ...
)

Arguments

`x`	an object of class `pwreg.score`.
`k`	A positive integer indicating the order of covariate to be plotted. For example, `k=3` requests the standardized score process for the third covariate in the covariate matrix `Z`.
`xlab`	a title for the x axis.
`ylab`	a title for the y axis.
`lty`	the line type. Default is 1.
`frame.plot`	a logical variable indicating if a frame should be drawn in the 1D case.
`add`	a logical variable indicating whether add to current plot?
`ylim`	a vector indicating the range of y-axis. Default is (-3,3).
`xlim`	a vector indicating the range of x-axis. Default is NULL.
`lwd`	the line width, a positive number. Default is 1.
`...`	further arguments passed to or from other methods

Value

A plot of the standardized score process for object pwreg.score.

Examples

# see the example for score.proc
# see the example for score.proc

Print the results of the proportional win-fractions regression model

Description

Print the results of the proportional win-fractions regression model.

Usage

## S3 method for class 'pwreg'
print(x, ...)
## S3 method for class 'pwreg'
print(x, ...)

Arguments

`x`	an object of class `pwreg`.
`...`	further arguments passed to or from other methods

Value

Print the results of pwreg object

Examples

# see the example for pwreg
# see the example for pwreg

Print information on the content of the pwreg.score object

Description

Print information on the content of the pwreg.score object

Usage

## S3 method for class 'pwreg.score'
print(x, ...)
## S3 method for class 'pwreg.score'
print(x, ...)

Arguments

`x`	A object of class pwreg.score.
`...`	further arguments passed to or from other methods.

Value

Print the results of pwreg.score object.

Examples

# see the example for score.proc
# see the example for score.proc

Print the results of the two-sample recurrent-event win ratio analysis

Description

Print the results of the two-sample recurrent-event win ratio analysis.

Usage

## S3 method for class 'WRrec'
print(x, ...)
## S3 method for class 'WRrec'
print(x, ...)

Arguments

`x`	an object of class `WRrec`.
`...`	further arguments passed to or from other methods.

Value

Print the results of WRrec object.

Examples

# see the example for WRrec
# see the example for WRrec

Fit a standard proportional win-fractions (PW) regression model

Description

Fit a standard proportional win-fractions (PW) regression model.

Usage

pwreg(
  ID,
  time,
  status,
  Z,
  rho = 0,
  strata = NULL,
  fixedL = TRUE,
  eps = 1e-04,
  maxiter = 50
)
pwreg(
  ID,
  time,
  status,
  Z,
  rho = 0,
  strata = NULL,
  fixedL = TRUE,
  eps = 1e-04,
  maxiter = 50
)

Arguments

`ID`	a vector of unique subject-level identifiers.
`time`	a vector of event times.
`status`	a vector of event type labels. 0: censoring, 1:death and 2: non-fatal event.
`Z`	a matrix or a vector of covariates.
`rho`	a non-negative number as the power of the survival function used in the weight. Default (`rho=0`) is recommended. If there is a 'strata' argument, then 'rho' is ignored.
`strata`	a vector of stratifying variable if a stratified model is desired.
`fixedL`	logical variable indicating which variance estimator to be used. If 'TRUE', the type I variance estimator (for a small number strata) is used; otherwise the type II variance estimator (for a large number strata) is used.
`eps`	precision for the convergence of Newton-Raphson algorithm.
`maxiter`	maximum number of iterations allow for the Newton-Raphson algorithm.

Value

An object of class pwreg with the following components. beta:a vector of estimated regression coefficients. Var:estimated covariance matrix for beta. conv: boolean variable indicating whether the algorithm converged within the maximum number of iterations.

References

Mao, L. and Wang, T. (2020). A class of proportional win-fractions regression models for composite outcomes. Biometrics, 10.1111/biom.13382

Wang, T. and Mao, L. (2021+). Stratified Proportional Win-fractions Regression Analysis.

Examples

library(WR)
head(non_ischemic)
id_unique <-unique(non_ischemic$ID)

# Randomly sample 200 subjects from non_ischemic data
set.seed(2019)
id_sample <- sample(id_unique, 200)
non_ischemic_reduce <- non_ischemic[non_ischemic$ID %in% id_sample, ]

# Use the reduced non_ischemic data for analysis
nr <- nrow(non_ischemic_reduce)
p <- ncol(non_ischemic_reduce)-3
ID <- non_ischemic_reduce[,"ID"]
time <- non_ischemic_reduce[,"time"]
status <- non_ischemic_reduce[,"status"]
Z <- as.matrix(non_ischemic_reduce[,4:(3+p)],nr,p)
## unstratified analysis
pwreg.obj <- pwreg(time=time,status=status,Z=Z,ID=ID)
print(pwreg.obj)
## Not run: 
## stratified PW by sex
sex<-Z[,3]
## take out sex from the covariate matrix
Z1<-Z[,-3]
pwreg.obj1 <- pwreg(time=time,status=status,Z=Z1,ID=ID,strata=sex)
print(pwreg.obj1)

## End(Not run)
library(WR)
head(non_ischemic)
id_unique <-unique(non_ischemic$ID)

# Randomly sample 200 subjects from non_ischemic data
set.seed(2019)
id_sample <- sample(id_unique, 200)
non_ischemic_reduce <- non_ischemic[non_ischemic$ID %in% id_sample, ]

# Use the reduced non_ischemic data for analysis
nr <- nrow(non_ischemic_reduce)
p <- ncol(non_ischemic_reduce)-3
ID <- non_ischemic_reduce[,"ID"]
time <- non_ischemic_reduce[,"time"]
status <- non_ischemic_reduce[,"status"]
Z <- as.matrix(non_ischemic_reduce[,4:(3+p)],nr,p)
## unstratified analysis
pwreg.obj <- pwreg(time=time,status=status,Z=Z,ID=ID)
print(pwreg.obj)
## Not run: 
## stratified PW by sex
sex<-Z[,3]
## take out sex from the covariate matrix
Z1<-Z[,-3]
pwreg.obj1 <- pwreg(time=time,status=status,Z=Z1,ID=ID,strata=sex)
print(pwreg.obj1)

## End(Not run)

Computes the standardized score processes

Description

Computes the standarized score processes for the covariates.

Usage

score.proc(obj, t = NULL)
score.proc(obj, t = NULL)

Arguments

`obj`	an object of class pwreg.
`t`	a vector containing times. If not specified, the function will use all unique event times from the data.

Value

An object of class pwreg.score consisting of t: a vector of times; and score: a matrix whose rows are the standardized score processes as a function of t.

References

Mao, L. and Wang, T. (2020). A class of proportional win-fractions regression models for composite outcomes. Biometrics, 10.1111/biom.13382

Examples

library(WR)
head(non_ischemic)

# Randomly sample 200 subjects from non_ischemic data
id_unique <-unique(non_ischemic$ID)
set.seed(2019)
id_sample <- sample(id_unique, 200)
non_ischemic_reduce <- non_ischemic[non_ischemic$ID %in% id_sample, ]

# Use the reduced non_ischemic data for analysis
nr <- nrow(non_ischemic_reduce)
p <- ncol(non_ischemic_reduce)-3
ID <- non_ischemic_reduce[,"ID"]
time <- non_ischemic_reduce[,"time"]
status <- non_ischemic_reduce[,"status"]
Z <- as.matrix(non_ischemic_reduce[,4:(3+p)],nr,p)
pwreg.obj <- pwreg(time=time,status=status,Z=Z,ID=ID)
score.obj <- score.proc(pwreg.obj)
#plot the standardized score process for the first covariate
plot(score.obj, k = 1)
library(WR)
head(non_ischemic)

# Randomly sample 200 subjects from non_ischemic data
id_unique <-unique(non_ischemic$ID)
set.seed(2019)
id_sample <- sample(id_unique, 200)
non_ischemic_reduce <- non_ischemic[non_ischemic$ID %in% id_sample, ]

# Use the reduced non_ischemic data for analysis
nr <- nrow(non_ischemic_reduce)
p <- ncol(non_ischemic_reduce)-3
ID <- non_ischemic_reduce[,"ID"]
time <- non_ischemic_reduce[,"time"]
status <- non_ischemic_reduce[,"status"]
Z <- as.matrix(non_ischemic_reduce[,4:(3+p)],nr,p)
pwreg.obj <- pwreg(time=time,status=status,Z=Z,ID=ID)
score.obj <- score.proc(pwreg.obj)
#plot the standardized score process for the first covariate
plot(score.obj, k = 1)

Generalized win ratio tests

Description

Perform stratified two-sample test of possibly recurrent nonfatal event and death using the recommended last-event assisted win ratio (LWR), and/or naive win ratio (NWR) and first-event assisted win ratio (FWR) (Mao et al., 2022). The LWR and FWR reduce to the standard win ratio of Pocock et al. (2012).

Usage

WRrec(ID, time, status, trt, strata = NULL, naive = FALSE)
WRrec(ID, time, status, trt, strata = NULL, naive = FALSE)

Arguments

`ID`	A vector of unique patient identifiers.
`time`	A numeric vector of event times.
`status`	A vector of event type variable; 2 = recurrent event, 1 = death, and 0 = censoring.
`trt`	A vector of binary treatment indicators.
`strata`	A vector of categorical variable for strata; Default is NULL, which leads to unstratified analysis.
`naive`	If TRUE, results for NWR and FWR will be provided in addition to LWR; Default is FALSE, which gives LWR only.

Value

An object of class WRrec, which contains the following elements.

`theta`	A bivariate vector of win/loss fractions by LWR.
`log.WR`, `se`	Log-win ratio estimate and its standard error by LWR.
`pval`	$p$ -value by the LWR test.
`theta.naive`	A bivariate vector of win/loss fractions by NWR.
`log.WR.naive`, `se.naive`	Log-win ratio estimate and its standard error by NWR.
`theta.FI`	A bivariate vector of win/loss fractions by FWR.
`log.WR.FI`, `se.FI`	Log-win ratio estimate and its standard error by FWR.
`...`

References

Mao, L., Kim, K. and Li, Y. (2022). On recurrent-event win ratio. Statistical Methods in Medical Research, under review.

Pocock, S., Ariti, C., Collier, T., and Wang, D. (2012). The win ratio: a new approach to the analysis of composite endpoints in clinical trials based on clinical priorities. European Heart Journal, 33, 176–182.

Examples

## load the HF-ACTION trial data
library(WR)
head(hfaction_cpx9)
dat<-hfaction_cpx9
## Comparing exercise training to usual care by LWR, FWR, and NWR
obj<-WRrec(ID=dat$patid,time=dat$time,status=dat$status,
          trt=dat$trt_ab,strata=dat$age60,naive=TRUE)
## print the results
obj
## load the HF-ACTION trial data
library(WR)
head(hfaction_cpx9)
dat<-hfaction_cpx9
## Comparing exercise training to usual care by LWR, FWR, and NWR
obj<-WRrec(ID=dat$patid,time=dat$time,status=dat$status,
          trt=dat$trt_ab,strata=dat$age60,naive=TRUE)
## print the results
obj

Compute the sample size for standard win ratio test

Description

Compute the sample size for standard win ratio test.

Usage

WRSS(xi, bparam, q = 0.5, alpha = 0.05, side = 2, power = 0.8)
WRSS(xi, bparam, q = 0.5, alpha = 0.05, side = 2, power = 0.8)

Arguments

`xi`	A bivariate vector of hypothesized component-wise (treatment-to-control) log-hazard ratios under the Gumbel–Hougaard copula model described in `base`.
`bparam`	A list containing baseline parameters `zeta2` for $\zeta_0^2$ and `delta` for $\boldsymbol\delta_0$ ; Can directly use the output of base.
`q`	Proportion of patients assigned to treatment.
`alpha`	Type I error rate.
`side`	2-sided or 1-sided test.
`power`	Target power.

Value

A list containing n, the computed sample size.

References

Mao, L., Kim, K. and Miao, X. (2021). Sample size formula for general win ratio analysis. Biometrics, https://doi.org/10.1111/biom.13501.

Examples

# The following is not run in package checking to save time.
## Not run: 
## load the package and pilot dataset
library(WR)
head(hfaction_cpx9)
dat<-hfaction_cpx9
## subset to control group
pilot<-dat[dat$trt_ab==0,]

## get the data ready for gumbel.est()
id<-pilot$patid
## convert time from month to year
time<-pilot$time/12
status<-pilot$status
## compute the baseline parameters for the Gumbel--Hougaard
## copula for death and hospitalization
gum<-gumbel.est(id, time, status)

## get the baseline parameters
lambda_D<-gum$lambda_D
lambda_H<-gum$lambda_H
kappa<-gum$kappa
## set up design parameters and use base()
## to calculate bparam for WRSS()
# max follow-up 4 years
tau<-4
# 3 years of initial accrual
tau_b<-3
# loss to follow-up rate
lambda_L=0.05
# compute the baseline parameters
bparam<-base(lambda_D,lambda_H,kappa,tau_b,tau,lambda_L)
bparam

## sample size with power=0.8 under hazard ratios
## 0.9 and 0.8 for death and hospitalization, respectively.
WRSS(xi=log(c(0.9,0.8)),bparam=bparam,q=0.5,alpha=0.05,
    power=0.8)$n
## sample size under the same set-up but with power 0.9
WRSS(xi=log(c(0.9,0.8)),bparam=bparam,q=0.5,alpha=0.05,
    power=0.9)$n

## End(Not run)
# The following is not run in package checking to save time.
## Not run: 
## load the package and pilot dataset
library(WR)
head(hfaction_cpx9)
dat<-hfaction_cpx9
## subset to control group
pilot<-dat[dat$trt_ab==0,]

## get the data ready for gumbel.est()
id<-pilot$patid
## convert time from month to year
time<-pilot$time/12
status<-pilot$status
## compute the baseline parameters for the Gumbel--Hougaard
## copula for death and hospitalization
gum<-gumbel.est(id, time, status)

## get the baseline parameters
lambda_D<-gum$lambda_D
lambda_H<-gum$lambda_H
kappa<-gum$kappa
## set up design parameters and use base()
## to calculate bparam for WRSS()
# max follow-up 4 years
tau<-4
# 3 years of initial accrual
tau_b<-3
# loss to follow-up rate
lambda_L=0.05
# compute the baseline parameters
bparam<-base(lambda_D,lambda_H,kappa,tau_b,tau,lambda_L)
bparam

## sample size with power=0.8 under hazard ratios
## 0.9 and 0.8 for death and hospitalization, respectively.
WRSS(xi=log(c(0.9,0.8)),bparam=bparam,q=0.5,alpha=0.05,
    power=0.8)$n
## sample size under the same set-up but with power 0.9
WRSS(xi=log(c(0.9,0.8)),bparam=bparam,q=0.5,alpha=0.05,
    power=0.9)$n

## End(Not run)

Package 'WR'

Help Index

Compute the baseline parameters needed for sample size calculation for standard win ratio test

Description

Usage

Arguments

Value

References

See Also

Examples

A subset of the German Breast Cancer study data

Description

Usage

Format

References

Estimate baseline parameters in the Gumbel–Hougaard model for sample size calculation using pilot data

Description

Usage

Arguments

Value

References

See Also

Examples

A subset of the HF-ACTION study data on high-risk non-ischemic heart failure patients

Description

Usage

Format

References

A subset of the HF-ACTION study data on non-ischemic heart failure patients with full covariate measurement.

Description

Usage

Format

References

Plot the standardized score processes

Description

Usage

Arguments

Value

See Also

Examples

Print the results of the proportional win-fractions regression model

Description

Usage

Arguments

Value

See Also

Examples

Print information on the content of the pwreg.score object

Description

Usage

Arguments

Value

See Also

Examples

Print the results of the two-sample recurrent-event win ratio analysis

Description

Usage

Arguments

Value

See Also

Examples

Fit a standard proportional win-fractions (PW) regression model

Description

Usage

Arguments

Value

References

See Also

Examples

Computes the standardized score processes

Description

Usage

Arguments

Value

References

See Also

Examples

Generalized win ratio tests

Description

Usage