diff --git a/DESCRIPTION b/DESCRIPTION index 72fe494..5b0a52c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,7 +11,7 @@ Description: This package uses patchwork to overlay forest plots created in License: MIT + file LICENSE Encoding: UTF-8 LazyData: true -RoxygenNote: 7.1.1 +RoxygenNote: 7.1.2 Imports: dplyr, ggplot2, @@ -34,5 +34,7 @@ Imports: tidyr Suggests: knitr, - rmarkdown + rmarkdown, + readxl VignetteBuilder: knitr +Roxygen: list(markdown = TRUE) diff --git a/R/forester.R b/R/forester.R index f52297a..9f05564 100644 --- a/R/forester.R +++ b/R/forester.R @@ -1,27 +1,30 @@ #' Create a forest plot column in a table #' -#' Creates an png image with the forest plot column inserted in the supplied data frame. +#' Creates a forest plot overlaid on a table. #' #' @param left_side_data Data frame (required). The information to be displayed to the left of the forest plot. #' @param estimate Vector. The point estimates to be displayed in the forest plot. #' @param ci_low Vector. The lower confidence bounds. #' @param ci_high Vector. The upper confidence bounds. +#' @param ci_sep String. What should separate the low and high confidence bounds? Default " to ". #' @param right_side_data Data frame (optional). Information to be displayed on the right side of the table. If not supplied, an Estimate column is generated automatically. #' @param estimate_precision Integer. The number of decimal places on the estimate (default 1) #' @param ggplot_width Integer. The width of forest plot in characters (default 30) #' @param null_line_at Numeric. Default 0. Change to 1 if using relative measures such as OR, RR. -#' @param file_path String. Where to save the image, default "forestable_plot.png" in the current working directory. +#' @param file_path String. Where to save the image, default file.path(tempdir(), "forester_plot.png"). #' @param dpi Numeric. The image resolution in dpi, default 600 -#' @param display Logical. Show the table in RStudio viewer? Default TRUE. If you're using forester inside of RMarkdown, change to false and display the generated images using standard markdown syntax (See file_path). -#' @param blank_na Logical. Should missing values in the left side table be displayed as blank? Default TRUE, if FALSE, NA values will be shown +#' @param display Logical. Should the file be opened? Default TRUE. #' @param font_family String. The font to use for the ggplot and table. Default "mono". #' @param estimate_col_name String. The name for the generated estimate column. Default "Estimate" -#' @param stripe_colour Hex String. Colour to use for the table stripes, default "#eff3f2" -#' @param x_scale_linear Logical. Default TRUE, change to FALSE for log scale +#' @param stripe_colour Hex String. Colour to use for the table stripes, default "#eff3f2". +#' @param background_colour Hex String or Colour Name. The colour of the background, default "white". +#' @param x_scale_linear Logical. Default TRUE, change to FALSE for a log scale. #' @param xlim Vector. Manually specify limits for the x axis as a vector length 2, i.e. c(low, high) #' @param xbreaks Vector. X axis breaks to label. Specify limits in xlim if using this option. #' @param nudge_x Numeric. Nudge the alignment horizontally. Default 1. Higher values make the entire plot wider and consequently space out the elements of the figure. #' @param nudge_y Numeric. Allows small changes to the vertical alignment of the forest plot points. 1 unit is approximately the height of 1 row. +#' @param nudge_height Numeric. Adjust the overall height of the plot output. Default is 0. +#' @param nudge_width Numeric. Adjust the overall width of the plot output. Default is 0. #' @param arrows Logical. Should there be arrows displayed below the ggplot? Default FALSE. Specify xlim if using arrows. #' @param arrow_labels String Vector, length 2. Labels for the arrows. Set arrows to TRUE or this will have no effect. #' @param add_plot A ggplot object to add to the right side of the table. To align correctly with rows, 1 unit is the height of a row and y = 0 for the center of the bottom row. @@ -30,7 +33,8 @@ #' @param point_sizes Vector. Length should be equal to 1 or nrow(left_side_data). The sizes of the points in the center plot, where 3.25 is the default. #' @param point_shapes Vector. Length should be equal to 1 or nrow(left_side_data). The shapes of the points in the center plot, where 16 (a filled circle) is the default. #' @param center_ggplot A ggplot object to use instead of the central plot. -#' @param render_as What output format should be used? Default is "image", the only other option currently is "rmarkdown". +#' @param lower_header_row Logical. If TRUE, drops the header down one row (In the table rather than above it, like the default value (FALSE)) +#' @param render_as String or Function. What output format should be used? Option is passed to ggplot2::ggsave() as the argument "device". Either pass a device function (e.g. png) or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only). #' #' @return image #' @importFrom rlang .data @@ -38,15 +42,17 @@ #' @export #' #' @examples +#' forester <- function(left_side_data, estimate, ci_low, ci_high, + ci_sep = " to ", right_side_data = NULL, estimate_precision = 1, ggplot_width = 30, null_line_at = 0, - file_path = here::here("forester_plot.png"), + file_path = file.path(tempdir(), paste0("forester_plot.", render_as)), dpi = 600, display = TRUE, font_family = "mono", @@ -58,6 +64,8 @@ forester <- function(left_side_data, xbreaks = NULL, nudge_y = 0, nudge_x = 1, + nudge_height = 0, + nudge_width = 0, arrows = FALSE, arrow_labels = c("Lower", "Higher"), add_plot = NULL, @@ -67,7 +75,7 @@ forester <- function(left_side_data, point_shapes = 16, center_ggplot = NULL, lower_header_row = FALSE, - render_as = "image"){ + render_as = "png"){ if(lower_header_row == FALSE){ theme <- gridExtra::ttheme_minimal(core=list( @@ -95,7 +103,7 @@ forester <- function(left_side_data, ci_high = ci_high) if(lower_header_row){ - gdata <- add_row(gdata, .before = 1) + gdata <- tibble::add_row(gdata, .before = 1) } if(is.null(right_side_data)){ @@ -109,7 +117,7 @@ forester <- function(left_side_data, # pretty formatting for confidence intervals right_side_data <- data.frame(Estimate = ifelse(tdata$estimate == " ", " ", paste0(tdata$estimate, " (", tdata$ci_low, - " to ", tdata$ci_high, ")"))) + ci_sep, tdata$ci_high, ")"))) colnames(right_side_data) <- estimate_col_name @@ -269,10 +277,10 @@ forester <- function(left_side_data, la <- sum(oob_arrows$ci_low < oob_arrows$x_low, na.rm = T) > 0 if(ra){ - right_arrows <- dplyr::select(dplyr::filter(oob_arrows, ci_high > x_high), start = estimate, end = x_high, y = row_num) + right_arrows <- dplyr::select(dplyr::filter(oob_arrows, ci_high > .data$x_high), start = estimate, end = .data$x_high, y = .data$row_num) } if(la){ - left_arrows <- dplyr::select(dplyr::filter(oob_arrows, ci_low < x_low), start = estimate, end = x_low, y = row_num) + left_arrows <- dplyr::select(dplyr::filter(oob_arrows, ci_low < .data$x_low), start = estimate, end = .data$x_low, y = .data$row_num) } if(ra && !la){ @@ -525,17 +533,18 @@ forester <- function(left_side_data, } ######### save the plot as a png, then display it with magick ################ - if(render_as == "image"){ - ggplot2::ggsave(dpi = dpi, - height = png_height, - width = png_width, units = "in", - filename = file_path) + if(!(render_as == "rmarkdown")){ + ggplot2::ggsave( + dpi = dpi, + height = png_height + nudge_height, + width = png_width + nudge_width, + units = "in", + filename = file_path, + device = render_as + ) if(display == TRUE){ - magick::image_resize(magick::image_read(file_path), - paste0(grDevices::dev.size("px")[1], - "x", - grDevices::dev.size("px")[2])) + system(paste0('open "', file_path, '"')) } }else{ final diff --git a/README.Rmd b/README.Rmd index 79ec3ac..25868dc 100644 --- a/README.Rmd +++ b/README.Rmd @@ -34,7 +34,7 @@ Suppose we wish to replicate the following figure published in the NEJM [1]: ![](man/figures/target_figure.jpg) -forester simply requires the left side of the table (in this case, three columns with Subgroups and counts for each of two groups) and vectors which contain the point estimates and confidence intervals. +Forester simply requires the left side of the table (in this case, three columns with Subgroups and counts for each of two groups) and vectors which contain the point estimates and confidence intervals. ```{r example} library(forester) @@ -88,7 +88,7 @@ forester(left_side_data = table[,1], ## Display Options -By default, forester will both display the plot in the RStudio viewer (`display = TRUE`) and save a high quality version to the current directory (`file_path = here::here("forester_plot.png")`) at a resolution controllable by `dpi`. When making a rmarkdown document (such as this one), these options should be overwritten as required. You can display the images created by forester using standard RMarkdown syntax (i.e. `![](path)`). +Using the default options will result in a png image being written to your temporary folder and opened with your default program for viewing images. If you don't want to open the file, specify `display = FALSE`. `ggplot2::ggsave` is used to save the file, so any format supported there will work in theory (though not necessarily in practice). Use the `render_as` option to change the output file format - for example, `render_as = "pdf"` will render the plot in pdf form. If you want to display the plot inline in an rmarkdown document, use `render_as = "rmarkdown` (this feature is still experimental). You can alternatively generate the plots as images and then use normal markdown syntax to include them in your document (i.e. `![]()`). Be sure to change the `file_path` option to save the plot somewhere permanent if you are using this option or would otherwise like your plots to be saved. ## Font Families diff --git a/README.md b/README.md index 213b965..88b6032 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Suppose we wish to replicate the following figure published in the NEJM ![](man/figures/target_figure.jpg) -forester simply requires the left side of the table (in this case, three +Forester simply requires the left side of the table (in this case, three columns with Subgroups and counts for each of two groups) and vectors which contain the point estimates and confidence intervals. @@ -83,13 +83,20 @@ forester(left_side_data = table[,1], ## Display Options -By default, forester will both display the plot in the RStudio viewer -(`display = TRUE`) and save a high quality version to the current -directory (`file_path = here::here("forester_plot.png")`) at a -resolution controllable by `dpi`. When making a rmarkdown document (such -as this one), these options should be overwritten as required. You can -display the images created by forester using standard RMarkdown syntax -(i.e. `![](path)`). +Using the default options will result in a png image being written to +your temporary folder and opened with your default program for viewing +images. If you don’t want to open the file, specify `display = FALSE`. +`ggplot2::ggsave` is used to save the file, so any format supported +there will work in theory (though not necessarily in practice). Use the +`render_as` option to change the output file format - for example, +`render_as = "pdf"` will render the plot in pdf form. If you want to +display the plot inline in an rmarkdown document, use +`render_as = "rmarkdown` (this feature is still experimental). You can +alternatively generate the plots as images and then use normal markdown +syntax to include them in your document (i.e. `![]()`). Be sure to +change the `file_path` option to save the plot somewhere permanent if +you are using this option or would otherwise like your plots to be +saved. ## Font Families @@ -103,6 +110,7 @@ library(extrafont) #> Registering fonts with R loadfonts(device = "win") +#> Roboto Condensed already registered with windowsFonts(). windowsFonts("Fira Sans" = windowsFont("Fira Sans")) forester(left_side_data = table[,1:3], @@ -271,6 +279,7 @@ of the plot (units are relative to the width of the table). ``` r library(ggplot2) library(tibble) +#> Warning: package 'tibble' was built under R version 4.1.1 ex_plot <- ggplot(tibble(x = rep(1:7, each = 15), y = rep(0:14, times = 7)), aes(x = x, y = y)) + geom_point() diff --git a/forester_plot.png b/forester_plot.png deleted file mode 100644 index 77ec355..0000000 Binary files a/forester_plot.png and /dev/null differ diff --git a/man/figures/add_dots.png b/man/figures/add_dots.png index 0dd6763..1cd2bf8 100644 Binary files a/man/figures/add_dots.png and b/man/figures/add_dots.png differ diff --git a/man/figures/fewer_cols.png b/man/figures/fewer_cols.png index f0251da..3b7bf11 100644 Binary files a/man/figures/fewer_cols.png and b/man/figures/fewer_cols.png differ diff --git a/man/figures/fewer_rows.png b/man/figures/fewer_rows.png index e3dd8ed..6ad4e57 100644 Binary files a/man/figures/fewer_rows.png and b/man/figures/fewer_rows.png differ diff --git a/man/figures/forester_plot.png b/man/figures/forester_plot.png index 5c7170a..ad4fe0b 100644 Binary files a/man/figures/forester_plot.png and b/man/figures/forester_plot.png differ diff --git a/man/figures/forester_plot_arrows.png b/man/figures/forester_plot_arrows.png index d5b72d4..dffb110 100644 Binary files a/man/figures/forester_plot_arrows.png and b/man/figures/forester_plot_arrows.png differ diff --git a/man/figures/forester_plot_fira.png b/man/figures/forester_plot_fira.png index e504a88..492fdc1 100644 Binary files a/man/figures/forester_plot_fira.png and b/man/figures/forester_plot_fira.png differ diff --git a/man/figures/limit_breaks.png b/man/figures/limit_breaks.png index 3200a8e..74e2f09 100644 Binary files a/man/figures/limit_breaks.png and b/man/figures/limit_breaks.png differ diff --git a/man/figures/more_plot_width.png b/man/figures/more_plot_width.png index 7e43eea..33c1b18 100644 Binary files a/man/figures/more_plot_width.png and b/man/figures/more_plot_width.png differ diff --git a/man/figures/more_precise.png b/man/figures/more_precise.png index d8ae8eb..c1027e9 100644 Binary files a/man/figures/more_precise.png and b/man/figures/more_precise.png differ diff --git a/man/figures/size_shape.png b/man/figures/size_shape.png index 05fc541..d2ce9ab 100644 Binary files a/man/figures/size_shape.png and b/man/figures/size_shape.png differ diff --git a/man/figures/stripe_colour.png b/man/figures/stripe_colour.png index 01e575d..bd29c37 100644 Binary files a/man/figures/stripe_colour.png and b/man/figures/stripe_colour.png differ diff --git a/man/forester.Rd b/man/forester.Rd index ada6ed6..146678b 100644 --- a/man/forester.Rd +++ b/man/forester.Rd @@ -9,11 +9,12 @@ forester( estimate, ci_low, ci_high, + ci_sep = " to ", right_side_data = NULL, estimate_precision = 1, ggplot_width = 30, null_line_at = 0, - file_path = here::here("forester_plot.png"), + file_path = file.path(tempdir(), paste0("forester_plot.", render_as)), dpi = 600, display = TRUE, font_family = "mono", @@ -34,7 +35,7 @@ forester( point_shapes = 16, center_ggplot = NULL, lower_header_row = FALSE, - render_as = "image" + render_as = "png" ) } \arguments{ @@ -46,6 +47,8 @@ forester( \item{ci_high}{Vector. The upper confidence bounds.} +\item{ci_sep}{String. What should separate the low and high confidence bounds? Default " to ".} + \item{right_side_data}{Data frame (optional). Information to be displayed on the right side of the table. If not supplied, an Estimate column is generated automatically.} \item{estimate_precision}{Integer. The number of decimal places on the estimate (default 1)} @@ -54,19 +57,21 @@ forester( \item{null_line_at}{Numeric. Default 0. Change to 1 if using relative measures such as OR, RR.} -\item{file_path}{String. Where to save the image, default "forestable_plot.png" in the current working directory.} +\item{file_path}{String. Where to save the image, default file.path(tempdir(), "forester_plot.png").} \item{dpi}{Numeric. The image resolution in dpi, default 600} -\item{display}{Logical. Show the table in RStudio viewer? Default TRUE. If you're using forester inside of RMarkdown, change to false and display the generated images using standard markdown syntax (See file_path).} +\item{display}{Logical. Should the file be opened? Default TRUE.} \item{font_family}{String. The font to use for the ggplot and table. Default "mono".} \item{estimate_col_name}{String. The name for the generated estimate column. Default "Estimate"} -\item{stripe_colour}{Hex String. Colour to use for the table stripes, default "#eff3f2"} +\item{stripe_colour}{Hex String. Colour to use for the table stripes, default "#eff3f2".} + +\item{background_colour}{Hex String or Colour Name. The colour of the background, default "white".} -\item{x_scale_linear}{Logical. Default TRUE, change to FALSE for log scale} +\item{x_scale_linear}{Logical. Default TRUE, change to FALSE for a log scale.} \item{xlim}{Vector. Manually specify limits for the x axis as a vector length 2, i.e. c(low, high)} @@ -92,9 +97,9 @@ forester( \item{center_ggplot}{A ggplot object to use instead of the central plot.} -\item{render_as}{What output format should be used? Default is "image", the only other option currently is "rmarkdown".} +\item{lower_header_row}{Logical. If TRUE, drops the header down one row (In the table rather than above it, like the default value (FALSE))} -\item{blank_na}{Logical. Should missing values in the left side table be displayed as blank? Default TRUE, if FALSE, NA values will be shown} +\item{render_as}{String or Function. What output format should be used? Option is passed to ggplot2::ggsave() as the argument "device". Either pass a device function (e.g. png) or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only).} } \value{ image @@ -102,3 +107,6 @@ image \description{ Creates an png image with the forest plot column inserted in the supplied data frame. } +\examples{ + +} diff --git a/vignettes/alignment_tests.Rmd b/vignettes/alignment_tests.Rmd index 36679ed..bc56cc4 100644 --- a/vignettes/alignment_tests.Rmd +++ b/vignettes/alignment_tests.Rmd @@ -1,8 +1,10 @@ --- -title: "alignment_tests" -author: "Randy Boyes" -date: "30/03/2021" -output: html_document +title: "Alignment Tests" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Alignment_Tests} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} @@ -13,7 +15,7 @@ The following document exists mainly to check whether alignment works for the su ```{r example} library(forester) -library(tidyverse) +library(purrr) table <- readxl::read_excel(here::here("inst/extdata/example_figure_data.xlsx")) diff --git a/vignettes/mono_10.png b/vignettes/mono_10.png index 9b5a512..7d4491c 100644 Binary files a/vignettes/mono_10.png and b/vignettes/mono_10.png differ diff --git a/vignettes/mono_15.png b/vignettes/mono_15.png index 1f3652a..f6871fe 100644 Binary files a/vignettes/mono_15.png and b/vignettes/mono_15.png differ diff --git a/vignettes/mono_20.png b/vignettes/mono_20.png index 3ba12f9..80d4880 100644 Binary files a/vignettes/mono_20.png and b/vignettes/mono_20.png differ diff --git a/vignettes/mono_25.png b/vignettes/mono_25.png index 77514ac..f5fe3a0 100644 Binary files a/vignettes/mono_25.png and b/vignettes/mono_25.png differ diff --git a/vignettes/mono_30.png b/vignettes/mono_30.png index 0fc0a1a..6e0f669 100644 Binary files a/vignettes/mono_30.png and b/vignettes/mono_30.png differ diff --git a/vignettes/mono_5.png b/vignettes/mono_5.png index cdb9bcd..894b7eb 100644 Binary files a/vignettes/mono_5.png and b/vignettes/mono_5.png differ diff --git a/vignettes/sans_10.png b/vignettes/sans_10.png index 77c3097..dcfa5be 100644 Binary files a/vignettes/sans_10.png and b/vignettes/sans_10.png differ diff --git a/vignettes/sans_15.png b/vignettes/sans_15.png index e2e8e6d..6d49eee 100644 Binary files a/vignettes/sans_15.png and b/vignettes/sans_15.png differ diff --git a/vignettes/sans_20.png b/vignettes/sans_20.png index 8f3a14b..3e2fa1b 100644 Binary files a/vignettes/sans_20.png and b/vignettes/sans_20.png differ diff --git a/vignettes/sans_25.png b/vignettes/sans_25.png index f0a8553..c4765e4 100644 Binary files a/vignettes/sans_25.png and b/vignettes/sans_25.png differ diff --git a/vignettes/sans_30.png b/vignettes/sans_30.png index 42b3c2a..8c22830 100644 Binary files a/vignettes/sans_30.png and b/vignettes/sans_30.png differ diff --git a/vignettes/sans_5.png b/vignettes/sans_5.png index 35292a3..014e69c 100644 Binary files a/vignettes/sans_5.png and b/vignettes/sans_5.png differ diff --git a/vignettes/serif_10.png b/vignettes/serif_10.png index b8da692..286320a 100644 Binary files a/vignettes/serif_10.png and b/vignettes/serif_10.png differ diff --git a/vignettes/serif_15.png b/vignettes/serif_15.png index 49f62e0..575bcdb 100644 Binary files a/vignettes/serif_15.png and b/vignettes/serif_15.png differ diff --git a/vignettes/serif_20.png b/vignettes/serif_20.png index de1fc7a..fe9d3e7 100644 Binary files a/vignettes/serif_20.png and b/vignettes/serif_20.png differ diff --git a/vignettes/serif_25.png b/vignettes/serif_25.png index 863ec9e..a9faf59 100644 Binary files a/vignettes/serif_25.png and b/vignettes/serif_25.png differ diff --git a/vignettes/serif_30.png b/vignettes/serif_30.png index 2dddbe1..4cc402f 100644 Binary files a/vignettes/serif_30.png and b/vignettes/serif_30.png differ diff --git a/vignettes/serif_5.png b/vignettes/serif_5.png index 1f16b4e..c165a61 100644 Binary files a/vignettes/serif_5.png and b/vignettes/serif_5.png differ