---
title: "Make a PRISMA flow chart"
author: "Jack O. Wasey"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette
bibliography:
 - all.bib
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Make a PRISMA flow chart}
  %\VignetteEncoding{UTF-8}
---
  
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
suppressPackageStartupMessages(library(DiagrammeR))
```

```{r pkgdesc, results = "asis", echo = FALSE}
cat(packageDescription("PRISMAstatement")$Description)
```

# Background

The [Preferred Reporting Items for Systematic Reviews and Meta-Analyses](http://prisma-statement.org) (PRISMA) Statement  [@moher_preferred_2009] defines an evidence-based, minimal set of items for reporting in systematic reviews and meta-analyses. PRISMA should be used for the reporting of studies evaluating randomized clinical trials (RCTs), and for reporting of systematic reviews of other types of research.

Meta-analysis is a critical tool in evidence-based medicine, forming the basis of international recommendations and guiding local medical practice. Unfortunately, a large amount of published medical research is likely to be false [@ioannidis_why_2005]. This increases the importance of good meta-analysis of potentially flawed studies in order to reduce bias. An effort has been made to raise the standard of work accepted in major medical journals, for both primary research and systematic reviews. For example, for randomized controlled trials, we have the widely enforced CONSORT statement [@Schulz_CONSORT2010Statement_2010]. PRISMA is the analogue of CONSORT for meta-analysis and systematic reviews.

The importance of these efforts to raise standards is so great that the PRISMA Statement has been published in multiple medical journals [e.g., @Moher_Preferredreportingitems_2010; @Liberati_PRISMAstatementreporting_2009], and it is now a requirement for authors to follow its guidelines when submitting meta-analyses and systematic reviews to major journals.

In addition to increasing the standard of research in general, the movement towards reproducible research continues, with a drive to publish more data and to automate and publish the statistical analysis. The "Living Systematic Review" brings the reproducible concept to systematic reviews and extends it by allowing prompt updates as new evidence is published [@Elliott_Livingsystematicreview_2017]. With these goals and trends in mind, the `PRISMAstatement` package for the R statistical software [@R] enables construction of a correct PRISMA flow diagram which can be generated as part of a reproducible workflow in R.

The R packages such as `ggplot2` [@ggplot2], `rmarkdown` [@rmarkdown], `rticles` [@rticles] give researchers the tools to produce manuscripts incorporating their analysis, figures and text, entirely within the R environment. However, plotting flow charts is not straightforward, especially not those that confirm to the specific PRISMA statement requirements. Most researchers are likely to resort to producing their PRISMA flow diagram in another application then import the resulting figure. This is a possible source of errors, and a barrier to reproducible research: with `PRISMAstatement` it is now possible to use a reproducible workflow up-to-date PRISMA flow diagram of publication quality.

# Generate a PRISMA flow chart

```{r prisma}
#install.packages("PRISMAstatement")
library(PRISMAstatement)

prisma(found = 750,
       found_other = 123,
       no_dupes = 776, 
       screened = 776, 
       screen_exclusions = 13, 
       full_text = 763,
       full_text_exclusions = 17, 
       qualitative = 746, 
       quantitative = 319,
       width = 800, height = 800)
```

# Tweaks

Ideally, you will stick closely to the PRISMA statement, but small deviations are common. `PRISMAstatement` gives the option of adding a box which simply calculates the number of duplicates removed.

```{r prismadupesbox}
prisma(found = 750,
       found_other = 123,
       no_dupes = 776, 
       screened = 776, 
       screen_exclusions = 13, 
       full_text = 763,
       full_text_exclusions = 17, 
       qualitative = 746, 
       quantitative = 319,
       extra_dupes_box = TRUE)
```

You can also change the labels, but you will have to insert the number for any label you change. E.g.,
```{r labels}
prisma(1000, 20, 270, 270, 10, 260, 20, 240, 107,
       labels = list(found = "FOUND", found_other = "OTHER"))
```

# Safety

There are some hard constraints on the relationships between the numbers in each box, which are enforced by the `prisma` function. There are a couple of warnings given when it seems that numerically valid, but unlikely numbers are given: studies shouldn't just disappear between each step. Arguably this is a hard stop, but there might be circumstances when additional exclusions are made which could be annotated in a figure caption.

```{r errors and warnings}
tryCatch(
  prisma(1, 2, 3, 4, 5, 6, 7, 8, 9),
  error = function(e) e$message)
prisma(1000, 20, 270, 270, 10, 260, 19, 240, 107, 
       width = 100, height = 100)
prisma(1000, 20, 270, 270, 269, 260, 20, 240, 107, 
       width = 100, height = 100)
```

# Font size

The underlying `DiagrammeR` uses `htmlwidgets` to render the flow chart, and this can occasionally cause text boxes to overflow. Varying the font size using the `PRISMAstatement::prisma` argument `font_size` may help prepare a PRISMA flow chart for publication.

```{r font_size}
prisma(1000, 20, 270, 270, 10, 260, 20, 240, 107, font_size = 6)
prisma(1000, 20, 270, 270, 10, 260, 20, 240, 107, font_size = 60)
```

# Take care modifying the width, height and DPI

For publication quality graphics, a certain number of DPI is often requested. This is difficult to achieve with the chain of tools that PRISMAstatement uses (DiagrammeR, htmlwidgets), and also affected by the output container which may be a PDF vignette, file, browser window, etc..

```{r prismadpi1, fig.cap="just set width and height"}
prisma(found = 750,
       found_other = 123,
       no_dupes = 776, 
       screened = 776, 
       screen_exclusions = 13, 
       full_text = 763,
       full_text_exclusions = 17, 
       qualitative = 746, 
       quantitative = 319,
       width = 200, height = 200)
```

```{r prismadpi2, fig.cap="same width and height but DPI increased to 300"}
prisma(found = 750,
       found_other = 123,
       no_dupes = 776, 
       screened = 776, 
       screen_exclusions = 13, 
       full_text = 763,
       full_text_exclusions = 17, 
       qualitative = 746, 
       quantitative = 319,
       width = 200, height = 200,
       dpi = 300)
```

```{r prismadpi3, fig.cap="same width and height but DPI decreased to 36"}
prisma(found = 750,
       found_other = 123,
       no_dupes = 776, 
       screened = 776, 
       screen_exclusions = 13, 
       full_text = 763,
       full_text_exclusions = 17, 
       qualitative = 746, 
       quantitative = 319,
       width = 200, height = 200,
       dpi = 36)
```

My recommendation is to leave DPI at the default (72), and change the canvas size to achieve the correct number of pixels to fit the width of your target document. Tweaking the DPI may help (or cause) clipping.

## Publications

It may be useful for publications to have a separate high-quality PDF of the PRISMA flow chart. An experimental internal function can do something like this:
```{r prismapdf, echo = TRUE, eval = FALSE}
prsm <- prisma(found = 750,
               found_other = 123,
               no_dupes = 776,
               screened = 776,
               screen_exclusions = 13,
               full_text = 763,
               full_text_exclusions = 17,
               qualitative = 746,
               quantitative = 319,
               width = 200, height = 200,
               dpi = 36)
tmp_pdf <- tempfile()
PRISMAstatement:::prisma_pdf(prsm, tmp_pdf)
knitr::include_graphics(path = tmp_pdf)
unlink(tmp_pdf)
```
# References
