Create a Forest Plot

Generates a simple forest plot (defined here as a plot of multiple estimates and their associated error bars).

plot_forest(
  x,
  lower = NULL,
  upper = NULL,
  point_type = 19,
  point_color = "black",
  point_background = "white",
  text_size = 1,
  line_width = 2,
  line_color = "black",
  margin = NULL,
  labels_y = NULL,
  labels_x = NULL,
  labels_estimates = NULL,
  labels_estimates_pos = 4,
  labels_estimates_limit = NULL,
  labels_position = -1.25,
  title_x = NULL,
  xlim = NULL,
  vert_grid = 0,
  vert_color = "black",
  vert_type = 1,
  horiz_grid = FALSE,
  horiz_color = "grey80",
  new = FALSE,
  w = 5,
  h = 5
)

Arguments

x

Either a vector of estimates or a data.frame/matrix with three columns consisting of the estimates, the lower limits the for error bars, and the upper limits for the error bars).

lower

A vector matching in length to values with the lower limits for the error bars.

upper

A vector matching in length to values with the upper limits for the error bars.

point_type

An integer vector specifying the type of point to draw (see graphics::points).

point_color

A character vector specifying the color(s) for the points.

point_background

A character vector specifying the color(s) for the point backgrounds.

text_size

A numeric vector of three elements specifying the size of the points to draw, the size of the x and y-axis labels, and the size of the x-axis title, respectively. If less than three elements are given, elements are recycled to produce the necessary length.

line_width

A numeric vector of three elements, the line widths for the error bars, the horizontal grid lines, and the vertical grid lines, respectively.

line_color

A character vector specifying the color(s) for the error bars.

margin

A numeric vector specifying the margin sizes (in inches) for the bottom, left, top, and right-hand sides of the figure.

labels_y

A character vector, the labels for the y-axis.

labels_x

A numeric vector giving the x-axis labels. If NULL the function attempts to automatically create the labels.

labels_estimates

A character vector, the labels to add next to each estimate within the plot.

labels_estimates_pos

An integer value indicating the side to place labels for estimates, where 1 = bottom, 2 = left, 3 = top, and 4 = right.

labels_estimates_limit

A numeric value specifying the highest or lowest value an estimate label can be placed when placing to the left or right, respectively.

labels_position

A numeric vector of three elements, the position at which to draw the y-axis labels, the x-axis labels, and the x-axis title, respectively.

title_x

A character string, the x-axis title.

xlim

A numeric vector with the lower and upper limits for the x-axis plotting boundary. If NULL the function computes it using base::range.

vert_grid

A numeric vector giving the x-axis positions for vertical grid lines. If NULL no grid lines are drawn.

vert_color

A character vector specifying the color(s) for the vertical grid lines.

horiz_grid

Logical; if TRUE horizontal grid lines are added to separate the different estimates visually.

horiz_color

A character vector specifying the color for the horizontal grid lines.

new

Logical; if TRUE a new plotting window is generated.

w

An integer value, the width of a new plotting window.

h

An integer value, the height of a new plotting window.

Value

A forest plot.

Examples

# Example data set
data("ChickWeight")
dtf <- ChickWeight[ ChickWeight$Time == 21, ]
# Compute uncertainty intervals around means
x <- stats_by_group( dtf, 'weight', 'Diet', c( 'N', 'M', 'SE', 'UI' ) )

# Basic forest plot
plot_forest(
  x[, c( 'M', 'UI_LB', 'UI_UB') ], labels_y = 'Diet ' %p% 1:4,
  new = FALSE
)



# Nicely formatted forest plot

# T-test against overall mean
x$P_value <- pt(
  abs( x$M - mean(x$M) ) / x$SE, x$N - 1, lower.tail = FALSE
)*2
signifcant <- x$P_value < .05
# Summary of results
results <-
  round( x$M ) %p% ' [' %p% round( x$UI_LB ) %p% ', ' %p%
  round( x$UI_UB ) %p% ']; p = ' %p%
  format( round( x$P_value, 3 ), nsmall = 3 )

plot_forest(
  x[, c( 'M', 'UI_LB', 'UI_UB') ],
  xlim = c( 140, 340 ), labels_x = seq( 140, 340, 40 ),
  labels_y = 'Diet ' %p% 1:4, labels_estimates = results,
  labels_estimates_limit = 230,
  new = FALSE, horiz_grid = TRUE, vert_grid = mean( x$M ),
  point_type = replace_cases( signifcant, c( T, F ), c( 21, 19 ) ),
  margin = c( .5, .5, .2, 1.75 ), text_size = c( 1.25, .8 )
)