Creates a forest plot with ggplot
Usage
forest_plot(
panels,
row.labels = NULL,
row.labels.levels = NULL,
rows = NULL,
row.labels.heading = NULL,
row.labels.space = c(0, 1, 0, 0),
exponentiate = TRUE,
logscale = exponentiate,
panel.names = NULL,
panel.headings = NULL,
panel.headings.align = c("panel", "plot"),
col.key = "key",
col.estimate = c("estimate", "est", "beta", "loghr"),
col.stderr = c("stderr", "std.err", "se"),
col.lci = NULL,
col.uci = NULL,
col.left = NULL,
col.right = NULL,
col.right.parse = FALSE,
col.left.heading = "",
col.right.heading = as.list(xlab),
col.left.pos = NULL,
col.right.pos = NULL,
col.left.hjust = 1,
col.right.hjust = 0,
col.left.gap = c("I", "W"),
col.right.gap = c("I", "W"),
col.heading.space = 0,
col.heading.rule = FALSE,
estcolumn = TRUE,
col.keep = NULL,
ci.delim = ", ",
digits = 2,
title = "",
xlab = "HR (95% CI)",
xlim = NULL,
xticks = NULL,
nullval = NULL,
col.diamond = NULL,
diamond = NULL,
col.bold = NULL,
bold.labels = NULL,
scalepoints = FALSE,
minse = NULL,
pointsize = 3,
shape = 15,
plotcolour = "black",
colour = plotcolour,
cicolour = colour,
fill = colour,
ciunder = NULL,
addtext = NULL,
bottom.space = 0.7,
left.space = NULL,
right.space = NULL,
mid.space = unit(5, "mm"),
plot.margin = margin(2, 8, 2, 8, "mm"),
panel.width = NULL,
panel.height = NULL,
base_size = 11,
base_line_size = base_size/22,
stroke = 0,
diamonds.linewidth = base_line_size,
quiet = FALSE,
printplot = !quiet,
showcode = !quiet,
data.function = NULL,
addaes = NULL,
addarg = NULL,
add = NULL,
envir = NULL,
blankrows = NULL
)Arguments
- panels
A list of data frames. These should include columns or point estimates, and standard errors or confidence interval limits. If you specify a row.labels data frame, then they must also all contain a key column with the same name (which can be specified by col.key).
- row.labels
A data frame that contains the labels to be used for the rows of the plot. Use NA if a lower level heading is not required for a given row.
- row.labels.levels
A character vector. The names of columns in row.labels to use as headings/subheadings/labels for labelling rows.
- rows
If set, then only rows matching these labels (at the first level) will be included.
- row.labels.heading
Title to be placed above row labels.
- row.labels.space
A numeric vector specifying the space after a row label heading, at the end of a row label heading 'section'. (Default: c(0, 1, 0, 0))
- exponentiate
Exponentiate estimates (and CIs) before plotting. (Default: TRUE)
- logscale
Use log scale on the axis, and add a line at null effect. (Default: exponentiate)
- panel.names
A character vector. The names to be used for each forest plot panel. If none provided, then they will be numbered 1, 2, 3 ...
- panel.headings
Titles to be placed above each forest plot.
- panel.headings.align
Panel headings are by default centred over the plotting area ("panel"). Set to "plot" to centre over plotting area and text columns.
- col.key
Name of column that links the results given in each data frame provided in panels and the labels given in row.labels. If row.labels data frame is not given, then this column will be used as row labels. (Default: "key")
- col.estimate, col.stderr, col.lci, col.uci
Names of columns for: point estimates, standard errors, lower and upper limits of confidence intervals.
- col.left, col.right
Names of columns to be printed to the left/right of the plot.
- col.right.parse
A logical vector, the same length as col.right (+ 1 if estcolumn = TRUE). Should the contents of the columns be parsed into expressions. (Default: FALSE)
- col.left.heading, col.right.heading
Headings for columns.
- col.left.pos, col.right.pos
A unit vector to position col.left/col.right columns.
- col.left.hjust, col.right.hjust
A numeric vector. The horizontal justification of col.left/col.right columns. (Default: 1)
- col.left.gap, col.right.gap
A character vector of length two. The two characters control the gaps between the first text column and the panel, and successive text columns. (Default: c("I", "W"))
- col.heading.space
Position of the titles given by col.left.heading and col.right.heading. Increase to move them up. (Default: 0)
- col.heading.rule
Include a horizontal rule below column headings? (Default: FALSE)
- estcolumn
Include column of estimates and confidence intervals to the right of each plot. (Default: TRUE)
- col.keep
Names of additional columns to be kept in returned data frame.
- ci.delim
Character string to separate lower and upper limits of confidence interval. (Default: ", ")
- digits
Number of digits after decimal point to show for estimates and confidence intervals. (Default: 2)
- title
Title to appear at the top of the plot.
- xlab
Label to appear below the x-axis. (Default: "HR (95% CI)")
- xlim
A numeric vector. The limits of the x axis.
- xticks
A numeric vector. The tick points of the x axis.
- nullval
Add a vertical reference line at this value. (If logscale == TRUE then by default it will be added at 1, but use NA not to plot this line.)
- col.diamond
Plot estimates and CIs as diamonds. Name of a column of logical values.
- diamond
Alternative to col.diamond. A character vectors identify the rows (using the key values) for which the estimate and CI should be plotted using a diamond.
- col.bold
Plot text as bold. Name of a column of logical values.
- bold.labels
A character vector identifying row labels (using key values) which should additionally be bold. (Default: NULL)
- scalepoints
Should the points be scaled by inverse of the standard error? (Default: FALSE)
- minse
Minimum standard error to use when scaling point size. (Default will use minimum in the data.)
- pointsize
The (largest) size of box to use for plotting point estimates. (Default: 3)
- shape
Shape of points. An integer, or name of a column of integers. (Default: 15 (square))
- plotcolour
Colour for all parts of the plot. (Default: "black")
- colour
Colour of points. Name of a colour, or name of a column of colour names. (Default will use plotcolour.)
- cicolour
Colour of CI lines. Colour of CI lines. Name of a colour, or name of a column of colour names. (Default will use colour.)
- fill
Fill colour of points. Name of a colour, or name of a column of colour names. (Default will use colour.)
- ciunder
Plot CI lines before points. A logical value, or name of a column of logical values. (Default will plot CI lines after points.)
- addtext
A list of data frames. List must be the same length as panels. Data frames should contain a column with the name specified in col.key, and one or more of:
a column named 'text' containing character strings
columns named 'het_dof', 'het_stat', and 'het_p' containing character strings
columns names 'trend_stat' and 'trend_p' containing character strings
The character strings, heterogeneity test, and trend test results will be plotted in the column of estimates and CIs, below the row with the key given in the col.key column.
- bottom.space
Space between bottom row and axis. (Default: 0.7)
- left.space, right.space, mid.space
Space to the left/right/between panels. (Default mid.space: unit(5, "mm"))
- plot.margin
Plot margin, given as margin(top, right, bottom, left, units). (Default: margin(8, 8, 8, 8, "mm"))
- panel.width, panel.height
Set width/height of panels. A grid::unit object, if a numeric is given assumed to be in mm. If panel.width is used, will alsovapply different formatting to narrow CIs.
- base_size
base font size, given in pts.
- base_line_size
base size for line elements
- stroke
Size of outline of shapes. (Default: 0)
- diamonds.linewidth
Line width for diamonds. (Default: base_line_size)
- quiet
Set to TRUE to not print the plot nor show generated code in the RStudio 'Viewer' pane. (Default: FALSE)
- printplot
Print the plot. (Default: !quiet)
- showcode
Show the ggplot2 code to generate the plot in RStudio 'Viewer' pane. (Default: !quiet)
- data.function
Name of a function to apply to data frame before plotting.
- addaes, addarg, add
Methods for customising the plot. See documentation for details.
- envir
Environment in which to evaluate the plot code. May be useful when calling this function inside another function.
- blankrows
DEPRECATED