Type: Package
Title: Flexible Forest Plots
Version: 0.2.5
Description: Simplifies the creation and customization of forest plots (alternatively called dot-and-whisker plots). Input classes accepted by 'forplo' are data.frame, matrix, lm, glm, and coxph. 'forplo' was written in base R and does not depend on other packages.
License: GPL-3
Encoding: UTF-8
Language: en-US
Depends: R (≥ 3.5.0)
VignetteBuilder: knitr, rmarkdown, lattice
RoxygenNote: 7.1.2
Suggests: knitr, rmarkdown, lattice, MASS, meta, survival, extrafont
NeedsCompilation: no
Packaged: 2023-02-16 00:56:24 UTC; arinetencate-hoek
Author: Vincent ten Cate, PhD [cre, aut]
Maintainer: "Vincent ten Cate, PhD" <vincent10kd@gmail.com>
Repository: CRAN
Date/Publication: 2023-02-16 01:10:02 UTC

forplo - flexible forest plots with R

Description

forplo is an R package meant to simplify the creation and customization of forest plots (alternatively called dot-and-whisker plots). Input classes accepted by forplo are data.frame, matrix, lm, glm, and coxph. forplo was written in base R and does not depend on other packages. For extensive examples and how to use all arguments for customization, please refer to the package vignette.

Usage

forplo(
  mat,
  em = "OR",
  row.labels = NULL,
  linreg = FALSE,
  prop = FALSE,
  pval = NULL,
  xlim = xlimits,
  fliprow = NULL,
  flipbelow1 = FALSE,
  flipsymbol = "*",
  ci.sep = "-",
  ci.lwd = 1.5,
  ci.edge = TRUE,
  font = "sans",
  groups = NULL,
  grouplabs = NULL,
  group.space = 1,
  group.italics = FALSE,
  indent.groups = NULL,
  left.align = FALSE,
  favorlabs = NULL,
  add.arrow.left = FALSE,
  add.arrow.right = FALSE,
  arrow.left.length = 3,
  arrow.right.length = 3,
  arrow.vadj = 0,
  sort = FALSE,
  char = 20,
  size = 1.5,
  col = 1,
  insig.col = "gray",
  scaledot.by = NULL,
  scaledot.factor = 0.75,
  diamond = NULL,
  diamond.col = col,
  diamond.line = TRUE,
  add.columns = NULL,
  add.colnames = NULL,
  column.spacing = 3,
  right.bar = FALSE,
  rightbar.ticks = 0,
  left.bar = TRUE,
  leftbar.ticks = 0,
  shade.every = NULL,
  shade.col = "red",
  shade.alpha = 0.05,
  fill.by = NULL,
  fill.colors = NULL,
  fill.labs = NULL,
  legend = FALSE,
  legend.vadj = 0,
  legend.hadj = 0,
  legend.spacing = 1,
  margin.left = NULL,
  margin.top = 0,
  margin.bottom = 2,
  margin.right = 10,
  horiz.bar = FALSE,
  title = NULL,
  save = FALSE,
  save.path = NULL,
  save.name = NULL,
  save.type = "png",
  save.width = 9,
  save.height = 4.5
)

Arguments

mat

An n*3 data.frame or matrix, or a regression model of class lm, glm or coxph.

em

Effect measure to be displayed (e.g. OR, RR, HR).

row.labels

Labels to display as variable names (character vector of length nrow(mat)).

linreg

Set to TRUE if the estimates are from a linear regression model.

prop

Set to TRUE if the estimates are proportions.

pval

A numeric or character vector of same length as nrow(mat), with p-values.

xlim

A numeric vector of length 2 indicating the limits of the x-axis.

fliprow

A numeric vector indicating which estimates should be inverted (only for ratios).

flipbelow1

Set to TRUE to invert all ratios below 1.

flipsymbol

A symbol to display besides inverted estimates. Asterisk by default.

ci.sep

The separator between confidence intervals. Dash by default.

ci.lwd

Line width for the confidence interval 'whiskers'.

ci.edge

Set to FALSE to remove the 90 degree edges at the end of the CI whiskers.

font

Controls the font family. 'Calibri' by default. Note: monospaced fonts work poorly.

groups

A numeric vector of length nrow(mat) indicating group membership of each element.

grouplabs

A character vector of equal length to the number of groups, with the labels of each group.

group.space

A single numeric value to indicate how much empty rows should be between grouped estimates.

group.italics

Set to TRUE to italicize the group labels.

indent.groups

A numeric vector indicating which groups to indent (works only when left.align==TRUE)

left.align

Set to TRUE to left align variable and group labels.

favorlabs

A character vector of length 2, providing labels for underneath the x-axis (e.g. c('favors control','favors intervention')).

add.arrow.left

Adds an arrow pointing left underneath the x-axis.

add.arrow.right

Adds an arrow pointing right underneath the x-axis.

arrow.left.length

Controls the length of the arrow pointing left.

arrow.right.length

Controls the length of the arrow pointing right.

arrow.vadj

Allows to adjust the vertical placement of the arrows.

sort

Set to TRUE to sort the rows by effect size (not compatible with groups or diamond).

char

Controls the character to display for the dots. Equivalent to pch in the base R plot function.

size

Controls the size of the dots. Equivalent to cex in the base R plot function.

col

Controls the color of the dots. Equivalent to col in the base R plot function.

insig.col

Controls the color of the CI whiskers when crossing the null line. Gray by default.

scaledot.by

Numeric vector of length nrow(mat) to indicate relative importance of each variable (e.g. sample size, weight).

scaledot.factor

Scaling factor (scalar) for scaledot.by, to adapt the size of all scaled dots at once.

diamond

Numeric vector indicating the rows that should be displayed as diamonds (e.g. for meta-analytic estimates).

diamond.col

Controls the color of the diamonds.

diamond.line

Shows a dotted vertical line through the last diamond. Set to FALSE to disable.

add.columns

A data.frame of nrow(mat) with additional columns to add to the right of the plot.

add.colnames

A character vector of length ncol(add.columns) with column labels for these columns.

column.spacing

A constant that controls the horizontal spacing between added columns.

right.bar

Set to TRUE to show a vertical bar directly to the left of the estimates.

rightbar.ticks

Controls the tick marks on the right axis.

left.bar

Set to FALSE to remove the horizontal bar on the left axis.

leftbar.ticks

Controls the tick marks on the left axis.

shade.every

Controls row shading option. A value of 1 colors every other row, a value of 2 per blocks of 2, etc. Non-integer values also allowed.

shade.col

Controls the default row shading color. Default is 'red'.

shade.alpha

Controls the transparency of the row shading color. Default is 0.05.

fill.by

Numeric vector of length nrow(mat) indicating color group membership of each element.

fill.colors

Character vector of length unique(fill.by), with colors for each color group.

fill.labs

Character vector of length fill.colors, specifying the legend labels.

legend

Set to TRUE to display a legend if fill.colors is not NULL.

legend.vadj

Controls the vertical placement of the legend.

legend.hadj

Controls the horizontal placement of the legend.

legend.spacing

Controls the spacing between legend items.

margin.left

Controls size of left margin.

margin.top

Controls size of top margin.

margin.bottom

Controls size of bottom margin.

margin.right

Controls size of right margin.

horiz.bar

Set to TRUE to display a horizontal bar below the plot.

title

Title to display above the plot. Equivalent to title in the base R plot function.

save

Set to TRUE to save the plot (also requires save.name and save.path) in 300 dpi resolution.

save.path

Indicates folder where the plot should be saved.

save.name

Name of the plot (should not include filetype extension).

save.type

Filetype of the saved plot. Default is .png, but also supports .wmf on Windows.

save.width

Width of the saved plot in inches. Default is 9.

save.height

Height of the saved plot in inches. Default is 4.5.

Value

The function plots in the user's plot window, but does not return anything.

Examples

#==== Create some regression models ==========
mod1 <- lm(Sepal.Length~Sepal.Width+Species+Petal.Width+Petal.Length,iris)

#==== Example forest plots====================
# default plot for linear regression model
forplo(mod1)

# customized plot for linear regression model
forplo(mod1,
       row.labels=c('Sepal width','Versicolor','Virginica','Petal width','Petal length'),
       groups=c(1,2,2,3,3),
       grouplabs=c('Sepal traits','Species','Petal traits'),
       shade.every=1,
       shade.col='gray',
       left.align=TRUE,
       xlim=c(-2,2),
       title='Linear regression with grouped estimates')

## More examples are given in the vignette.