forestplot: forestplot – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Draws a forest plot

Description

The forestplot is based on the rmeta-package's forestplot function. This function resolves some limitations of the original functions such as:

Adding expressions: Allows use of expressions, e.g. expression(beta)
Multiple bands: Using multiple confidence bands for the same label
Autosize: Adapts to viewport (graph) size

Usage

forestplot(...)

## Default S3 method:
forestplot(
  labeltext,
  mean,
  lower,
  upper,
  align,
  is.summary = FALSE,
  graph.pos = "right",
  hrzl_lines,
  clip = c(-Inf, Inf),
  xlab = "",
  zero = ifelse(xlog, 1, 0),
  graphwidth = "auto",
  colgap,
  lineheight = "auto",
  line.margin,
  col = fpColors(),
  txt_gp = fpTxtGp(),
  xlog = FALSE,
  xticks,
  xticks.digits = 2,
  grid = FALSE,
  lwd.xaxis,
  lwd.zero,
  lwd.ci,
  lty.ci = 1,
  ci.vertices,
  ci.vertices.height = 0.1,
  boxsize,
  mar = unit(rep(5, times = 4), "mm"),
  title,
  legend,
  legend_args = fpLegend(),
  new_page = getOption("forestplot_new_page", TRUE),
  fn.ci_norm = fpDrawNormalCI,
  fn.ci_sum = fpDrawSummaryCI,
  fn.legend,
  shapes_gp = fpShapesGp(),
  ...
)

Arguments

`...`	Passed on to the `fn.ci_norm` and `fn.ci_sum` arguments
`labeltext`	A list, matrix, vector or expression with the names of each row. The list should be wrapped in m x n number to resemble a matrix: `list(list("rowname 1 col 1", "rowname 2 col 1"), list("r1c2", expression(beta))`. You can also provide a matrix although this cannot have expressions by design: `matrix(c("rowname 1 col 1", "rowname 2 col 1", "r1c2", "beta"), ncol=2)`. Use `NA`:s for blank spaces and if you provide a full column with `NA` then that column is a empty column that adds some space. Note: If you do not provide the mean/lower/upper arguments the function expects the label text to be a matrix containing the labeltext in the rownames and then columns for mean, lower, and upper.
`mean`	A vector or a matrix with the averages. You can also provide a 2D/3D matrix that is automatically converted to the lower/upper parameters. The values should be in exponentiated form if they follow this interpretation, e.g. use exp(mean) if you have the output from a logistic regression
`lower`	The lower bound of the confidence interval for the forestplot, needs to be the same format as the mean, i.e. matrix/vector of equal columns & length
`upper`	The upper bound of the confidence interval for the forestplot, needs to be the same format as the mean, i.e. matrix/vector of equal columns \& length
`align`	Vector giving alignment (l,r,c) for the table columns
`is.summary`	A vector indicating by `TRUE`/`FALSE` if the value is a summary value which means that it will have a different font-style
`graph.pos`	The position of the graph element within the table of text. The position can be `1-(ncol(labeltext) + 1)`. You can also choose set the positin to `"left"` or `"right"`.
`hrzl_lines`	Add horizontal lines to graph. Can either be `TRUE` or a `list` of `gpar`. See line section below for details.
`clip`	Lower and upper limits for clipping confidence intervals to arrows
`xlab`	x-axis label
`zero`	x-axis coordinate for zero line. If you provide a vector of length 2 it will print a rectangle instead of just a line. If you provide NA the line is supressed.
`graphwidth`	Width of confidence interval graph, see `unit` for details on how to utilize mm etc. The default is `auto`, that is it uses up whatever space that is left after adjusting for text size and legend
`colgap`	Sets the gap between columns, defaults to 6 mm but for relative widths. Note that the value should be in `unit(,"npc")`.
`lineheight`	Height of the graph. By default this is `auto` and adjustes to the space that is left after adjusting for x-axis size and legend. Sometimes it might be desireable to set the line height to a certain height, for instance if you have several forestplots you may want to standardize their line height, then you set this variable to a certain height, note this should be provided as a `unit` object. A good option is to set the line height to `unit(2, "cm")`. A third option is to set line height to "lines" and then you get 50 % more than what the text height is as your line height
`line.margin`	Set the margin between rows, provided in numeric or `unit` formar. When having multiple confidence lines per row setting the correct margin in order to visually separate rows
`col`	Set the colors for all the elements. See `fpColors` for details
`txt_gp`	Set the fonts etc for all text elements. See `fpTxtGp` for details
`xlog`	If TRUE, x-axis tick marks are to follow a logarithmic scale, e.g. for logistic regressoin (OR), survival estimates (HR), Poisson regression etc. Note: This is an intentional break with the original `forestplot` function as I've found that exponentiated ticks/clips/zero effect are more difficult to for non-statisticians and there are sometimes issues with rounding the tick marks properly.
`xticks`	Optional user-specified x-axis tick marks. Specify NULL to use the defaults, numeric(0) to omit the x-axis. By adding a labels-attribute, `attr(my_ticks, "labels") <- ...` you can dictate the outputted text at each tick. If you specify a boolean vector then ticks indicated with FALSE wont be printed. Note that the labels have to be the same length as the main variable.
`xticks.digits`	The number of digits to allow in the x-axis if this is created by default
`grid`	If you want a discrete gray dashed grid at the level of the ticks you can set this parameter to `TRUE`. If you set the parameter to a vector of values lines will be drawn at the corresponding positions. If you want to specify the `gpar` of the lines then either directly pass a `gpar` object or set the gp attribute e.g. `attr(line_vector, "gp") <- gpar(lty=2, col = "red")`
`lwd.xaxis`	lwd for the xaxis, see `gpar`
`lwd.zero`	lwd for the vertical line that gives the no-effect line, see `gpar`
`lwd.ci`	lwd for the confidence bands, see `gpar`
`lty.ci`	lty for the confidence bands, see `gpar`
`ci.vertices`	Set this to TRUE if you want the ends of the confidence intervals to be shaped as a T. This is set default to TRUE if you have any other line type than 1 since there is a risk of a dash occurring at the very end, i.e. showing incorrectly narrow confidence interval.
`ci.vertices.height`	The height hoft the vertices. Defaults to npc units corresponding to 10% of the row height. Note that the arrows correspond to the vertices heights.
`boxsize`	Override the default box size based on precision
`mar`	A numerical vector of the form `c(bottom, left, top, right)` of the type `unit`
`title`	The title of the plot if any
`legend`	Legend corresponding to the number of bars
`legend_args`	The legend arguments as returned by the `fpLegend` function.
`new_page`	If you want the plot to appear on a new blank page then set this to `TRUE`, by default it is `TRUE`. If you want to change this behavior for all plots then set the `options(forestplot_new_page = FALSE)`
`fn.ci_norm`	You can specify exactly how the line with the box is drawn for the normal (i.e. non-summary) confidence interval by changing this parameter to your own function or some of the alternatives provided in the package. It defaults to the box function `fpDrawNormalCI`
`fn.ci_sum`	Same as previous argument but for the summary outputs and it defaults to `fpDrawSummaryCI`.
`fn.legend`	What type of function should be used for drawing the legends, this can be a list if you want different functions. It defaults to a box if you have anything else than a single function or the number of columns in the `mean` argument
`shapes_gp`	Sets graphical parameters (squares and lines widths, styles, etc.) of all shapes drawn (squares, lines, diamonds, etc.). This overrides `col`, `lwd.xaxis`, `lwd.zero`, `lwd.ci` and `lty.ci`.

Details

See vignette("forestplot") for details.

Value

NULL

Multiple bands

Using multiple bands, i.e. multiple lines, per variable can be interesting when you want to compare different outcomes. E.g. if you want to compare survival specific to heart disease to overall survival for smoking it may be useful to have two bands on top of eachother. Another useful implementation is to show crude and adjusted estimates as separate bands.

Horizontal lines

The argument hrzl_lines can be either TRUE or a list with gpar elements:

TRUEA line will be added based upon the is.summary rows. If the first line is a summary it
gparThe same as above but the lines will be formatted according to the gpar element
listThe list must either be numbered, i.e. list("2" = gpar(lty=1)), or have the same length as the NROW(mean) + 1. If the list is numbered the numbers should not exceed the NROW(mean) + 1. The no. 1 row designates the top, i.e. the line above the first row, all other correspond to the row below. Each element in the list needs to be TRUE, NULL, or gpar element. The TRUE defaults to a standard line, the NULL skips a line, while gpar corresponds to the fully customized line. Apart from allowing standard gpar line descriptions, lty, lwd, col, and more you can also specify gpar(columns = c(1:3, 5)) if you for instance want the line to skip a column.

Known issues

The x-axis does not entirely respect the margin. Autosizing boxes is not always the best option, try to set these manually as much as possible.

API-changes from rmeta-package's `forestplot`

xlog: The xlog outputs the axis in log() format but the input data should be in antilog/exp format
col: The corresponding function is fpColors for this package

Author(s)

Max Gordon, Thomas Lumley

Examples

#############################################
# Simple examples of how to do a forestplot #
#############################################

ask <- par(ask = TRUE)

# A basic example, create some fake data
row_names <- list(list("test = 1", expression(test >= 2)))
test_data <- data.frame(
  coef = c(1.59, 1.24),
  low = c(1.4, 0.78),
  high = c(1.8, 1.55)
)
forestplot(row_names,
  test_data$coef,
  test_data$low,
  test_data$high,
  zero = 1,
  cex  = 2,
  lineheight = "auto",
  xlab = "Lab axis txt"
)

# Print two plots side by side using the grid
# package's layout option for viewports
grid.newpage()
pushViewport(viewport(layout = grid.layout(1, 2)))
pushViewport(viewport(layout.pos.col = 1))
forestplot(row_names,
  test_data$coef,
  test_data$low,
  test_data$high,
  zero = 1,
  cex  = 2,
  lineheight = "auto",
  xlab = "Lab axis txt",
  new_page = FALSE
)
popViewport()
pushViewport(viewport(layout.pos.col = 2))
forestplot(row_names,
  test_data$coef,
  test_data$low,
  test_data$high,
  zero = 1,
  cex  = 2,
  lineheight = "auto",
  xlab = "Lab axis txt",
  new_page = FALSE
)
popViewport(2)


# An advanced test
test_data <- data.frame(
  coef1 = c(1, 1.59, 1.3, 1.24),
  coef2 = c(1, 1.7, 1.4, 1.04),
  low1 = c(1, 1.3, 1.1, 0.99),
  low2 = c(1, 1.6, 1.2, 0.7),
  high1 = c(1, 1.94, 1.6, 1.55),
  high2 = c(1, 1.8, 1.55, 1.33)
)

col_no <- grep("coef", colnames(test_data))
row_names <- list(
  list("Category 1", "Category 2", "Category 3", expression(Category >= 4)),
  list(
    "ref",
    substitute(
      expression(bar(x) == val),
      list(val = round(rowMeans(test_data[2, col_no]), 2))
    ),
    substitute(
      expression(bar(x) == val),
      list(val = round(rowMeans(test_data[3, col_no]), 2))
    ),
    substitute(
      expression(bar(x) == val),
      list(val = round(rowMeans(test_data[4, col_no]), 2))
    )
  )
)

coef <- with(test_data, cbind(coef1, coef2))
low <- with(test_data, cbind(low1, low2))
high <- with(test_data, cbind(high1, high2))
forestplot(row_names, coef, low, high,
  title = "Cool study",
  zero = c(0.98, 1.02),
  grid = structure(c(2^-.5, 2^.5),
    gp = gpar(col = "steelblue", lty = 2)
  ),
  boxsize = 0.25,
  col = fpColors(
    box = c("royalblue", "gold"),
    line = c("darkblue", "orange"),
    summary = c("darkblue", "red")
  ),
  xlab = "The estimates",
  new_page = TRUE,
  legend = c("Treatment", "Placebo"),
  legend_args = fpLegend(
    pos = list("topright"),
    title = "Group",
    r = unit(.1, "snpc"),
    gp = gpar(col = "#CCCCCC", lwd = 1.5)
  )
)

# An example of how the exponential works
test_data <- data.frame(
  coef = c(2.45, 0.43),
  low = c(1.5, 0.25),
  high = c(4, 0.75),
  boxsize = c(0.5, 0.5)
)
row_names <- cbind(
  c("Name", "Variable A", "Variable B"),
  c("HR", test_data$coef)
)
test_data <- rbind(rep(NA, 3), test_data)

forestplot(
  labeltext = row_names,
  test_data[, c("coef", "low", "high")],
  is.summary = c(TRUE, FALSE, FALSE),
  boxsize = test_data$boxsize,
  zero = 1,
  xlog = TRUE,
  col = fpColors(lines = "red", box = "darkred")
)

# An example using shapes_gp
forestplot(
  labeltext = cbind(Author = c("Smith et al", "Smooth et al", "Al et al")),
  mean = cbind(1:3, 1.5:3.5),
  lower = cbind(0:2, 0.5:2.5),
  upper = cbind(4:6, 5.5:7.5),
  is.summary = c(FALSE, FALSE, TRUE),
  shapes_gp = fpShapesGp(
    default = gpar(lineend = "square", linejoin = "mitre", lwd = 3, col = "pink"),
    box = gpar(fill = "black", col = "red"), # only one parameter
    lines = list( # as many parameters as CI
      gpar(lwd = 10), gpar(lwd = 5),
      gpar(), gpar(),
      gpar(lwd = 2), gpar(lwd = 1)
    ),
    summary = list( # as many parameters as band per label
      gpar(fill = "violet", col = "gray", lwd = 10),
      gpar(fill = "orange", col = "gray", lwd = 10)
    )
  ),
  vertices = TRUE
)

par(ask = ask)
# See vignette for a more detailed description
# vignette("forestplot",  package="forestplot")

forestplot

Advanced Forest Plot Using 'grid' Graphics

v1.10.1

GPL-2

Authors

Max Gordon [aut, cre], Thomas Lumley [aut, ctb]

Initial release

forestplot

Description

Usage

Arguments

Details

Value

Multiple bands

Horizontal lines

Known issues

API-changes from rmeta-package's `forestplot`

Author(s)

See Also

Examples

forestplot

We don't support your browser anymore

forestplot

Description

Usage

Arguments

Details

Value

Multiple bands

Horizontal lines

Known issues

API-changes from rmeta-package's forestplot

Author(s)

See Also

Examples

forestplot

We don't support your browser anymore

API-changes from rmeta-package's `forestplot`