Package 'forplo'

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.

---