Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

quiet down warnings, readme updated to include new features #21

Merged
merged 1 commit into from
Mar 28, 2021
Merged

quiet down warnings, readme updated to include new features #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions R/forester.R
View file
Open in desktop
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
Open in desktop
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