forest {forestploter}

Forest plot

Description

A data frame will be used for the basic layout of the forest plot. Graphical parameters can be set using the forest_theme function.

Usage

forest(
  data,
  est,
  lower,
  upper,
  sizes = 0.4,
  ref_line = ifelse(x_trans %in% c("log", "log2", "log10"), 1, 0),
  vert_line = NULL,
  ci_column,
  is_summary = NULL,
  xlim = NULL,
  ticks_at = NULL,
  ticks_digits = NULL,
  ticks_minor = NULL,
  arrow_lab = NULL,
  x_trans = "none",
  xlab = NULL,
  footnote = NULL,
  title = NULL,
  nudge_y = 0,
  fn_ci = makeci,
  fn_summary = make_summary,
  index_args = NULL,
  theme = NULL,
  ...
)

Arguments

data

Data to be displayed in the forest plot

est

Point estimation. Can be a list for multiple columns and/or multiple groups. If the length of the list is larger than then length of ci_column, then the values reused for each column and considered as different groups.

lower

Lower bound of the confidence interval, same as est.

upper

Upper bound of the confidence interval, same as est.

sizes

Size of the point estimation box, can be a unit, vector or a list. Values will be used as it is, no transformation will be applied.

ref_line

X-axis coordinates of zero line, default is 1. Provide an atomic vector if different reference line for each ci_column is desired.

vert_line

Numerical vector, add additional vertical line at given value. Provide a list of numerical vector element if different vertical line for each ci_column is desired.

ci_column

Column number of the data the CI will be displayed.

is_summary

A logical vector indicating if the value is a summary value, which will have a diamond shape for the estimate. Can not be used with multiple group forestplot.

xlim

Limits for the x axis as a vector of length 2, i.e. c(low, high). It will take the minimum and maximum of the lower and upper value if not provided. This will apply to all CI columns if provided, and will be calculated automatically for each column if not provided. This should be a list with the same length of ci_column if different xlim for different column is desired.

ticks_at

Set X-axis tick-marks point. This will apply to all CI columns if provided, and will be calculated automatically for each column if not provided. This should be a list if different ticks_at for different column is desired. Although many efforts have been made to automatically get a pretty ticks break, it will not give a perfect solution, especially if 'log2' and 'log10' defined for x_trans. Please provide this value if possible.

ticks_digits

Number of digits for the x-axis, default is NULL to calculate an integer based on ticks_at if provided or lower and upper if not. This should be a numerical vector if different rounding will be applied to different column. If an integer is specified, for example 1L, trailing zeros after the decimal mark will be dropped. Specify numeric, for example 1, to keep the trailing zero after the decimal mark.

ticks_minor

A numeric vector of positions to draw ticks without labels (optional). The values provided here can be superset or disjoint sets of ticks_at.

arrow_lab

Labels for the arrows, string vector of length two (left and right). The theme of arrow will inherit from the x-axis. This should be a list if different arrow labels for each column is desired.

x_trans

Change axis scale, Allowed values are one of c("none", "log", "log2", "log10"). Default is "none", no transformation will be applied. The formatted label will be used for scale = "log2" or "log10", change this in x_trans. Set this to "log" if x-axis tick marks assume values are exponential, e.g. for logistic regression (OR), survival estimates (HR), Poisson regression etc.

xlab

X-axis labels, it will be put under the x-axis. An atomic vector should be provided if different xlab for different column is desired.

footnote

Footnote for the forest plot, will be aligned at left bottom of the plot. Please adjust the line length with line break to avoid the overlap with the arrow and/or x-axis.

title

The text for the title.

nudge_y

Horizontal adjustment to nudge groups by, must be within 0 to 1.

fn_ci

Name of the function to draw confidence interval, default is makeci. You can specify your own drawing function to draw the confidence interval, but the function needs to accept arguments "est", "lower", "upper", "sizes", "xlim", "pch", "gp", "t_height", "nudge_y". Please refer to the makeci function for the details of these parameters.

fn_summary

Name of the function to draw summary confidence interval, default is make_summary. You can specify your own drawing function to draw the summary confidence interval, but the function needs to accept arguments "est", "lower", "upper", "sizes", "xlim", "gp". Please refer to the make_summary function for the details of these parameters.

index_args

A character vector, name of the arguments used for indexing the row and column. This should be the name of the arguments that is working the same way as est, lower and upper. Check out the examples in the make_boxplot.

theme

Theme of the forest plot, see forest_theme for details.

...

Other arguments passed on to the fn_ci and fn_summary.

Value

A gtable object.

See Also

gtable tableGrob forest_theme make_boxplot makeci make_summary

Examples

library(grid)
# Read provided sample example data
dt <- read.csv(system.file("extdata", "example_data.csv", package = "forestploter"))

# Keep needed columns
dt <- dt[,1:6]

# indent the subgroup if there is a number in the placebo column
dt$Subgroup <- ifelse(is.na(dt$Placebo),
                      dt$Subgroup,
                      paste0("   ", dt$Subgroup))

# NA to blank or NA will be transformed to carachter.
dt$Treatment <- ifelse(is.na(dt$Treatment), "", dt$Treatment)
dt$Placebo <- ifelse(is.na(dt$Placebo), "", dt$Placebo)
dt$se <- (log(dt$hi) - log(dt$est))/1.96

# Add blank column for the forest plot to display CI.
# Adjust the column width with space.
dt$` ` <- paste(rep(" ", 20), collapse = " ")

# Create confidence interval column to display
dt$`HR (95% CI)` <- ifelse(is.na(dt$se), "",
                             sprintf("%.2f (%.2f to %.2f)",
                                     dt$est, dt$low, dt$hi))

# Define theme
tm <- forest_theme(base_size = 10,
                   refline_gp = gpar(col = "red"),
                   footnote_gp = gpar(col = "#636363", fontface = "italic"))

p <- forest(dt[,c(1:3, 8:9)],
            est = dt$est,
            lower = dt$low,
            upper = dt$hi,
            sizes = dt$se,
            ci_column = 4,
            ref_line = 1,
            arrow_lab = c("Placebo Better", "Treatment Better"),
            xlim = c(0, 4),
            ticks_at = c(0.5, 1, 2, 3),
            footnote = "This is the demo data. Please feel free to change\nanything you want.",
            theme = tm)

# Print plot
plot(p)