plot_forest: Create a Forest Plot
In rettopnivek/arfpam: Assorted R Functions for Processing, Analysis, and Modeling

plot_forest

R Documentation

Create a Forest Plot

Description

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

Usage

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 )
)

rettopnivek/arfpam documentation built on Oct. 20, 2024, 7:24 p.m.