---
title: "Description of the network"
author: Loukia M. Spineli
date: "Latest version: `r Sys.Date()`"
source: vignettes/network_description.Rmd
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
params:
  EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true")
vignette: >
  %\VignetteIndexEntry{Description of the network}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, include = FALSE}
library(rnmamod)
```

## Introduction

This vignette aims to illustrate the toolkits of the **rnmamod** package for the
creation of the network plot and summarisation of the corresponding outcome 
data. If missing participant outcome data (MOD) have been extracted for all 
trials of the dataset, the **rnmamod** package facilitates visualising the 
proportion of MOD across the network and within the dataset.

## Example on a binary outcome 

### Dataset preparation

We will use the systematic review of 
[Bottomley et al., (2011)](https://pubmed.ncbi.nlm.nih.gov/21142838/) that 
comprises 9 trials comparing six pharmacologic interventions with each other and
placebo for moderately severe scalp psoriasis. The analysed binary outcome is 
the investigator global assessment response at 4 weeks (`?nma.bottomley2011`).

```{r set-options, echo = FALSE, comment = NA}
orig <- options(width = 1000)
nma.bottomley2011
options(orig)
```

The dataset has the one-trial-per-row format containing arm-level data for each 
trial. This format is widely used for BUGS models. For a binary outcome, the 
dataset must have a minimum of three items: 

- item `t` that refers to the intervention identifier for the corresponding 
(intervention) arm;
- item `r` that refers to the number of observed events in the corresponding 
arm. 
- item `n` that refers to the number of randomised participants in the 
corresponding arm.

If there is at least one trial that reports the number of missing participants 
per arm, we also include the item `m` in the dataset. If a trial reports the 
*total* number of missing participants rather than the number of missing 
participants per arm, we indicate with `NA` in the item `m` the arms of the 
corresponding trial.\cr

In the example, the maximum number of interventions observed in a trial is four.
Therefore, each element comprises four columns (e.g., `t1`, `t2`, `t3`, `t4`) to
indicate the maximum number of arms in the dataset. Furthermore, all trials of 
the dataset reported the number of missing participants per arm; therefore, the 
element `m` appears in the dataset.

### The network plot

The function `netplot` (see ?netplot for help) creates the network plot using 
only two arguments: the `data` for the dataset (in one-trial-per-row format) and
`drug_names` for the names of each intervention in the dataset. 

```{r, results = "hide", fig.show = "hide"}
netplot(data = nma.bottomley2011, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"), show_multi = TRUE, edge_label_cex = 1)
```

```{r, echo = FALSE, results = "hide", fig.width = 5, fig.height = 5, fig.align = "center"}
netplot(data = nma.bottomley2011, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"), show_multi = TRUE, edge_label_cex = 1)
```

The intervention names in `drug_names` must be sorted in the ascending order of 
their identifier. Hence, `1` in the element `t` refers to `BDP`, 
(betamethasone dipropionate) `2` to `BMV` (betamethasone valerate), `3` to `CPL`
(calcipotriol) and so on. See Details in `?nma.bottomley20119` for the names 
of the interventions.\cr

Each node refers to an intervention and each edge refers to a pairwise 
comparison. The size of a node and the thickness of an edge are weighted by the 
number of trials that investigated the corresponding intervention and pairwise 
comparison, respectively.  

### Network characteristics

`netplot` also produces a table with the characteristics of the network, such as
the number of interventions, number of possible comparisons, number of direct 
comparisons (i.e., comparisons of interventions informed by at least one trial),
and so on:

```{r, echo = FALSE, fig.show = "hide"}
describe_network(data = nma.bottomley2011,
                 drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"),
                 measure = "OR",
                 save_xls = FALSE)$network_description
```

### Distribution of the outcome

Furthermore, `netplot` returns a table that summarises the number of trials, 
number of randomised participants and the proportion of completers (participants
who completed the trial) **per intervention**. In the case of a binary outcome, 
the table additionally illustrates the distribution of the outcome as proportion
across the corresponding trials: 

```{r, echo = FALSE, fig.show = "hide"}
describe_network(data = nma.bottomley2011,
                 drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"),
                 measure = "OR",
                 save_xls = FALSE)$table_interventions
```

An identical table is returned for the **observed comparisons** in the network:

```{r, echo = FALSE, fig.show = "hide"}
describe_network(data = nma.bottomley2011,
                 drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"),
                 measure = "OR",
                 save_xls = FALSE)$table_comparisons
```

The users can export all tables in xlsx file at the working directory 
of their project by adding the argument `save_xls = TRUE` in the `describe_network` 
function.

### Distribution of missing participants across the network

When missing participants have been reported for *each arm of every* trial, we 
use the `heatmap_missing_network` function to illustrate the distribution of the
proportion of missing participants **per intervention** (main diagonal) and 
**observed comparison** (lower off-diagonal) in the network (see Details in 
`?heatmap_missing_network`). 

```{r, results = "hide", fig.show = "hide"}
heatmap_missing_network(data = nma.bottomley2011, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"))
```

```{r, echo = FALSE, results = "hide", fig.width = 7, fig.height = 7, fig.align = "center"}
heatmap_missing_network(data = nma.bottomley2011, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"))
```

The <span style="color:#009E73">**green**</span> colour implies a median 
proportion of missing participant up to 5\%, and hence, a 
<span style="color:#009E73">**low risk**</span> associated with the missing 
participants. The <span style="color:#D55E00">**red**</span> colour implies a 
median proportion of missing participant over 20\%, and hence, a 
<span style="color:#D55E00">**high risk**</span> associated with the missing 
participants; otherwise, <span style="color:orange">**orange**</span> indicates 
a <span style="color:orange">**moderate risk**</span>.\cr

In the example, most of the interventions and observed comparisons were 
associated with a *low* risk due the participant losses.

### Distribution of missing participants across the trials

Use the `heatmap_missing_dataset` function To illustrate the proportion of 
missing participants in each arm of every trial in the dataset :

```{r, results = "hide", fig.show = "hide"}
heatmap_missing_dataset(data = nma.bottomley2011, trial_names = nma.bottomley2011$study, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"))
```

```{r, echo = FALSE, results = "hide", fig.width = 7.5, fig.height = 7, fig.align = "center"}
heatmap_missing_dataset(data = nma.bottomley2011, trial_names = nma.bottomley2011$study, drug_names = c("BDP", "BMV", "CPL", "CPL+polytar", "capasal", "TCF gel", "placebo"))
```

## References

Bottomley JM, Taylor RS, Ryttov J. The effectiveness of two-compound formulation
calcipotriol and betamethasone dipropionate gel in the treatment of moderately 
severe scalp psoriasis: a systematic review of direct and indirect evidence. 
*Curr Med Res Opin* 2011;**27**(1):251--268. 
[doi: 10.1185/03007995.2010.541022](https://pubmed.ncbi.nlm.nih.gov/21142838/)

