README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
```

# `forplot` 

A package to generate forest plots.

## Installation

`forplot` can be installed via the R universe:

```{r uni-installation, eval = FALSE}
install.packages('forplot', repos = c('https://ctu-bern.r-universe.dev', 'https://cloud.r-project.org'))
```

or from github:

```{r gh-installation, eval = FALSE}
# install.packages("remotes")
remotes::install_github("CTU-Bern/forplot")
```


## Usage
`forplot` and its main function `fplot` needs a data frame with specific column names. 

- *vlabel*: a *chr* column with the variable labels.
- *nx*: any number of *chr* or *num* columns numbered sequentially (i.e. *n1*, *n2*, *n3*, ...). Could contain the number of observations and/or summary per group.
- *beta*, *beta_lci*, *beta_uci*: three *num* columns with point estimates and confidence interval to be plotted as forest.
- *beta_format*: optional *chr* column with formatted text to be printed along forest, generated from betas if not given.
- *px*: any number of *chr* or *num* columns numbered sequentially (i.e. *p1*, *p2*, *p3*, ...). Could contain p-values.

The order of the columns is kept for the plot.

The package includes an example dataset with 10 variables:

```{r}
# load package
library(forplot)

# demonstration data
data(forplotdata)

forplotdata
```

The *nx* columns include the number of observations and descriptives (mean (sd)) for each group, *beta* is a mean difference, *p1* the p-value.

The minimal plot only includes a label and the forest and needs columns *vlabel*, *beta*, *beta_lci*, *beta_uci*.

```{r, fig.height=3.5, fig.width=5}
fplot(dat=forplotdata[,c("vlabel","beta","beta_lci","beta_uci")])
```

Adding *nx* and *px* columns:
```{r, fig.height=3.5, fig.width=8}
fplot(dat=forplotdata)
```

Set more sensible widths and heights:

- lwidths has to be the same length as the number of columns for the input 
	data plus two for the left and right margin
- lheight is usually of length three, for header, body and footer	

```{r, fig.height=3.5, fig.width=8}
lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,0.5,0.05)

lheights<-c(0.14,1,0.08)

fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights)
```

A header can be given using a character vector the same 
	length as the number of columns of the input data:

```{r, fig.height=3.5, fig.width=8}
header<-c("","Group1\nN","Group0\nmean (sd)","Group2\nN","Group2\nmean (sd)",
	"Mean difference\n95% CI","","P-value")

fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights,header=header)
```

The header can also be placed at any x/y position using a list 
	with one element per header line:

```{r, fig.height=3.5, fig.width=8}
header<-list(
  list(y=0.7,text=c("Group1","Group2","Mean difference (95% CI)","P-value"),x=c(0.10,0.32,0.7,0.98)),
  list(y=0.3,text=c("N","mean (sd)","N","mean (sd)"),x=c(0.07,0.18,0.28,0.38)))

fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights)
```

Further formatting options for the forest plot include:
  
  - *xtitle*: a label below the x-axis
  - *ref*: adds a vertical reference line
  - *xlim*: limits for the x-axis


```{r, fig.height=3.5, fig.width=8}
xtitle<-list(x=0.86,y=0.2,textl="Group 1 better  ",textr="  Group 2 better")

fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights,
	xtitle=xtitle,ref=list(x=0),xlim=c(-1,0.5))
```

Note that arrows are shown if the limits of the confidence intervals are not included within *xlim*.

There are further options for the reference line and we can shift the x-axis
  if the gap at the bottom is too large:
	
```{r, fig.height=3.5, fig.width=8}
xtitle<-list(x=0.86,y=0.6,textl="Group 1 better  ",textr="  Group 2 better")

fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights,
	ref=list(x=0,col=2,extend=2),
	xtitle=xtitle,xlim=c(-1,0.5),shift_xaxis=0.3,xlab_line=-0.8)

```

The points of the forest plots can also be formatted:

```{r, fig.height=3.5, fig.width=8}
set.seed(1345)
ps<-list(pch=16,cex=rnorm(10,2,0.2),col=1)

fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights,
	ref=list(x=0,col=2,extend=2),
	xtitle=xtitle,xlim=c(-1,0.5),shift_xaxis=0.3,xlab_line=-0.8,
	ps=ps)

```

Lines at the top and bottom can be added:

```{r, fig.height=3.5, fig.width=8}
fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights,
  ref=list(x=0,col=2,extend=2),
	xtitle=xtitle,xlim=c(-1,0.5),shift_xaxis=0.3,xlab_line=-0.8,
	headline=2,bottomline=1)
```

If effect measures are on the log-scale (e.g. for odds ratios), option *lscale* can be used to indicate that the text should contain the exponentiated values. Axis ticks and labels have to be adapted by hand.

```{r, fig.height=3.5, fig.width=8}
xlab_text<-c(0.3,0.5,0.8,1.0,1.5)
xlab<-log(xlab_text)
xlim<-log(c(min(xlab_text),max(xlab_text)))

fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights,
  ref=list(x=0,col=2,extend=2),
  lscale=TRUE,
	xtitle=xtitle,shift_xaxis=0.3,xlab_line=-0.8,
  xlim=xlim,xlab=xlab, xlab_text=xlab_text,
	headline=2,bottomline=1)
```

## Under development

A feature under development is adding a second forest plot (e.g. to show a risk difference and ratio)
  by setting *beta2 = TRUE*.
That needs columns *beta2*, *beta_lci2* and *beta_uci2* in the dataset (just copied over in the example below).
Options *xlab2*, *xlab_text2*, *xlim2* and *xtitle2* are available to format the second plot.

```{r, fig.height=3.5, fig.width=8}

forplotdata2<-forplotdata
forplotdata2$beta2<-forplotdata2$beta
forplotdata2$beta_lci2<-forplotdata2$beta_lci
forplotdata2$beta_uci2<-forplotdata2$beta_uci
forplotdata2<-forplotdata2[,colnames(forplotdata2) != "p1"]
forplotdata2$p1<-forplotdata$p1
  
lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,1.2,1.2,0.5,0.05)
lheights<-c(0.14,1,0.08)

fplot(dat=forplotdata2, beta2 = TRUE,
      lwidths=lwidths,lheights=lheights,
      xlim=c(-1,0.5),xlim2=c(-1,0.5),
      headline=2,bottomline=1)

```