Skip to content

Commit

Permalink
Merge pull request #21 from rdboyes/dev
Browse files Browse the repository at this point in the history 
quiet down warnings, readme updated to include new features
  • Loading branch information
@rdboyes
rdboyes authored Mar 28, 2021
2 parents 35289f6 + 859b255 commit 7ac4644
Show file tree
Hide file tree
Showing 10 changed files with 247 additions and 88 deletions.
8 changes: 2 additions & 6 deletions R/forester.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,7 @@ forester <- function(left_side_data,
add_plot_width = 1,
add_plot_gap = FALSE,
point_sizes = 3,
point_shapes = 16


){
point_shapes = 16){

theme <- gridExtra::ttheme_minimal(core=list(
fg_params = list(hjust = 0, x = 0.05, fontfamily = font_family),
Expand Down Expand Up @@ -259,7 +256,7 @@ forester <- function(left_side_data,
########## the main figure - this will be overlaid on the table ##############

center <- ggplot2::ggplot() +
ggplot2::geom_point(data = gdata, ggplot2::aes(y = row_num, x = estimate, size = sizes, shape = shape)) +
ggplot2::geom_point(data = gdata, ggplot2::aes(y = row_num, x = estimate, size = sizes, shape = shape), na.rm = TRUE) +
ggplot2::geom_errorbarh(data = gdata, ggplot2::aes(y = row_num,
xmin = ci_low,
xmax = ci_high),
Expand All @@ -279,7 +276,6 @@ forester <- function(left_side_data,
legend.background = ggplot2::element_rect(fill = "transparent"),
legend.box.background = ggplot2::element_rect(fill = "transparent")) +
ggplot2::geom_vline(xintercept = null_line_at, linetype = "dashed") +
ggplot2::scale_x_continuous(labels = scales::number_format(accuracy = 0.1)) +
ggplot2::scale_y_continuous(expand = c(0,0)) +
ggplot2::scale_shape_identity() +
ggplot2::scale_size_identity() +
Expand Down
135 changes: 108 additions & 27 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ knitr::opts_chunk$set(
)
```

# forester
# Forester

<!-- badges: start -->
<!-- badges: end -->
Expand All @@ -28,7 +28,7 @@ This package is currently early in development, and must be installed from this
devtools::install_github("rdboyes/forester")
```

## Example
## Basic Usage

Suppose we wish to replicate the following figure published in the NEJM [1]:

Expand Down Expand Up @@ -62,7 +62,7 @@ forester(left_side_data = table[,1:3],

![](man/figures/forester_plot.png)

forester handles the alignment of the graph and the table automatically, so figures with fewer rows or columns should work by simply passing a smaller data frame to the function:
Forester handles the alignment of the graph and the table automatically, so figures with fewer rows or columns should work by simply passing a smaller data frame to the function:

```{r}
forester(left_side_data = table[1:12,1:3],
Expand All @@ -86,9 +86,13 @@ forester(left_side_data = table[,1],

![](man/figures/fewer_cols.png)

## Additional Fonts
## Display Options

While Courier has a certain appeal, you might want to give your tables a more modern look. However, due to the difficulty of aligning all elements when using them, the use of non-monospaced fonts should be considered experimental at this stage.
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)`).

## Font Families

Pass any font to `font_family` to control the output font. Tested options include `"mono"`, `"sans"`, and `"serif"`. Any font will work, but alignment may not be perfect for untested fonts. Use the provided options `nudge_x` and `nudge_y` to correct alignment issues.

```{r}
library(extrafont)
Expand All @@ -106,53 +110,131 @@ forester(left_side_data = table[,1:3],
```

![](man/figures/forester_plot_fira.png)
Adjusting table properties with different fonts will still work:

## Right Side Data

The option `estimate_precision` can be used to change the number of decimals displayed in the right hand side table. `estimate_col_name` allows you to change the name of the default right side column. If you require more control, pass a dataframe to `right_side_data` to override the right side completely.

```{r}
forester(left_side_data = table[1:12,1:3],
estimate = table$Estimate[1:12],
ci_low = table$`CI low`[1:12],
ci_high = table$`CI high`[1:12],
forester(left_side_data = table[,1],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
font_family = "Fira Sans",
file_path = here::here("man/figures/fewer_rows_fira.png"))
estimate_precision = 3,
estimate_col_name = "Estimate (95% CI)",
file_path = here::here("man/figures/more_precise.png"))
```

![](man/figures/fewer_rows_fira.png)
```{r}
windowsFonts("Times New Roman" = windowsFont("Times New Roman"))
![](man/figures/more_precise.png)

forester(left_side_data = table[1:12,1:3],
estimate = table$Estimate[1:12],
ci_low = table$`CI low`[1:12],
ci_high = table$`CI high`[1:12],
## Plot Width

Change `ggplot_width` from its default value of 30 to adjust the relative amount of space that the figure takes up. `nudge_x` can be used to correct alignment issues if this option causes any.

```{r}
forester(left_side_data = table[,1],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
font_family = "Times New Roman",
file_path = here::here("man/figures/fewer_rows_times.png"))
ggplot_width = 40,
nudge_x = .5,
file_path = here::here("man/figures/more_plot_width.png"))
```

![](man/figures/fewer_rows_times.png)
![](man/figures/more_plot_width.png)

## Adding Arrows (Experimental)
## Limits, Breaks, and the Null Line

Limits and breaks are set automatically, but the defaults can be overwritten using `xlim` (use a vector of length 2, i.e. c(low, high)) and `xbreaks` (use a vector indicating the breaks). `null_line_at` defaults to 0, but can be set to any value. This would be most commonly used to set the `null_line_at = 1.0` for relative measures. `x_scale_linear` defaults to `TRUE` but can be set to `FALSE` if a logarithmic scale is required. If a confidence interval extends outside the range set by `xlim`, it will automatically be indicated using an arrow.

```{r}
forester(left_side_data = table[,1:3],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
file_path = here::here("man/figures/forester_plot_arrows.png"),
file_path = here::here("man/figures/limit_breaks.png"),
font_family = "Fira Sans",
null_line_at = -50,
xlim = c(-100, -25),
xbreaks = c(-100, -75, -50, -25),
xbreaks = c(-100, -75, -50, -25))
```

![](man/figures/limit_breaks.png)

## Table Colour Options

As pointed out [here](https://twitter.com/davidrfeinberg/status/1375417579095924738), the default colour scheme looks a bit retro. Personally, I like the default stripe colour "#eff3f2", but you can change the stripe colour to anything you want :)

```{r}
forester(left_side_data = table[,1:3],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
file_path = here::here("man/figures/stripe_colour.png"),
font_family = "Fira Sans",
stripe_colour = "#ff0000"
)
```

![](man/figures/stripe_colour.png)

## Adding Arrows

Arrows can be added below the plot area (with `arrows = TRUE`) and labelled (with `arrow_labels = c("Left Label", "Right Label")`).

```{r}
forester(left_side_data = table[,1:3],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
file_path = here::here("man/figures/forester_plot_arrows.png"),
font_family = "Fira Sans",
null_line_at = 0,
xlim = c(-100, 25),
xbreaks = c(-100, -75, -50, -25, 0, 25),
arrows = TRUE,
arrow_labels = c("Inclisiran Better", "Placebo Better"))
```

![](man/figures/forester_plot_arrows.png)

## Adding additional ggplot objects (Experimental)
## Point Size and Shape

The size and shape of the points can be controlled using vectors of values passed to `point_sizes` and `point_shapes`.

```{r}
shapes <- rep(16, times = 30)
shapes[1] <- 17
sizes <- rep(3.25, times = 30)
sizes[30] <- 5
forester(left_side_data = table[,1:3],
estimate = table$Estimate,
ci_low = table$`CI low`,
ci_high = table$`CI high`,
display = FALSE,
file_path = here::here("man/figures/size_shape.png"),
font_family = "Fira Sans",
null_line_at = 0,
xlim = c(-100, 25),
xbreaks = c(-100, -75, -50, -25, 0, 25),
arrows = TRUE,
arrow_labels = c("Inclisiran Better", "Placebo Better"),
point_sizes = sizes,
point_shapes = shapes)
```

![](man/figures/size_shape.png)

## Adding Additional ggplot Objects

Custom ggplot objects can be passed to the `forester` function using the parameter `add_plot`. To align the plot with the rows of the table, the vertical center of the bottom row is at y = 0, and each row is one unit tall on the y axis. `add_plot_width` can be set to customize the width of the plot (units are relative to the width of the table).

Expand All @@ -168,7 +250,6 @@ forester(left_side_data = table[1:15,1:3],
ci_low = table$`CI low`[1:15],
ci_high = table$`CI high`[1:15],
display = FALSE,
font_family = "Times New Roman",
add_plot = ex_plot,
file_path = here::here("man/figures/add_dots.png"))
Expand Down
Loading

0 comments on commit 7ac4644

Please sign in to comment.