R: forplo - flexible forest plots with R

forplo {forplo}

R Documentation

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.

[Package forplo version 0.2.5 Index]