Package description

Description

The forest plot function, forestplot(), is a more general version of the original rmeta-packages forestplot implementation. The aim is at using forest plots for more than just meta-analyses.

Details

The forestplot:

1. Allows for multiple confidence intervals per row

2. Custom fonts for each text element

3. Custom confidence intervals

4. Text mixed with expressions

5. Legends both on top/left of the plot and within the graph

6. Custom line height including auto-adapt height

7. Graph width that auto-adapts

8. Flexible arguments

9. and more

Additional functions

The getTicks tries to format ticks for plots in a nicer way. The major use is for exponential form where ticks are generated using the 2^n since a doubling is a concept easy to grasp for less mathematical-savvy readers.

Author(s)

Maintainer: Max Gordon max@gforge.se

Authors:

• Thomas Lumley [contributor]

See Also

Useful links:

• https://gforge.se/packages/

• Report bugs at https://github.com/gforge/forestplot/issues

Regression coefficients and confidence intervals from HRQoL study

Description

The data is a list containing the Swedish and the Danish coefficients for health related quality of life (HRQoL) 1 year after total hip arthroplasty surgery. The age is modeled as a spline and is therefore presented as a contrast.

Author(s)

Max Gordon max@gforge.se

Retriever of tidyselect

Description

As forestpot has evolved we now primarily use tidyverse select style. This function helps with backward compatibility

Usage

assertAndRetrieveTidyValue(
  x,
  value,
  name = deparse(substitute(value)),
  optional = FALSE
)

Arguments

Value

value with attribute

Regression coefficients and confidence intervals from HRQoL study

Description

The data is a dataframe with the Swedish and the Danish coefficients for health related quality of life (HRQoL) 1 year after total hip arthroplasty surgery. The age is modeled as a spline and is therefore presented as a contrast.

Author(s)

Max Gordon max@gforge.se

Draws the horizontal lines

Description

Draws the horizontal lines

Usage

drawHorizontalLines(lines, number_of_rows, colwidths, graph.pos)

Arguments

Draws a forest plot

Description

This function generates a forest plot with extended capabilities compared to the default forestplot() function in the rmeta package. It overcomes some limitations of the original function, including the addition of expressions, use of multiple confidence bands per label, autosizing to viewport, and uses modern tidyverse syntax. Refer to vignette("forestplot") for comprehensive details.

Usage

forestplot(...)

## S3 method for class 'data.frame'
forestplot(x, mean, lower, upper, labeltext, is.summary, boxsize, ...)

## Default S3 method:
forestplot(
  labeltext,
  mean,
  lower,
  upper,
  align = NULL,
  is.summary = FALSE,
  graph.pos = "right",
  hrzl_lines = NULL,
  clip = c(-Inf, Inf),
  xlab = NULL,
  zero = ifelse(xlog, 1, 0),
  graphwidth = "auto",
  colgap = NULL,
  lineheight = "auto",
  line.margin = NULL,
  col = fpColors(),
  txt_gp = fpTxtGp(),
  xlog = FALSE,
  xticks = NULL,
  xticks.digits = 2,
  grid = FALSE,
  lwd.xaxis = NULL,
  lwd.zero = 1,
  lwd.ci = NULL,
  lty.ci = 1,
  ci.vertices = NULL,
  ci.vertices.height = 0.1,
  boxsize = NULL,
  mar = unit(rep(5, times = 4), "mm"),
  title = NULL,
  legend = NULL,
  legend_args = fpLegend(),
  new_page = getOption("forestplot_new_page", TRUE),
  fn.ci_norm = fpDrawNormalCI,
  fn.ci_sum = fpDrawSummaryCI,
  fn.legend = NULL,
  shapes_gp = fpShapesGp(),
  ...
)

## S3 method for class 'gforge_forestplot'
print(x, ...)

## S3 method for class 'gforge_forestplot'
plot(x, y, ..., new_page = FALSE)

## S3 method for class 'grouped_df'
forestplot(x, labeltext, mean, lower, upper, legend, is.summary, boxsize, ...)

Arguments

Details

This version of forestplot() enhances the standard function in the following ways:

• Adding Expressions: Allows the use of expressions, such as expression(beta).

• Multiple Bands: Enables multiple confidence bands for the same label.

• Autosize: Adapts to the viewport (graph) size.

• Tidyverse syntax: Utilizes convenient dplyr/tidyverse syntax for more flexible data manipulation.

Value

gforge_forestplot object

Multiple bands

Multiple bands (or lines) per variable can be useful for comparing different outcomes. For instance, you may want to compare heart disease-specific survival to overall survival rates for smokers. It can be insightful to overlay two bands for this purpose. Another application could be displaying crude and adjusted estimates as separate bands.

Horizontal lines

The hrzl_lines argument can be set as TRUE or a list with grid::gpar elements.

• TRUE: A line will be added based upon the is.summary rows. If the first line is a summary it

• grid::gpar: The same as above but the lines will be formatted according to the grid::gpar element

• list: The list must either be numbered, i.e. list("2" = gpar(lty = 1)), or have the same length as the NROW(mean) + 1. If the list is numbered the numbers should not exceed the NROW(mean) + 1. The no. 1 row designates the top, i.e. the line above the first row, all other correspond to the row below. Each element in the list needs to be TRUE, NULL, or gpar element. The TRUE defaults to a standard line, the NULL skips a line, while gpar corresponds to the fully customized line. Apart from allowing standard gpar line descriptions, lty, lwd, col, and more you can also specify gpar(columns = c(1:3, 5)) if you for instance want the line to skip a column.

Known Issues

• The x-axis does not completely adhere to the margin.

• Autosizing boxes may not always yield the best visual result; manual adjustment is recommended where possible.

API Changes from rmeta package's forestplot

• xlog: Outputs the axis in log() format, but the input data should be in antilog/exp format.

• col: The corresponding function in this package is fpColors.

Author(s)

Max Gordon, Thomas Lumley

See Also

vignette("forestplot")

Other forestplot functions: fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

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)
)
test_data |>
  forestplot(labeltext = row_names,
             mean = coef,
             lower = low,
             upper = high,
             zero = 1,
             cex  = 2,
             lineheight = "auto",
             xlab = "Lab axis txt") |>
  fp_add_header("Group") |>
  fp_set_style(lines = gpar(col = "darkblue"))

# Print two plots side by side using the grid
# package's layout option for viewports
fp1 <- test_data |>
  forestplot(labeltext = row_names,
             mean = coef,
             lower = low,
             upper = high,
             zero = 1,
             cex  = 2,
             lineheight = "auto",
             title = "Plot 1",
             xlab = "Lab axis txt")
fp2 <- test_data |>
  forestplot(labeltext = row_names,
             mean = coef,
             lower = low,
             upper = high,
             zero = 1,
             cex  = 2,
             lineheight = "auto",
             xlab = "Lab axis txt",
             title = "Plot 2",
             new_page = FALSE)

grid.newpage()
pushViewport(viewport(layout = grid.layout(1, 2)))
pushViewport(viewport(layout.pos.col = 1))
plot(fp1)
popViewport()
pushViewport(viewport(layout.pos.col = 2))
plot(fp2)
popViewport(2)

# An advanced example
library(dplyr)
library(tidyr)
test_data <- data.frame(id = 1:4,
                        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))

# Convert into dplyr formatted data
out_data <- test_data |>
  pivot_longer(cols = everything() & -id) |>
  mutate(group = gsub("(.+)([12])$", "\\2", name),
         name = gsub("(.+)([12])$", "\\1", name)) |>
  pivot_wider() |>
  group_by(id) |>
  mutate(col1 = lapply(id, \(x) ifelse(x < 4,
                                       paste("Category", id),
                                       expression(Category >= 4))),
         col2 = lapply(1:n(), \(i) substitute(expression(bar(x) == val),
                                              list(val = mean(coef) |> round(2)))),
         col2 = if_else(id == 1,
                        rep("ref", n()) |> as.list(),
                        col2)) |>
  group_by(group)

out_data |>
  forestplot(mean = coef,
             lower = low,
             upper = high,
             labeltext = c(col1, col2),
             title = "Cool study",
             zero = c(0.98, 1.02),
             grid = structure(c(2^-.5, 2^.5),
                              gp = gpar(col = "steelblue", lty = 2)
             ),
             boxsize = 0.25,
             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)
             )) |>
  fp_set_style(box = c("royalblue", "gold"),
               line = c("darkblue", "orange"),
               summary = c("darkblue", "red"))

# An example of how the exponential works
data.frame(coef = c(2.45, 0.43),
           low = c(1.5, 0.25),
           high = c(4, 0.75),
           boxsize = c(0.25, 0.25),
           variables = c("Variable A", "Variable B")) |>
  forestplot(labeltext = c(variables, coef),
             mean = coef,
             lower = low,
             upper = high,
             boxsize = boxsize,
             zero = 1,
             xlog = TRUE) |>
  fp_set_style(lines = "red", box = "darkred") |>
  fp_add_header(coef = "HR" |> fp_txt_plain() |> fp_align_center(),
                variables = "Measurements")

# An example using style
forestplot(labeltext = cbind(Author = c("Smith et al", "Smooth et al", "Al et al")),
           mean = cbind(1:3, 1.5:3.5),
           lower = cbind(0:2, 0.5:2.5),
           upper = cbind(4:6, 5.5:7.5),
           is.summary = c(FALSE, FALSE, TRUE),
           vertices = TRUE) |>
  fp_set_style(default = gpar(lineend = "square", linejoin = "mitre", lwd = 3, col = "pink"),
               box = gpar(fill = "black", col = "red"), # only one parameter
               lines = list( # as many parameters as CI
                 gpar(lwd = 10), gpar(lwd = 5),
                 gpar(), gpar(),
                 gpar(lwd = 2), gpar(lwd = 1)
               ),
               summary = list( # as many parameters as band per label
                 gpar(fill = "violet", col = "gray", lwd = 10),
                 gpar(fill = "orange", col = "gray", lwd = 10)
               ))

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

A function for the color elements used in forestplot()

Description

This function encapsulates all the colors that are used in the forestplot function. As there are plenty of color options this function gathers them all in one place.

Usage

fpColors(
  all.elements,
  box = "black",
  lines = "gray",
  summary = "black",
  zero = "lightgray",
  text = "black",
  axes = "black",
  hrz_lines = "black",
  vrtcl_lines = "lightgray"
)

Arguments

Details

Further customization of non-text elements can be performed with fpShapesGp passed as shapes_gp parameter to forestplot. The fpColors function is kept for backwards compatibility.

If you have several values per row in a forestplot you can set a color to a vector where the first value represents the first line/box, second the second line/box etc. The vectors are only valid for the box & lines options.

This function is a copy of the meta.colors function in the rmeta package.

Value

A list with key elements

Author(s)

Max Gordon, Thomas Lumley

See Also

Other forestplot functions: forestplot(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Examples

ask <- par(ask = TRUE)

# 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 = "#990000", box = "#660000", zero = "darkblue"),
  new_page = TRUE
)

par(ask = ask)

Draw standard confidence intervals

Description

A function that is used to draw the different confidence intervals for the non-summary lines. Use the fpDrawNormalCI function as a template if you want to make your own funky line + marker.

Usage

fpDrawNormalCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  y.offset = 0.5,
  clr.line,
  clr.marker,
  lwd,
  lty = 1,
  vertices,
  vertices.height = 0.1,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

fpDrawDiamondCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  y.offset = 0.5,
  clr.line,
  clr.marker,
  lwd,
  lty = 1,
  vertices,
  vertices.height = 0.1,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

fpDrawCircleCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  y.offset = 0.5,
  clr.line,
  clr.marker,
  lwd,
  lty = 1,
  vertices,
  vertices.height = 0.1,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

fpDrawPointCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  y.offset = 0.5,
  clr.line,
  clr.marker,
  lwd,
  lty = 1,
  vertices,
  vertices.height = 0.1,
  pch = 1,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

fpDrawSummaryCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  col,
  y.offset = 0.5,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

fpDrawBarCI(
  lower_limit,
  estimate,
  upper_limit,
  size,
  col,
  y.offset = 0.5,
  shapes_gp = fpShapesGp(),
  shape_coordinates = structure(c(1, 1), max.coords = c(1, 1)),
  ...
)

Arguments

Value

void The function outputs the line using grid compatible functions and does not return anything.

Author(s)

Max Gordon, Thomas Lumley

See Also

Other forestplot functions: forestplot(), fpColors(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Examples

ask <- par(ask = TRUE)

test_data <- data.frame(
  coef1 = c(1, 1.59, 1.3, 1.24),
  coef2 = c(1, 1.7, 1.4, 1.04)
)

test_data$low1 <- test_data$coef1 - 1.96 * c(0, .2, .1, .15)
test_data$high1 <- test_data$coef1 + 1.96 * c(0, .2, .1, .15)

test_data$low2 <- test_data$coef2 - 1.96 * c(0, .1, .15, .2)
test_data$high2 <- test_data$coef2 + 1.96 * c(0, .1, .15, .2)

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

# Change all to diamonds
forestplot(row_names, coef, low, high,
  fn.ci_norm = fpDrawDiamondCI,
  title = "Cool study",
  zero = 1, 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(
    title = "Group",
    pos = list("topright", inset = .1),
    r = unit(.1, "snpc"),
    gp = gpar(col = "#CCCCCC", lwd = 1.5)
  )
)

# Change first to diamonds
forestplot(row_names, coef, low, high,
  fn.ci_norm = c(
    "fpDrawDiamondCI",
    rep("fpDrawNormalCI",
      times = nrow(coef) - 1
    )
  ),
  title = "Cool study",
  zero = 1, 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(
    title = "Group",
    pos = list("topright", inset = .1),
    r = unit(.1, "snpc"),
    gp = gpar(col = "#CCCCCC", lwd = 1.5)
  )
)

# You can also use a list with the actual functions
# as long as it is formatted [[row]][[column]]
# Note: if you have a non-square input then
# the software will reformat [[col]][[row]]
# to [[row]][[col]]
forestplot(row_names, coef, low, high,
  fn.ci_norm = list(
    list(fpDrawDiamondCI, fpDrawCircleCI),
    list(fpDrawNormalCI, fpDrawNormalCI),
    list(fpDrawNormalCI, fpDrawCircleCI),
    list(fpDrawNormalCI, fpDrawNormalCI)
  ),
  title = "Cool study",
  zero = 1, 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(
    title = "Group",
    pos = list("topright", inset = .1),
    r = unit(.1, "snpc"),
    gp = gpar(col = "#CCCCCC", lwd = 1.5)
  )
)

par(ask = ask)

A function for the legend used in forestplot()

Description

This function encapsulates all the legend options that are used in the forestplot function. This is in order to limit the crowding among the arguments for the forestplot call.

Usage

fpLegend(
  pos = "top",
  gp = NULL,
  r = unit(0, "snpc"),
  padding = unit(ifelse(!is.null(gp), 3, 0), "mm"),
  title = NULL
)

Arguments

Value

list Returns a list with all the elements

See Also

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

A function for graphical parameters of the shapes used in forestplot()

Description

This function encapsulates all the non-text elements that are used in the forestplot() function. As there are plenty of shapes options this function gathers them all in one place.

Usage

fpShapesGp(
  default = NULL,
  box = NULL,
  lines = NULL,
  vertices = NULL,
  summary = NULL,
  zero = NULL,
  axes = NULL,
  hrz_lines = NULL,
  vrtcl_lines = NULL,
  grid = NULL
)

Arguments

Details

This function obsoletes fpColors().

If some, but not all parameters of a shape (e.g. box) are specified in gpar() such as setting lwd but not line color, the unspecified parameters default to the ones specified in default, then, default to legacy parameters of forestplot such as col.

Parameters box, lines, vertices, summary may be set as list containing several gpars. The length of the list must either be equal to the number of bands per label or to the number of bands multiplied by the number of labels, allowing specification of different styles for different parts of the forest plot.

The parameter grid can either be a single gpar or a list of gpars with as many elements as there are lines in the grid (as set by the xticks or grid arguments of forestplot)

Parameters zero, axes, hrz_lines must either be NULL or gpar but cannot be lists of gpars.

Value

list A list with the elements:

• default: the gpar for default attributes

• box: the gpar or list of gpars of the box/marker

• lines: the gpar or list of gpars of the lines

• vertices: the gpar or list of gpars of the vertices

• summary: the gpar or list of gpars of the summary

• zero: the gpar of the zero vertical line

• axes: the gpar of the x-axis

• hrz_lines: the gpar of the horizontal lines

• grid: the gpar or list of gpars of the grid lines

Author(s)

Andre GILLIBERT

See Also

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Examples

ask <- par(ask = TRUE)

# An example of how fpShapesGp works

styles <- fpShapesGp(
  default = gpar(col = "pink", lwd = 2, lineend = "square", linejoin = "mitre"),
  grid = list(
    gpar(col = "blue"),
    gpar(col = "black"),
    gpar(col = "blue")
  ),
  box = list(
    gpar(fill = "black"),
    gpar(fill = "blue"),
    gpar(fill = "black"),
    gpar(fill = "blue")
  ),
  lines = gpar(lty = "dashed"),
  vertices = gpar(lwd = 5, col = "red")
)

forestplot(
  labeltext = c("Author1", "Author2", "Author3", "Author4"),
  grid = c(1, 3, 5),
  mean = 1:4, lower = 0:3, upper = 2:5,
  shapes_gp = styles
)

par(ask = ask)

Get font settings for forestplot

Description

This function generates all the gpar() elements for the different text elements within the graph. Elements not specified inherit their default settings from the label argument.

Usage

fpTxtGp(label, summary, xlab, title, ticks, legend, legend.title, cex = 1)

Arguments

Value

A list of the fpTxtGp class

List arguments for label/summary

You can provide a list of elements for the label and summary in order to specify separate elements. If you provide a list in one dimension the gpar elements are assumed to follow the columns. If you provide a list of 2 dimensions the structure assumes is list[[row]][[column]] and the number of elements should correspond to the number of labels for the label argument, i.e. without the rows marked as summary elements. The same goes for summary arguments.

Examples

fpTxtGp(label = gpar(fontfamily = "HersheySerif"))

Adds a line to the graph

Description

Adds a line to the graph, defaults to horizontal. Lines with prefix v_ will be vertical, no prefix or h_ will be horizontal. If argument is TRUE or just empty: A line will be added based upon the is.summary rows. If the first line is a summary it will choose the last non-summary row.

Usage

fp_add_lines(x, ...)

Arguments

Details

If you provide the argument as a number it will add the line to that particular line. 1 corresponds to the top row and the max row is num_rows + 1. If the argument is TRUE it will default to a standard line. A string will default to the color of that string. If you provide a grid::gpar element it will style the line according to the ⁠gpar object⁠. Apart from allowing standard gpar line descriptions, lty, lwd, col, and more you can also specify gpar(columns = c(1:3, 5)) if you for instance want the line to skip a column.

If you want to add mix vertical and horizontal lines you can prefix the lines with h_ and v_, e.g. v_2 for the second column.

Value

The foresplot object with the styles

See Also

Other graph modifiers: fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_decorate_graph(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Examples

base_data <- tibble::tibble(mean  = c(0.578, 0.165, 0.246, 0.700, 0.348, 0.139, 1.017),
                            lower = c(0.372, 0.018, 0.072, 0.333, 0.083, 0.016, 0.365),
                            upper = c(0.898, 1.517, 0.833, 1.474, 1.455, 1.209, 2.831),
                            study = c("Auckland", "Block", "Doran", "Gamsu",
                                      "Morrison", "Papageorgiou", "Tauesch"),
                            deaths_steroid = c("36", "1", "4", "14", "3", "1", "8"),
                            deaths_placebo = c("60", "5", "11", "20", "7", "7", "10"),
                            OR = c("0.58", "0.16", "0.25", "0.70", "0.35", "0.14", "1.02"))

base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_set_style(box = "royalblue",
               line = "darkblue") |>
  fp_add_lines("steelblue")


base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_set_style(box = "royalblue",
               line = "darkblue") |>
  # Add top line
  fp_add_lines(h_3 = "darkred") |>
  # Add surrounding box with fancy syntax
  fp_add_lines(h_5 = gpar(col = "steelblue", columns = 1:4, lty = 2),
               h_7 = gpar(col = "steelblue", columns = 1:4, lty = 2),
               v_1 = gpar(col = "steelblue", rows = 5:6, lty = 3, lty = 2),
               v_5 = gpar(col = "steelblue", rows = 5:6, lty = 3, lty = 2))

Decorate the graph

Description

Decorate the graph

Usage

fp_decorate_graph(
  x,
  box = NULL,
  right_bottom_txt = NULL,
  left_bottom_txt = NULL,
  right_top_txt = NULL,
  left_top_txt = NULL,
  grid = NULL,
  graph.pos = NULL
)

Arguments

Value

The forestplot object with the extended decoration

See Also

Other graph modifiers: fp_add_lines(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_insert_row(), fp_set_style(), fp_set_zebra_style()

Examples

base_data <- tibble::tibble(mean  = c(0.578, 0.165, 0.246, 0.700, 0.348, 0.139, 1.017),
                            lower = c(0.372, 0.018, 0.072, 0.333, 0.083, 0.016, 0.365),
                            upper = c(0.898, 1.517, 0.833, 1.474, 1.455, 1.209, 2.831),
                            study = c("Auckland", "Block", "Doran", "Gamsu",
                                      "Morrison", "Papageorgiou", "Tauesch"),
                            deaths_steroid = c("36", "1", "4", "14", "3", "1", "8"),
                            deaths_placebo = c("60", "5", "11", "20", "7", "7", "10"),
                            OR = c("0.58", "0.16", "0.25", "0.70", "0.35", "0.14", "1.02"))

base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_set_style(box = "royalblue",
               line = "darkblue",
               summary = gpar(fill = "royalblue", clr = "black"),
               txt_gp = fpTxtGp(label = gpar(fontfamily = "mono"))) |>
  fp_decorate_graph(box = "lightgray",
                    right_bottom_txt = fp_txt_gp("RB", gp = gpar(cex = .5)),
                    left_bottom_txt = fp_txt_gp("LB", gp = gpar(cex = .5)),
                    right_top_txt = "RT",
                    left_top_txt = "LT")

Insert/append rows into forestplot

Description

These functions are used for inserting or appending a row into a forestplot object. Can be used for inputting multiple rows. Just make sure that all elements are of equal length.

Usage

fp_insert_row(
  x,
  ...,
  mean = NULL,
  lower = NULL,
  upper = NULL,
  position = 1,
  is.summary = FALSE,
  boxsize = NA
)

fp_add_header(x, ..., position = 1, is.summary = TRUE)

fp_append_row(x, ..., position = "last", is.summary = FALSE)

Arguments

Value

The foresplot object with the added rows

See Also

Other graph modifiers: fp_add_lines(), fp_decorate_graph(), fp_set_style(), fp_set_zebra_style()

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_set_style(), fp_set_zebra_style()

Examples

base_data <- tibble::tibble(mean  = c(0.578, 0.165, 0.246, 0.700, 0.348, 0.139, 1.017),
                            lower = c(0.372, 0.018, 0.072, 0.333, 0.083, 0.016, 0.365),
                            upper = c(0.898, 1.517, 0.833, 1.474, 1.455, 1.209, 2.831),
                            study = c("Auckland", "Block", "Doran", "Gamsu",
                                      "Morrison", "Papageorgiou", "Tauesch"),
                            deaths_steroid = c("36", "1", "4", "14", "3", "1", "8"),
                            deaths_placebo = c("60", "5", "11", "20", "7", "7", "10"),
                            OR = c("0.58", "0.16", "0.25", "0.70", "0.35", "0.14", "1.02"))

base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_append_row(mean  = 0.531,
                lower = 0.386,
                upper = 0.731,
                study = "Summary",
                OR = "0.53",
                is.summary = TRUE)

Set the style of the graph

Description

Sets the output style associated with the foresplot

Usage

fp_set_style(
  x,
  default = NULL,
  box = NULL,
  lines = NULL,
  vertices = NULL,
  summary = NULL,
  zero = NULL,
  axes = NULL,
  hrz_lines = NULL,
  grid = NULL,
  txt_gp = NULL,
  align = NULL
)

Arguments

Value

The foresplot object with the styles

See Also

Other graph modifiers: fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_zebra_style()

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_zebra_style()

Examples

base_data <- tibble::tibble(mean  = c(0.578, 0.165, 0.246, 0.700, 0.348, 0.139, 1.017),
                            lower = c(0.372, 0.018, 0.072, 0.333, 0.083, 0.016, 0.365),
                            upper = c(0.898, 1.517, 0.833, 1.474, 1.455, 1.209, 2.831),
                            study = c("Auckland", "Block", "Doran", "Gamsu",
                                      "Morrison", "Papageorgiou", "Tauesch"),
                            deaths_steroid = c("36", "1", "4", "14", "3", "1", "8"),
                            deaths_placebo = c("60", "5", "11", "20", "7", "7", "10"),
                            OR = c("0.58", "0.16", "0.25", "0.70", "0.35", "0.14", "1.02"))

base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_set_style(box = "royalblue",
               line = "darkblue",
               summary = gpar(fill = "royalblue", clr = "black"),
               txt_gp = fpTxtGp(label = gpar(fontfamily = "mono")))

Decorate the plot with a zebra pattern

Description

Decorate the plot with a zebra pattern

Usage

fp_set_zebra_style(x, ..., ignore_subheaders = FALSE)

Arguments

Value

The forestplot object with the zebra style

See Also

Other graph modifiers: fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style()

Other forestplot functions: forestplot(), fpColors(), fpDrawNormalCI(), fpLegend(), fpShapesGp(), fp_add_lines(), fp_decorate_graph(), fp_insert_row(), fp_set_style()

Examples

base_data <- tibble::tibble(mean  = c(0.578, 0.165, 0.246, 0.700, 0.348, 0.139, 1.017),
                            lower = c(0.372, 0.018, 0.072, 0.333, 0.083, 0.016, 0.365),
                            upper = c(0.898, 1.517, 0.833, 1.474, 1.455, 1.209, 2.831),
                            study = c("Auckland", "Block", "Doran", "Gamsu",
                                      "Morrison", "Papageorgiou", "Tauesch"),
                            deaths_steroid = c("36", "1", "4", "14", "3", "1", "8"),
                            deaths_placebo = c("60", "5", "11", "20", "7", "7", "10"),
                            OR = c("0.58", "0.16", "0.25", "0.70", "0.35", "0.14", "1.02"))

base_data |>
  forestplot(labeltext = c(study, deaths_steroid, deaths_placebo, OR),
             clip = c(0.1, 2.5),
             xlog = TRUE) |>
  fp_add_header(study = c("", "Study"),
                deaths_steroid = c("Deaths", "(steroid)"),
                deaths_placebo = c("Deaths", "(placebo)"),
                OR = c("", "OR")) |>
  fp_set_style(box = "royalblue",
               line = "darkblue",
               summary = gpar(fill = "royalblue", clr = "black")) |>
  fp_set_zebra_style("#EFEFEF")

Text styling

Description

This is a collection of functions to allow styling of text

Usage

fp_txt_italic(txt)

fp_txt_bold(txt)

fp_txt_plain(txt)

fp_txt_gp(txt, gp)

fp_align_left(txt)

fp_align_center(txt)

fp_align_right(txt)

Arguments

Value

A list of txt with style attributes

Examples

fp_txt_italic("Italic text")

Ticks for plot axis

Description

Gets the ticks in a formatted version. This is since I'm not always that fond of just pretty(1:10/5). In exponential form the ticks are determined from the 2-base, meaning that you get an intuitive feeling for when the value is doubled.

Usage

getTicks(low, high = low, clip = c(-Inf, Inf), exp = FALSE, digits = 0)

Arguments

Details

This function is far from perfect and I recommend specifying yourself the ticks that you want.

Value

vector Returns a vector with the ticks

Examples

test_data <- data.frame(
  coef = c(2, 0.5),
  low = c(1.5, 0.05),
  high = c(3, 0.75),
  boxsize = c(0.5, 0.5)
)

# Exponential form where the exponent base i 2 for easier understanding
getTicks(
  low = test_data$low,
  high = test_data$high,
  clip = c(-Inf, Inf),
  exp = TRUE
)

# Non exponential form with using pretty
getTicks(
  low = test_data$low,
  high = test_data$high,
  clip = c(-Inf, Inf),
  exp = FALSE
)


# A very simple example
getTicks(1:5 * 2.33,
  exp = FALSE
)

# A slightly more advanced exponential version
getTicks(1:10 * .33,
  digits = 2,
  exp = TRUE
)

Gets the height for an x-axis object

Description

A function that gets the height of an xaxisGrob. It is for some reason not included by default in the grid-package.

Usage

## S3 method for class 'xaxis'
heightDetails(x)

Arguments

Value

grid::unit A unit object

Examples

library(grid)
grid.newpage()
xg <- xaxisGrob(c(1:3))
convertY(grobHeight(xg), "lines")

Construct default parameters from arguments that may include missing arguments

Description

Construct default parameters from arguments that may include missing arguments

Usage

prDefaultGp(col, lwd, lty)

Arguments

Value

a gpar object containing these three attributes

Converts a 2D or 3D array to mean, lower, upper

Description

Converts a 2D or 3D array to mean, lower, upper

Usage

prFpConvertMultidimArray(x)

Arguments

Value

list(mean = mean, lower = lower, upper = upper)

Draws a straight line

Description

If the line is outside the boundaries the line is clipped with an arrow at the limit indicating that it continues. If the lower limit is not below the upper limit the line is not drawn.

Usage

prFpDrawLine(
  lower_limit,
  upper_limit,
  clr.line,
  lwd,
  lty,
  y.offset,
  vertices,
  vertices.height = 0.1,
  line_gp,
  vertices_gp
)

Arguments

Value

void

Get the label

Description

A function used for fetching the text or expression from the supplied labeltext.

Usage

prFpFetchRowLabel(label_type, labeltext, i, j)

Arguments

Value

An expression or a text

Finds the widest grob in the current list of grobs

Description

Finds the widest grob in the current list of grobs

Usage

prFpFindWidestGrob(grob.list, return_unit = "mm")

Arguments

Value

grid::unit Returns the width unit for the widest grob

Get a function list

Description

This function helps the forestplot to deal with multiple drawing functions for the confidence intervals.

Usage

prFpGetConfintFnList(fn, no_rows, no_depth, missing_rows, is.summary, summary)

Arguments

Value

list The function returns a list that has the format [row][col] where each element contains the function that you need to call using the as.call and eval functions: eval(as.call(list(fn[[row]][[col]], arg_1 = 1, arg_2 = 2)))

Get the main forestplot

Description

The layout makes space for a legend if needed

Usage

prFpGetLayoutVP(lineheight, labels, legend_layout = NULL)

Arguments

Value

viewport Returns the viewport needed

Converts legend position to a standard position

Description

Used for the forestplot legend box.

Usage

prFpGetLegendBoxPosition(pos)

Arguments

Value

list Returns the pos list with the correct x/y/adjust values

Prepares the legend marker function

Description

Prepares the legend marker function

Usage

prFpPrepareLegendMarker(fn.legend, col_no, row_no, fn.ci_norm)

Arguments

Value

list

Plots the labels

Description

This is a helper function to the forestplot function.

Usage

prFpPrintLabels(labels, nc, nr, graph.pos)

Arguments

Value

void

Validate the forestplot label list

Description

Checks that all list elements have equal length, i.e. there is a m x n relation

Usage

prFpValidateLabelList(labelList)

Arguments

Value

boolean TRUE or FALSE

Gets the x-axis range

Description

If the borders are smaller than the upper/lower limits then clip the graph. The line will have arrows indicating that it continues beyond the graph The zero bar has to be on the chart though!

Usage

prFpXrange(upper, lower, clip, zero, xticks, xlog)

Arguments

Value

vector Contains a min and max value

Gets the forestplot labels

Description

A function that gets all the labels

Usage

prGetLabelsList(labels, align, is.summary, txt_gp, col)

Arguments

Value

list A list with attr(labels, "no_cols") where each element contains a list of attr(labels, "no_rows") elements with attributes width/height for each element and max_width/max_height for the total

A function to extract graphical parameters from a fpShapesGp object

Description

A function to extract graphical parameters from a fpShapesGp object

Usage

prGetShapeGp(
  shapes_gp,
  coords,
  object,
  default = grid::gpar(),
  nodefault = FALSE
)

Arguments

Value

An object of class gpar

Author(s)

Andre GILLIBERT

Just a simple access to the gp$cex parameter

Description

Just a simple access to the gp$cex parameter

Usage

prGetTextGrobCex(x)

Arguments

Value

numeric The cex value, 1 if no cex was present

Merges two gpar elements

Description

The second elements overrides any conflicting elements within the first

Usage

prGparMerge(l1, l2)

Arguments

Value

Returns a gpar element

Adds a title to the plot

Description

Adds the title and generates a new main viewport below the title

Usage

prGridPlotTitle(title, gp, space_below)

Arguments

Value

NULL The function does not return a value

An alternative to rep()

Description

The rep() doesn't work with length.out when lists are supposed to be their own elements

Usage

prListRep(x, length.out)

Arguments

Value

list

A function to merge two sets of graphical parameters

Description

A function to merge two sets of graphical parameters

Usage

prMergeGp(weak = gpar(), strong = gpar())

Arguments

Value

A gpar merging attributes of both weak and strong

Populate a list corresponding to matrix specs

Description

This function helps the forestplot to deal with different arguments for the confidence intervals.

Usage

prPopulateList(elmnt, no_rows, no_depth, missing_rows, is.summary, summary)

Arguments

Value

list The function returns a list that has the format [row][col] where each element contains the corresponding element

Pushes viewport with margins

Description

A grid.layout object is used to generate the margins. A second viewport selecting the mid-row/col is used to create the effect of margins

Usage

prPushMarginViewport(bottom, left, top, right, name = NULL)

Arguments

Value

void

Prepares graph position

Description

Prepares the graph position so that it matches the label size

Usage

prepAlign(align, graph.pos, nc)

Arguments

Value

Returns vector of ⁠"l", "c", "r"⁠ values

Prepares graph position

Description

Prepares the graph position so that it matches the label size

Usage

prepGraphPositions(graph.pos, nc)

Arguments

Value

Returns number indicating the graph position

Convert margins to viewport npc margins

Description

Convert margins to viewport npc margins

Usage

prepGridMargins(mar)

Arguments

Value

Returns a list with bottom, left, top, and right as unit("npc")

Prepares label text

Description

Prepares an object that contains the number of columns and rows

Usage

prepLabelText(labeltext, nr)

## S3 method for class 'forestplot_labeltext'
x[i, j, ...]

Arguments

Value

Returns a forestplot_labeltext object with attributes:

• no_cols

• no_rows

• widthcolumn

• label_type

Functions

• [: Pick the value that corresponds to the row and column. Returns expression, call, or text.

Prepares the lines for the plot

Description

Prepares the lines for the plot

Usage

prepLines(lines, is.summary, number_of_rows, number_of_columns, col, shapes_gp)

Arguments

Safely loads package

Description

Stops if the package doesn't exist

Usage

safeLoadPackage(package)

Arguments