Produce multiple forest plots side by side

Share:

Description

Produces forest plot using data in a standardised format from a spreadsheet. Can produce multiple forest plots in one figure, arranged horizontally. Box sizes, font styles and sizes can be specified in a spreadsheet to make the output easy to configure.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
multiforest(data = NULL, rowheights = 1.1, colgaps = unit(0.3, "cm"),
    colgaps_cm = NULL, defaultfontface = "plain",
    defaultjust = "left", defaultfontsize = 10,
    defaultgraphwidth = unit(5, "cm"), 
    defaultboxsize = 0.8, defaultboxcolour = "black",
    defaultlinecolour = "black", defaultxlab = "Hazard ratio",
    xticks = NULL, xtickfontsize = 10, xlabfontsize = 12,
    xlaboffset = -2.5, zerocolour = "gray", zerolinewidth = 1,
    zerolineposition = NULL, ...)
multiforestPNG(data, outfile, border = 0.1, ...)
multiforestPDF(data, outfile, border = 0.1, ...)

Arguments

data

either a filename of a tab or comma-delimited text file or Stata file containing the data to plot, or a data.frame containing this information. If NULL, the user is asked to choose the text file using file.choose.

outfile

output filename. If missing and data is a filename, the time and PNG or PDF file extension are appended to the data file name.

border

border width in inches.

rowheights

relative row height (default=1), can be a single number or a vector of heights

colgaps

gap between columns of the output.

colgaps_cm

a convenience wrapper for supplying colgaps as a units object.

defaultfontface

font face as a character string, default = 'plain', possible alternatives are 'bold', 'italic' or 'bold.italic'

defaultjust

default justification of text, default = 'left', possible alternatives are 'right' or 'centre'

defaultfontsize

a number specifying the default point size

defaultgraphwidth

default width of graph as a unit object, if not specified in data

defaultboxsize

default box size, between 0 and 1. Set to NULL to set box size to relative inverse variance.

defaultboxcolour

default box colour, if not specified in data

defaultlinecolour

default line colour, if not specified in data

defaultxlab

default label for x axis

xticks

a vector of positions for tick marks on the x axis, NULL to generate tick positions from the data

xtickfontsize

point size of axis numbers

xlabfontsize

point size of x axis label

xlaboffset

offset of x axis label from axis, measured in text lines

zerocolour

colour of zero line (for hazard ratio = 1)

zerolinewidth

width of zero line

zerolineposition

NULL to keep default position (0 on the linear scale, 1 where log coefficients are supplied and they are exponentiated in the graph, such as for hazard ratios or odds ratios). Alternatively supply the value for plotting.

...

Other arguments to multiforest, read.delim or read.dta.

Details

Uses grid graphics. Based on the forestplot function in the rmeta package, with extensions to allow multiple plots and other options.

The spreadsheet must contain groups of columns specifying the text, numbers to graph and formatting column headings in the first row. The first two characters of each column heading denote the group, and the remainder must be one of the following:

For text columns:

text

text or an R expression. If the text is of the form expression(<R expression>), e.g. expression(paste(theta^2)) it is interpreted as an R expression, otherwise it is treated as text.

fontface

either 'plain', 'italic', 'bold' or 'bold.italic' (must be in lower case)

fontsize

size of font in points

just

'left', 'right' or 'centre'

numcols

number of columns to span (default = 1)

To insert spaces between columns, either specify the colgaps argument, or insert an intermediate column with the appropriate number of spaces in one of the cells to provide the correct width. (see test_multiforest2).

For graph columns, options which apply to every row:

mean

coefficient; required

upper

upper 95% CI; either upper and lower or se must be supplied

lower

lower 95% CI

se

standard error, can be used to calculate 95% CI if upper and lower are not supplied

boxsize

relative box sizes

boxcolour

colour specified as a string

linecolour

line colour specified as a string

linewidth

default is 2

summary

1 if it is the summary row, 0 if not

clipupper

clip if upper CI greater than this

cliplower

clip if lower CI less than this

xrange

range to plot on the x axis (can be a pair or a whole set of numbers or a single number, in which case it is taken as the maximum and zero is taken as the minimum). If not supplied it is derived from xticks or the data

For graph columns, the following options apply to the whole graph, and only the first row below the column heading is considered:

xlog

whether to use a log scale: 1 for log scale (default), 0 for ordinary scale (which will not exponentiate coefficients either)

xlab

label for x axis, default is 'Hazard ratio'

graphwidth

width of graph in centimetres

For example, the column headings might be a1text, a1fontface, g1mean, g1se, ... If a column is omitted the default settings are used.

See http://research.stowers-institute.org/efg/R/Color/Chart/ColorChart.pdf for a list of colours.

Value

multiforest returns a list containing the image dimensions, which is used by multiforestPNG and multiforestPDF to output the plot at the appropriate size.

height_in_inches

height of the plot in inches

width_in_inches

width of the plot in inches

See Also

test_multiforest, test_multiforest2

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
mydata <- data.frame(a1text = c(
    'expression(paste("Graph of ", theta))', 'Plot1', 'Plot2',
    'expression(theta)'),
    a1fontface = c('plain', 'italic', 'bold', 'bold.italic'),
    a1fontsize = c(13, 9, 10, 11),
    a1just = c('centre', 'left', 'right', 'right'),
    a1numcols = c(2, 1, 1, 1),
    a2mean = c(NA, 0.3, 0.6, 1),
    a2se = c(NA, 0.3, 0.6, 0.1),
    a2boxsize = c(NA, 1, 2, 3),
    a2boxcolour = c(NA, 'red', 'green', 'blue'),
    a2linecolour = c(NA, 'red', 'green', 'black'),
    a2linewidth = c(NA, 1, 2, 3),
    a2summary = c(0, 0, 0, 1))
multiforest(mydata, xticks = c(0.5, 1, 2, 4))

# Load an example from data
data(test_multiforest)
multiforest(test_multiforest)

# Another example
data(test_multiforest2)
# Create spaces in column 2 (these were lost when the text file was
# loaded using 'data', but wil be retained if loaded directly by multiforest)
test_multiforest2$a2text <- "   "
multiforest(test_multiforest2)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.