---
title: "Vignette 3: create a forest plot for an umbrella review with metaumbrella"
author: "Corentin J. Gosling^a^, Aleix Solanes^a^, Paolo Fusar-Poli & Joaquim Radua"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Vignette 3: create a forest plot for an umbrella review with metaumbrella}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{=html}
<style type="text/css">

*{
  font-family: "Gill Sans", sans-serif;
}

h1.title {
  font-weight: 700;
  font-size: 2.2rem;
  padding-top: 0rem;
  margin-top: 0rem;
  border-top: none;
}

#TOC {
  width: 100%;
}

h1{
  font-weight: 550;
  font-size: 1.9rem;
  border-top: 1px solid black;
  margin-top: 3rem;
  padding-top: 2rem;
}
p{
  line-height: 1.4rem;
}
</style>
```

```{r, echo = FALSE, warning = FALSE, results = 'hide'}
library(metaumbrella)
library(DT)
```

# Introduction

As in any statistical analysis, data visualization is an important step to interpret the results. To do so, the metaumbrella package proposes to display the results of your umbrella review using forest plots adapted to umbrella reviews. Contrary to forest plots used in standard meta-analyses (in which the effect sizes of individual studies are plotted), the forest plots proposed in the metaumbrella package display the pooled effect sizes of the meta-analyses. <br>

More precisely, the graphical presentation of the results generated by the `forest` function includes - by default (i) the name of the factors assessed in the umbrella review (referred to as the `factor` column), (ii) a graphical representation of the pooled effect size of each factor using a forest plot, (iii) the numeric values of the pooled effect size and 95% confidence interval (referred to as the `value` column). Numerous options are proposed to customize this basic figure (iv) various information such as the sample size or the heterogeneity.<br>

In the examples provided below, we present how to display a simple forest plot (Example 1), how to display a more complex forest plot in which some columns are added at the left of the plot (Example 2) and how to group the factors under a specific header, plus modifying the general layout (Example 3).

# Example 1: simple forest plot

<p>
This example uses the dataset named `df.OR` distributed along with the metaumbrella package. In this example, we plot the results of the calculations of the umbrella review while no stratification of evidence has been performed. 
</p>

```{r, eval=FALSE}
# perform the calculations
umb <- umbrella(df.OR, verbose = FALSE)

# plot the results
forest(umb)
```

```{r, echo=FALSE, warning=FALSE, fig.width = 8, fig.height = 6}
umb <- metaumbrella:::.quiet(umbrella(df.OR))
metaumbrella:::.quiet(forest(umb))
```

The effect sizes are displayed as `eG`, the default in this function. Since all factors have used `OR`, we can convert the effect sizes in `eOR` using the measure argument. Moreover, because all effect sizes are `OR` and not `eOR`, we indicate it in the plot (we can do this using the `rightlab` argument to modify the title of the right column and using the `xlab` argument to modify the title of the x-axis). <br> 
In the meantime, we also add a title to the plot using the `smlab` argument. 

```{r, eval=FALSE}
forest(umb,
       measure = "OR", # display eOR instead of eG,
       rightlab = "OR + 95% CI",
       xlab = "Odds Ratio",
       smlab = "Umbrella review of \nrisk factors for NDD" # title of the plot
       ) 
```


```{r, echo=FALSE, warning=FALSE, fig.width = 8, fig.height = 7}
metaumbrella:::.quiet(forest(umb,
       measure = "OR", # display eOR instead of eG,
       rightlab = "OR + 95% CI",
       xlab = "Odds Ratio",
      smlab = "Umbrella review of \nrisk factors for NDD" # title of the plot
      )) 
```

As you can see in the code for the title, we have added "backslash" n after the word 'for'. This forces a line break.<br>

The size of the dots reflects the precision of the pooled effect sizes. The narrower the 95% CI, the larger the size of the dot. If you would like to fix the size of the dot, you can set the argument `weight.study` to "same". <br>

```{r, eval=FALSE}
forest(umb,
       measure = "OR", # display eOR instead of eG,
       rightlab = "OR + 95% CI",
       xlab = "Odds Ratio",
       weight.study = "same",
       smlab = "Umbrella review of \nrisk factors for NDD" # title of the plot
       ) 

```

```{r, echo=FALSE, warning=FALSE, fig.width = 8, fig.height = 7}
metaumbrella:::.quiet(forest(umb,
       measure = "OR", # display eOR instead of eG,
       rightlab = "OR + 95% CI",
       xlab = "Odds Ratio",
       weight.study = "same",
       smlab = "Umbrella review of \nrisk factors for NDD" # title of the plot
       ) )
```

<br>
<br>

# Example 2: modified forest plot (modification of column positions)

This example uses two datasets named `df.SMD` and `df.HR` distributed along with the metaumbrella package. For the example, we stratify the evidence for all factors included in these two datasets according to some Personalized criteria.

```{r, eval=FALSE}
# perform the calculations
umb <- union.umbrella(umbrella(df.SMD), umbrella(df.HR))

# stratify the evidence
strat.prso <- add.evidence(umb, criteria= "Personalized",
                           class_I = c(n_studies = 10, total_n = 3000, egger_p = .10, esb_p = .05),
                           class_II = c(n_studies = 10, total_n = 2000, egger_p = .10),
                           class_III = c(n_studies = 10, total_n = 1000, egger_p = .10),
                           class_IV = c(n_studies = 10, total_n = 500, egger_p = .10))

# plot the results
forest(strat.prso) 
```


```{r, echo = FALSE, warning = FALSE, fig.width = 8, fig.height = 6}
umb <- metaumbrella:::.quiet(union.umbrella(umbrella(df.SMD), umbrella(df.HR)))
strat.prso <- metaumbrella:::.quiet(add.evidence(umb, criteria = "Personalized",
                           class_I = c(n_studies = 10, total_n = 3000, egger_p = .10, esb_p = .05),
                           class_II = c(n_studies = 10, total_n = 2000, egger_p = .10),
                           class_III = c(n_studies = 10, total_n = 1000, egger_p = .10),
                           class_IV = c(n_studies = 10, total_n = 500, egger_p = .10)))
metaumbrella:::.quiet(forest(strat.prso))
```

As you can see, the results are ordered according to the class reached. The meta-analyses using `HR` effect size measures have been automatically converted to eG. 

In some situations, you may be interested in adding/modifying the position of a column. In this example, we add a column describing the tau² values, and we move the column storing the effect size values and 95% CI on the left.

```{r, eval=FALSE}
forest(strat.prso,
       leftcols = c("Factor", "Class", "n_studies", "total_n", "tau2",
                    "effect.ci"),
       leftlabs = c("Factor", "Class", "n-studies", "n-sample", "tau²",
                    "eSMD + 95% CI"),
          rightcols = FALSE,
    )

```

```{r, echo = FALSE, warning = FALSE, fig.width = 8, fig.height = 6}
metaumbrella:::.quiet(forest(
  strat.prso,
  leftcols = c("Factor", "Class", "n_studies", "total_n", "tau2",
                    "effect.ci"),
 leftlabs = c("Factor", "Class", "n-studies", "n-sample", "tau²",
                    "eSMD + 95% CI"),
          rightcols = FALSE,
    ))
```

<br>
<br>
<br>

# Example 3: modified forest plot (layout and subgroups)

This example uses several fictitious datasets distributed along with the metaumbrella package, namely `df.SMD`, `df.OR`, `df.RR`, `df.IRR` and `df.OR.multi`. 

```{r, eval=FALSE}
# perform the calculations
umb <- union.umbrella(union.umbrella(
        union.umbrella(union.umbrella(
          umbrella(df.SMD), umbrella(df.OR)),
          umbrella(df.RR)), umbrella(df.IRR)), 
        umbrella(df.OR.multi, mult.level = TRUE))

strat.prso <- add.evidence(umb, criteria = "Ioannidis")

forest(strat.prso) 
```


```{r, echo=FALSE, warning=FALSE, fig.width = 8, fig.height = 8}
umb <- metaumbrella:::.quiet(union.umbrella(union.umbrella(
        union.umbrella(
          union.umbrella(umbrella(df.SMD), umbrella(df.OR)),
          umbrella(df.RR)), umbrella(df.IRR)), umbrella(df.OR.multi, mult.level = TRUE)))

strat.prso <- metaumbrella:::.quiet(add.evidence(umb, criteria = "Ioannidis"))

metaumbrella:::.quiet(forest(strat.prso))
```


First, to change the general appearance of the plot, you can use the 'layout' argument which can takes 3 values : "meta" (the default), "JAMA" and "RevMan5". Let's use the "RevMan5" option for this example:
```{r, eval=FALSE}
forest(strat.prso,
       layout = "RevMan5")
```

```{r, echo = FALSE, warning = FALSE, fig.width = 8, fig.height = 6}
metaumbrella:::.quiet(forest(strat.prso,
       layout = "RevMan5"))
```


Second, we will present the factors grouped under specific headers. For this example, we will group them according to the classes.
```{r, eval=FALSE}
forest(strat.prso,
       layout = "RevMan5",
       subgroup = "Class",
       subgroup.name = "Class")
```

```{r, echo = FALSE, warning = FALSE, fig.width = 8, fig.height = 6}
metaumbrella:::.quiet(forest(strat.prso,
       layout = "RevMan5",
       subgroup = "Class",
       subgroup.name = "Class"))
```