---
title: "Tutorial on R package **mtrank**"
author: "Theodoros Evrenoglou, Guido Schwarzer"
output:
  rmarkdown::pdf_document:
   number_sections: false
  rmarkdown::html_vignette:
   toc: false
   number_sections: false
bibliography: references.bib 
vignette: >
  %\VignetteIndexEntry{mtrank: Tutorial on mtrank}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "##",
  message = TRUE,
  warning = FALSE
  )
options(knitr.kable.NA = ".")
```


This vignette serves as a tutorial for R package **mtrank**. This package allows R users to produce treatment hierarchies in network meta-analysis using the ranking method proposed by @Evre:Niko:Schw:prod:2024.

You could either install R package **mtrank** from CRAN

```{r, eval = FALSE}
install.packages("mtrank")
```

or the development version from GitHub

```{r, eval = FALSE}
remotes::install_github("TEvrenoglou/mtrank")
```

Next, we make the package available.

```{r}
library("mtrank")
```

We see that loading **mtrank** will automatically load the R packages **meta**, **metadat** and **netmeta**.

Next, we load the 'antidepressants' dataset which is part of R package **mtrank** and conduct a network meta-analysis. You can get information about this dataset using the command *help(antidepressants)*.

```{r}
data("antidepressants")
#
pw <- pairwise(studlab = studyid, treat = drug_name,
  n = ntotal, event = responders,
  data = antidepressants, sm = "OR")
#
net <- netmeta(pw, reference.group = "tra")
```


### Define treatment-choice criterion

In the next step, we set the treatment-choice criterion and get treatment preferences from NMA estimates using the function tcc(). More details about this function can be obtained using the command *help(tcc)*.

The treatment-choice criterion is determined by the smallest worthwhile difference (SWD), which represents the smallest relative effect between two treatments that can influence the selection of the preferable treatment. Users can set this value using argument 'swd' in tcc(), which then defines the range of equivalence (ROE) based on the swd and its reciprocal. For binary outcomes, the swd must be specified on its natural scale. The ROE constructed using the swd is always symmetrical, but for users who require a non-symmetrical ROE, the arguments 'swd.below.null' and 'swd.above.null' allow for explicit specification of preferred bounds. However, if argument 'swd' is specified, arguments 'swd.below.null' and 'swd.above.null' are ignored.

```{r}
ranks <- tcc(net, swd = 1.25, small.values = "undesirable")
```

We could print the preferences with the following command (result not shown).

```{r, eval = FALSE}
ranks$preferences
```

As argument 'swd = 1.25' the ROE is defined as [1 / swd, swd] = [0.8, 1.25]. The ROE is stored as the lower and upper bound.

```{r}
c(ranks$swd.below.null, ranks$swd.above.null)
```


Alternatively, we could define a ROE by specifying its lower and upper bound.

```{r, eval = FALSE}
ranks <- tcc(net, swd.below = 0.80, swd.above = 1.25,
  small.values = "undesirable")
```

Note, an asymmetric ROE could be defined in this way.


### Forest plot showing impact of treatment choice criterion

R function forest.tcc() can be used to create a forest plot. This function gets as first argument the object created from tcc() and as second the argument 'reference.group' which specifies the treatment for which the treatment choice criterion needs to be inspected. If users do not specify the argument 'treat' then forest plots are generated for every direct comparison in the network.

```{r, eval = FALSE}
forest(ranks, xlim = c(-1, 2),
  reference.group = "bupropion", baseline.reference = FALSE,
  label.left = "Favors other drug",
  label.right = "Favors bupropion",
  fill.equi = "lightblue", spacing = 1.5)
```

```{r, echo = FALSE, out.width = "70%"}
forest(ranks, xlim = c(-1, 2),
  reference.group = "bupropion", baseline.reference = FALSE,
  label.left = "Favors other drug",
  label.right = "Favors bupropion",
  fill.equi = "lightblue", spacing = 1.5,
  file = "forest1.pdf")
knitr::include_graphics("forest1.pdf")
```


### Probabilistic ranking model

The probabilistic ranking model can be fitted using mtrank() from R package **mtrank**. The ability estimates obtained from mtrank() can then be visualised in a forest plot.

```{r}
fit <- mtrank(ranks)
```

We can print the ability estimates and the probabilities of each treatment to rank first.

```{r}
fit
```


### Forest plot of log-ability estimates 

R function forest.mtrank() can be used to create a forest plot of ability estimates. By default, log-ability estimates are shown in the forest plot.

```{r, eval = FALSE}
forest(fit)
```

```{r, echo = FALSE, out.width = "70%"}
forest(fit, file = "forest2.pdf")
knitr::include_graphics("forest2.pdf")
```

Alternatively, we could plot the abilities using argument 'backtransf' (figure not shown).

```{r, eval = FALSE}
forest(fit, backtransf = TRUE)
```


### Sensitivity analysis

Given the subjectivity of the choice of the SWD value which determines the TCC, it is natural one to investigate the robustness of the treatment hierarchy under different SWD values. The R package **mtrank** allows for such a sensitivity analysis to be performed and presented in a linegraph through the function linegraph(). This function takes the following arguments:

- x: an mtrank object,
- swd: a numeric vector of SWD values to be used for the sensitivity analysis,
- swd.ref: a numeric SWD value to be used as the reference for sorting treatments in the final graph. This value must be included in swd,
- small.values: a character string specifying whether small treatment effects indicate a beneficial ("desirable") or harmful ("undesirable") effect,
- type: the metric to be used for plotting the results of the sensitivity analysis. Two options are available: the default is "probability", which plots results in terms of normalized abilities; the alternative is "ability", which plots results in terms of ability estimates. Both options can be abbreviated,
- k: a numeric value indicating the number of treatments to be plotted. By default, all available treatments are shown. For large networks, it is advisable to limit the number of treatments to improve readability. If specified, the first k treatments based on the hierarchy at swd.ref will be plotted.
- backtransf: a logical value indicating whether to display log-ability estimates (FALSE, default) or back-transformed ability estimates on the natural scale (TRUE). This argument is ignored if type = "probability".
- linewidth: a numeric value specifying the width of the lines (default: 1.1).
- point.size: a numeric value specifying the size of the points (default: 2).
- ...: additional arguments passed to mtrank().

For more details about this function please use *help(linegraph)*.

```{r}
# Perform a sensitivity analysis across different swd values assuming that 1.20 is the reference value
swd.vec <- seq(1.10, 1.50, by = 0.10)
swd.ref <- 1.20
# plot all the treatments in the network
linegraph(fit, swd = swd.vec, swd.ref = swd.ref)
# plot only the first six treatments in the order appearing at the 'swd.ref' value
linegraph(fit, swd = swd.vec, swd.ref = swd.ref, k = 6)
# plot in terms of ability estimates 
linegraph(fit, swd = swd.vec, swd.ref = swd.ref, type = "ability")


```


### Fitted probabilities

Finally, R package **mtrank** allows the calculation of pairwise preferences through the function fitted(). This function expects the following arguments:

- x: an mtrank object
- treat1: the first treatment considered in the treatment comparison,
- treat2: the second treatment considered in the treatment comparison,
- type: the probability of interest.

For more details about this function please use *help(fitted.mtrank)*.

```{r}
# Get probability fitted probabilities for comparison bupropion vs trazodone
fitted(fit, treat1 = "bupropion", treat2 = "trazodone",
  type = "all")
```

It is also possible to contrast one drug with several others (and to provide abbreviated but unambiguous drug names).

```{r}
# Get probability that bupropion is better than other drugs
fitted(fit, treat1 = "bupr",
  treat2 = c("fluo", "paro", "sert", "traz", "venl"), type = "all")
```


# References