multiforest: Produce multiple forest plots side by side
In CALIBERdatamanage: Data Management Tools for CALIBER Datasets

Description Usage Arguments Details Value See Also Examples

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.

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, ...)

`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.

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.

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

test_multiforest, test_multiforest2

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)