---
title: "An overview on rankinma"
author: "Enoch Kang, Chiehfeng Chen Wen-Hsuan Hou, Jin-Hua Chen, Yu-Chieh Chuang, & Edwin Chan"
date: "April 01, 2024"
description: > 
  Rank in network meta-analysis.
output: 
  rmarkdown::html_vignette:
    toc: TRUE
    md_keep: TRUE
    html: TRUE
vignette: >
  %\VignetteIndexEntry{An_overview_on_rankinma}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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


```{r echo = FALSE, out.width = "10%"}
knitr::include_graphics("rankinma_logo.png")
```

[![CRAN](https://img.shields.io/badge/CRAN-v0.2.1-blue.svg?logo=r&logoColor=skyblue)](https://CRAN.R-project.org/package=rankinma)
[![Update date](https://img.shields.io/badge/Update%20date-2024.Apr.01-blue.svg?logo=r&logoColor=skyblue)](https://github.com/EnochKang/rankinma/blob/main/NEWS.md)


## Brief overview

Package *rankinma* supports users to easily obtain and visualize various metrics of treatment ranking from network meta-analysis no matter using frequentist or Bayesian approach. This package not only accepts manual-prepared data set of treatment ranking metrics from users, but also can help users to gather various treatment ranking metrics in network meta-analysis. Users can use functions in *rankinma* by calling the library with following syntax:

```{r, eval = FALSE}
library(rankinma)
```

```{r setup, echo = FALSE, warning = FALSE, message = FALSE}
library(rankinma)
library(netmeta)
```

## Feature

*rankinma* allows users to visualize various treatment ranking metrics in network meta-analysis based either common-effect model or random-effects model. The current version includes three common metrics of treatment ranking.  

- **Probabilities:** probabilities of every available treatment on each possible rank.
- **SUCRA:** the value of surface under the cumulative ranking curve using Bayesian approach.
- **P-score:** the value of SUCRA using frequentist approach.


Briefly, *rankinma* can be used for visualization of both detailed metrics of probabilities and global metrics (i.e. SUCRA and P-score). Besides, *rankinma* provides users multiple types of plots to illustrate aforementioned treatment ranking metrics, and current version consists of five types of plots with six sub-types.

- **Beading plot:** a novel graphics for displaying global metrics of treatment ranking (i.e. SUCRA, P-score, and P-best) based on numeric line plot.
- **Bar chart:** a classic graphics for most metrics of treatment ranking (i.e. probabilities, SUCRA, and P-score), and *rankinma* supports two sub-type of bar chart in terms of side-by-side bar chart and cumulative bar chart.
- **Line chart:** a classic graphics for most metrics of treatment ranking (i.e. probabilities, SUCRA, and P-score), and *rankinma* supports two sub-type of line chart in terms of simple line chart (a line on a chart) and composite line chart (multiple lines on a chart).
- **Heat plot:** a new graphics for showing global metrics of treatment ranking (i.e. SUCRA and P-score) for each outcome, and *rankinma* supports to gather all heat plots of outcomes with interests on a plot.
- **Spie chart:** a new graphics proposed in 2020 for displaying multiple global metrics of treatment ranking (i.e. SUCRA and P-score) from outcomes with interests by each treatment, and *rankinma* supports to place all spie charts on a plot.


## Flow and functions

Users can visualize treatment ranking after network meta-analysis in five steps, but have to check condition before using *rankinma*.

**Situation 1:** Users have data for network meta-analysis of **a single outcome** but do not get treatment ranking metrics yet.
  
**Situation 2:** Users have data for network meta-analysis of **various outcomes** but do not get treatment ranking metrics yet.  
\

#### For situation 1:

**Step 1.** Load data and do network meta-analysis.

**Step 2.** Get treatment ranking metrics from the network meta-analysis using function `GetMetrics()`.

**Step 3.** Setup data in *rankinma* format using function `SetMetrics()`.

**Step 4.** Visualization using function `PlotBeads()`, `PlotHeat()`, `PlotBar()`, or `PlotLine()`.


#### For situation 2:

**Step 1.** Load data and do network meta-analysis.

**Step 2.** Get treatment ranking metrics from the network meta-analysis using function `GetMetrics()`.

--- Repeat step 1 and 2 for each outcome, and keep output of them for the further steps. ---

**Step 3.** Combine treatment ranking metrics using function `rbind()` in R *base*.

**Step 4.** Setup data in *rankinma* format using function `SetMetrics()`.

**Step 5.** Visualization using function `PlotBeads()`, `PlotHeat()`, `PlotBar()`, or `PlotLine()`.


## Usage and examples

The following steps and syntax demonstrate how user can illustrate a summary of treatment ranking metrics on various outcomes from network meta-analysis.

Example 1 for illustrating line chart when users have data for network meta-analysis of a single outcome but do not get treatment ranking metrics yet.

**STEP 1.** Load data
```{r, eval = FALSE}
library(rankinma)
library(netmeta)
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
```

\

**STEP 2.** Get Probabilities
```{r, eval = FALSE}
dataMetrics <- GetMetrics(nmaOutput, 
                          outcome = "HbA1c.random", 
                          prefer = "small", 
                          metrics = "Probabilities", 
                          model = "random", 
                          simt = 1000)
```

\

**STEP 3.**  Set data for rankinma
```{r, eval = FALSE}
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics.name = "Probabilities")
```

\

**STEP 4.** Visualize the probabilities of treatments among possible ranks

If the users wish to visualize the information using line chart, the following syntax could be a reference.

```{r, eval = FALSE}
PlotLine(data = dataRankinma, 
         compo = TRUE)
```

```{r, eval = TRUE, echo = FALSE, warning = FALSE, results = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 1**. Composite line chart for probabilities of treatments on each rank.", fig.height = 5, fig.width = 7, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
dataMetrics <- GetMetrics(nmaOutput, 
                          outcome = "HbA1c.random", 
                          prefer = "small", 
                          metrics = "Probabilities", 
                          model = "random", 
                          simt = 1000)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics.name = "Probabilities")
PlotLine(data = dataRankinma, 
         compo = TRUE)
```

\

If the users wish to visualize the information using stacked bar chart, the following syntax could be a reference.

```{r, eval = FALSE}
PlotBar(data = dataRankinma, 
        accum = TRUE)
```

```{r, eval = TRUE, echo = FALSE, warning = FALSE, results = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 2**. Accumulative bar chart for probabilities of treatments on each rank.", fig.height = 5, fig.width = 7, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
dataMetrics <- GetMetrics(nmaOutput, 
                          outcome = "HbA1c.random", 
                          prefer = "small", 
                          metrics = "Probabilities", 
                          model = "random", 
                          simt = 1000)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics.name = "Probabilities")
PlotBar(data = dataRankinma, 
        accum = TRUE)
```

\

Example 2 for illustrating beading plot when users have data for network meta-analysis of multiple outcomes but do not get treatment ranking metrics yet.

**STEP 1.** Load data
```{r, eval = FALSE}
library(rankinma)
library(netmeta)
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
```

\

**STEP 2.** Get global metrics
Due to several rank metrics in network meta-analysis, users have to decide which global metric would be used in the analysis; accordingly users choose argument for parameter `metrics` in the function `GetMetrics()`. The following syntax is for users who would like to obtain the Surface Under the Cumulative Ranking Curve (SUCRA).

*Get SUCRA*
```{r, eval = FALSE}
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "SUCRA", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "SUCRA", 
                        model = "common", 
                        simt = 1000)
```

\

If users wish to obtain the P-score, they can utilize the following syntax.

*Get P-score* 
```{r, eval = FALSE}
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "common", 
                        simt = 1000)
```

\

If users wish to obtain the P-best, they can assign the argument `P-best` to the parameter `metrics` in the function `GetMetrics()`. The following syntax is for reference.

*Get P-best*
```{r, eval = FALSE}
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "P-best", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "P-best", 
                        model = "common", 
                        simt = 1000)
```

\

**STEP 3.** Combine metrics from multiple outcomes
```{r, eval = FALSE}
dataMetrics <- rbind(nmaRandom, nmaCommon)
```

\

**STEP 4.** Set data for rankinma
As mentioned above, users choose argument for parameter `metrics` in the function `GetMetrics()` according to which global metric would be used in analysis due to several rank metrics in network meta-analysis. The following syntax is for users who would like to use SUCRA.

\

*Set data based on SUCRA*
```{r, eval = FALSE}
dataRankinma <- (dataMetrics, 
                 tx = tx, 
                 outcome = outcome, 
                 metrics = SUCRA, 
                 metrics.name = "SUCRA")
```

\

*Set data based on P-score*
```{r, eval = FALSE}
dataRankinma <- (dataMetrics, 
                 tx = tx, 
                 outcome = outcome, 
                 metrics = P.score, 
                 metrics.name = "P-score")
```

\

*Set data based on P-best*
```{r, eval = FALSE}
dataRankinma <- (dataMetrics, 
                 tx = tx, 
                 outcome = outcome, 
                 metrics = P.best, 
                 metrics.name = "P-best")
```

\

**STEP 5.** Visualize global ranking metrics

*Illustrate beading plot based on SUCRA (without relative effect)*
```{r, eval = FALSE}
PlotBeads(data = dataRankinma)
```

```{r, eval = TRUE, echo = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 3A**. Beading plot for SUCRA on two outcomes", fig.height = 6, fig.width = 8, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "SUCRA", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "SUCRA", 
                        model = "common", 
                        simt = 1000)
dataMetrics <- rbind(nmaRandom, nmaCommon)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics = SUCRA, 
                           metrics.name = "SUCRA")
PlotBeads(data = dataRankinma)
```

\

*Illustrate beading plot sorted by P-score (with relative effects and equidistant by rank)*
```{r, eval = FALSE}
PlotBeads(data = dataRankinma, 
          scaleX = "Rank",
          txtValue = "Effects")
```

```{r, eval = TRUE, echo = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 3A**. Beading plot for SUCRA on two outcomes", fig.height = 6, fig.width = 8, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "common", 
                        simt = 1000)
dataMetrics <- rbind(nmaRandom, nmaCommon)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics = P.score, 
                           metrics.name = "P-score")
PlotBeads(data = dataRankinma, 
          scaleX = "Rank",
          txtValue = "Effects")
```

\

*Illustrate colorblind-friendly beading plot based on P-best*
```{r, eval = FALSE}
PlotBeads(data = dataRankinma,
          lgcBlind = TRUE)
```

```{r, eval = TRUE, echo = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 3C**. Colorblind friendly beading plot for P-score on two outcomes", fig.height = 6, fig.width = 8, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "P-best", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "P-best", 
                        model = "common", 
                        simt = 1000)
dataMetrics <- rbind(nmaRandom, nmaCommon)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics = P.best, 
                           metrics.name = "P-best")
PlotBeads(data = dataRankinma,
          lgcBlind = TRUE)
```

\

*Illustrate spie plot based on P-score*
```{r, eval = FALSE}
PlotSpie(data = dataRankinma)
```

```{r, eval = TRUE, echo = FALSE, message = FALSE, results = "hide", fig.cap = "**Figure 3B**. Spie plot for P-score on two outcomes", fig.height = 6, fig.width = 8, fig.align = "center", out.width = "90%"}
data(Senn2013)
nmaOutput <- netmeta(TE, 
                     seTE, 
                     treat1, 
                     treat2, 
                     studlab, 
                     data = Senn2013, 
                     sm = "SMD")
nmaRandom <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.random", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "random", 
                        simt = 1000)
nmaCommon <- GetMetrics(nmaOutput, 
                        outcome = "HbA1c.common", 
                        prefer = "small", 
                        metrics = "P-score", 
                        model = "common", 
                        simt = 1000)
dataMetrics <- rbind(nmaRandom, nmaCommon)
dataRankinma <- SetMetrics(dataMetrics, 
                           tx = tx, 
                           outcome = outcome, 
                           metrics = P.score, 
                           metrics.name = "P-score")
PlotSpie(data = dataRankinma)
```



## Reference

Salanti, G., Ades, A. E., & Ioannidis, J. P. (2011). Graphical methods and numerical summaries for presenting results from multiple-treatment meta-analysis: an overview and tutorial. **Journal of clinical epidemiology**, *64(2)*, 163-171.

Chaimani, A., Higgins, J. P., Mavridis, D., Spyridonos, P., & Salanti, G. (2013). Graphical tools for network meta-analysis in STATA. **PloS one**, *8(10)*, e76654.

Van Valkenhoef, G., Tervonen, T., Zwinkels, T., De Brock, B., & Hillege, H. (2013). ADDIS: a decision support system for evidence-based medicine. **Decision Support Systems**, *55(2)*, 459-475.

Rücker, G., & Schwarzer, G. (2015). Ranking treatments in frequentist network meta-analysis works without resampling methods. **BMC medical research methodology**, *15(1)*, 1-9.

Daly, C. H., Mbuagbaw, L., Thabane, L., Straus, S. E., & Hamid, J. S. (2020). Spie charts for quantifying treatment effectiveness and safety in multiple outcome network meta-analysis: a proof-of-concept study. **BMC Medical Research Methodology**, *20*, 1-13.

Balduzzi, S., Rücker, G., Nikolakopoulou, A., Papakonstantinou, T., Salanti, G., Efthimiou, O., & Schwarzer, G. (2023). netmeta: An R package for network meta-analysis using frequentist methods. **Journal of Statistical Software**, *106*, 1-40.
