forestplot (version 1.0)

forestplot: 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(labeltext, mean, lower, upper, align, is.summary = FALSE,
  clip = c(-Inf, Inf), xlab = "", zero = ifelse(xlog, 1, 0),
  graphwidth = "auto", lineheight = "auto", line.margin, col = fpColors(),
  txt_gp = fpTxtGp(), xlog = FALSE, xticks, xticks.digits = 2, lwd.xaxis,
  lwd.zero, lwd.ci, boxsize, mar = unit(rep(5, times = 4), "mm"), title,
  legend, legend_args = fpLegend(), new_page = FALSE,
  fn.ci_norm = fpDrawNormalCI, fn.ci_sum = fpDrawSummaryCI, fn.legend, ...)

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 provid

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

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

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

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

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

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

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

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

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

...

Passed on to the fn.ci_norm and fn.ci_sum arguments

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.

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 <pkg>rmeta</pkg>-package`s <code><a href="/link/forestplot?package=forestplot&version=1.0&to=rmeta" rd-options="rmeta" data-mini-rdoc="rmeta::forestplot">forestplot</a></code>

• 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}

See Also

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

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


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