---
title: "Introduction to WRestimates"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to WRestimates}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(WRestimates)
```

# Introduction to the win-ratio

The win-ratio is a statistical methodology for comparing two groups when considering multiple endpoints.
The win-ratio is calculated by the number of wins divided by the number of losses of a group.
For instance, in a clinical trial with a treatment arm and a control arm, one would calculate the win-ratio of the treatment arm as the number of times treatment "won" over control divided by the number of times treatment "lost" to control.
For example, if the win-ratio was 1.5 this would indicate that the treatment group had 50% more wins than the control group.
A "win" or a "loss" is determined in pairs of patients for instance, patient T vs. patient C. In this example there will be two outcomes of interest, 1. Death and 2. Metastasis; where death is the first priority and metastasis is the second.
Patient T is in the treatment group, they did not die during the study but they did develop metastasis.
Patient C is in the control group, they died during the study and also developed metastasis prior to death.
Patient T will "win" over patient C ("loss") as they did not die during the study and death is the 1st priority outcome.
If metastasis was the first priority and death second; patient T and patient C would tie on metastasis and the second priority death would have to be consider. As patient C died and patient T did not, patient T would "win" here also.

The win-ratio is a particularly useful method for clinical trials as it allows for the determination of the holistic effect of a treatment while considering the hierarchy of all endpoints of interest at once.

# Sample size calculation
An important aspect of a clinical trial design is the sample size determination. It is necessary to calculate the required sample size to ensure the clinical trial has sufficient statistical power.

The `WRestimates` package contains the function `wr.ss()` which allows for the calculation of a sample size. For example, in a study of hormone therapy vs. placebo treatment for prostate cancer, the study designers deem a win-ratio of 1.25 to be clinically significant (25% more wins for the hormone therapy over the placebo), patients will be allocated in 1:1 and the expected number of tied pairs is 10%.

```{r}
wr.ss(WR.true = 1.25, k = 0.5, p.tie = 0.1)
```
As the power and level of significance (alpha) and beta (1 - power) were not specified they are assumed to be the default; defined as follows:

* alpha = 0.025; equivalent to a 5% level of significance in a two-sided test
* beta = 0.1; equivalent to a power of 90%

The required sample size is calculated to be `r ceiling(wr.ss(WR.true = 1.25, k = 0.5, p.tie = 0.1)$N)`.

# Power calculation
In some circumstances a sample size may be restricted. This may be due to economic or ethical considerations or simply due to the population of interest being rare.

In these circumstances, rather than calculating a sample size,
the power of the study is determined based on a set sample size.

The `WRestimates` package contains the function `wr.power()` which allows for the calculation of power. For example, in a study of hormone therapy vs. placebo treatment for prostate cancer, the study designers deem a win-ratio of 1.25 to be clinically significant (25% more wins for the hormone therapy over the placebo), there will be a sample size of 1000 patients who will be allocated in 1:1 and the expected number of tied pairs is 10%.
```{r}
wr.power(N = 1000, WR.true = 1.25, k = 0.5, p.tie = 0.1)
```
As the level of significance (alpha) was not specified it is assumed to be the default; defined as follows:

* alpha = 0.025; equivalent to a 5% level of significance in a two-sided test

The power is calculated to be `r round(wr.power(N = 1000, WR.true = 1.25, k = 0.5, p.tie = 0.1)$power, 3)`.

# Confidence Interval calculation
Confidence intervals are important because they allow us to:

* Assess how precise our estimates are.
* Determine the clinical significance of our results.

The `WRestimates` package contains the function `wr.ci()` which allows for the calculation of the confidence interval (CI) from summary statistics. For example, in a study of hormone therapy vs. placebo treatment for prostate cancer, the win-ratio is calculated to be of 1.22 (22% more wins for the hormone therapy over the placebo), the sample size is 1200 patients allocated in 1:1, and 4% of pairs are tied. The 95% confidence interval of this win ratio is:
```{r}
wr.ci(WR = 1.22, Z = 1.96, N = 1200, k = 0.5, p.tie = 0.04)
```
As the Z-score (Z) was not specified it is assumed to be the default; defined as follows:

* Z = 1.96; equivalent to a 5% level of significance in a two-sided test, or 95% CI.

The confidence interval is calculated to be (`r round(wr.ci(WR = 1.22, Z = 1.96, N = 1200, k = 0.5, p.tie = 0.04)$ci[1], 3)`, `r round(wr.ci(WR = 1.22, Z = 1.96, N = 1200, k = 0.5, p.tie = 0.04)$ci[2], 3)`).