forest: Forest plot
In forestploter: Create a Flexible Forest Plot

forest

R Documentation

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.

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)

forestploter documentation built on May 29, 2024, 5:48 a.m.