forestplot2: Create a forest plot

In raredd/Gmisc0: Collection of functions for plotting relations, generating tables, and more.

Description

forestplot2 is based on the rmeta 2.16 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 windows size

Usage

forestplot2(labeltext, mean, lower, upper, align = NULL, is.summary = FALSE,
  fontfamily.summary = NULL, fontfamily.labelrow = NULL, clip = c(-Inf,
  Inf), xlab = "", zero = 0, graphwidth = "auto", lineheight = "auto",
  col = fpColors(), xlog = FALSE, xticks = NULL, xticks.digits = 2,
  lwd.xaxis = NULL, lwd.zero = NULL, lwd.ci = NULL, cex = 1,
  cex.axis = cex * 0.6, boxsize = NULL, mar = unit(rep(5, times = 4),
  "mm"), main = NULL, legend = NULL, legend.pos = "top",
  legend.cex = cex * 0.8, legend.gp = NULL, legend.r = unit(0, "snpc"),
  legend.padding = unit(ifelse(length(legend.gp) > 0, 3, 0), "mm"),
  legend.title = NULL, new_page = FALSE, confintNormalFn = fpDrawNormalCI,
  confintSummaryFn = fpDrawSummaryCI, legendMarkerFn = NULL, ...)

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.
mean	A vector or a matrix with the averages
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 columns of table
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.
fontfamily.summary	The fontfamily of the summary
fontfamily.labelrow	The fontfamily of a regular row
clip	Lower and upper limits for clipping confidence intervals to arrows
xlab	x-axis label
zero	x-axis coordinate for zero line
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.
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 text height is as your line height.
col	See fpColors
xlog	If TRUE, x-axis tick marks are exponentiated
xticks	Optional user-specified x-axis tick marks. Specify NULL to use the defaults, numeric(0) to omit the x-axis.
xticks.digits	The number of digits to allow in the x-axis if this is created by default.
lwd.xaxis	lwd for the xaxis
lwd.zero	lwd for the vertical line that gives the no-effect line
lwd.ci	lwd for the confidence bands
cex	The font adjustment
cex.axis	The font adjustment for the x-xaxis, defaults to 60 % of the cex parameter.
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()
main	The title of the plot if any, default NULL
legend	Legen corresponding to the number of bars.
legend.pos	The position of the legend, either at the "top" or the "right" unlesss positioned inside the plot. If you want the legend to be positioned inside the plot then you have to provide a list with the same x & y qualities as legend. For instance if you want the legend to be positioned at the top right corner then use legend.pos = list("topright") - this is equivalent to legend.pos = list(x=1, y=1). If you want to have a distance from the edge of the graph then add a inset to the list, e.g. legend.pos = list("topright", "inset"=.1) - the inset should be either a unit element or a value between 0 and 1. The default is to have the boxes aligned vertical, if you want them to be in a line then you can specify the "align" option, e.g. legend.pos = list("topright", "inset"=.1, "align"="horizontal")
legend.cex	The cex size of the legend, defaults to 80 % procent of cex parameter.
legend.gp	The gpar options for the legend. If you want the background color to be light grey then use legend.gp = gpar(fill = "lightgrey"). If you want a border then set the col argument: legend.gp = gpar(fill = "lightgrey", col="black"). You can also use the lwd and lty argument as usual, legend.gp = gpar(lwd=2, lty=1), will result in a black border box of line type 1 and line width 2.
legend.r	The box can have rounded edges, check out grid.roundrect. The r option should be a unit object. This is by default unit(0, "snpc") but you can choose any value that you want. The "snpc" unit is the preferred option.
legend.padding	The padding for the legend box, only used if box is drawn. This is the distance from the border to the text/boxes of the legend.
legend.title	The title of the legend if any, default to NULL
new_page	If you want the plot to appear on a new blank page then set this to TRUE, by default it is FALSE.
confintNormalFn	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.
confintSummaryFn	Same as previous argument but for the summary outputs and it defaults to fpDrawSummaryCI.
legendMarkerFn	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.
...	Passed on to the confintNormalFn and confintSummaryFn arguments

Details

Using multiple bands for the same label can be interesting when one wants to compare different outcomer. It can also be an alternative when you want to show both crude and adjusted estimates.

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.

Value

void

Author(s)

Max Gordon, Thomas Lumley

See Also

Other forestplot functions: fpColors; fpDrawCircleCI, fpDrawDiamondCI, fpDrawNormalCI, fpDrawPointCI, fpDrawSummaryCI

Examples

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

ask <- par(ask=TRUE)
library(grid)

# 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))
forestplot2(row_names, 
            test_data$coef, 
            test_data$low, 
            test_data$high, 
            zero = 1, 
            cex  = 2,
            lineheight = "auto",
            xlab = "Lab axis txt",
            new_page = TRUE)

# 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))
forestplot2(row_names, 
            test_data$coef, 
            test_data$low, 
            test_data$high, 
            zero = 1, 
            cex  = 2,
            lineheight = "auto",
            xlab = "Lab axis txt")
popViewport()
pushViewport(viewport(layout.pos.col = 2))
forestplot2(row_names, 
            test_data$coef, 
            test_data$low, 
            test_data$high, 
            zero = 1, 
            cex  = 2,
            lineheight = "auto",
            xlab = "Lab axis txt")
popViewport()
popViewport()


# 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))
forestplot2(row_names, coef, low, high, 
            main="Cool study",
            zero = 1, boxsize=0.5,
            col=fpColors(box=c("royalblue", "gold"),
                         line=c("darkblue", "orange"),
                         summary=c("darkblue", "red")),
            xlab="The estimates",
            new_page = TRUE, 
            legend.title="Group",
            legend=c("Treatment", "Placebo"),
            legend.pos=list("topright"),
            legend.r = unit(.1, "snpc"),
            legend.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)

forestplot2(labeltext = row_names, 
            is.summary=c(TRUE, FALSE, FALSE),
            mean      = test_data$coef, 
            lower     = test_data$low, 
            upper     = test_data$high, 
            boxsize   = test_data$boxsize,
            zero      = 1,
            xlog      = TRUE,
            col = fpColors(lines="red", box="darkred"),
            new_page = TRUE)


par(ask=ask)

raredd/Gmisc0 documentation built on May 27, 2019, 2:02 a.m.