Type: Package
Title: Create Waterfall Charts using 'ggplot2' Simply
Version: 1.0.0
Author: Hugh Parsonage
Maintainer: Hugh Parsonage <hugh.parsonage+waterfall@gmail.com>
Description: A not uncommon task for quants is to create 'waterfall charts'. There seems to be no simple way to do this in 'ggplot2' currently. This package contains a single function (waterfall) that simply draws a waterfall chart in a 'ggplot2' object. Some flexibility is provided, though often the object created will need to be modified through a theme.
License: MIT + file LICENSE
URL: https://github.com/hughparsonage/waterfalls
Encoding: UTF-8
Imports: ggplot2 (≥ 2.0.0), grDevices
RoxygenNote: 7.2.0
NeedsCompilation: no
Packaged: 2022-11-20 12:14:06 UTC; hughp
Repository: CRAN
Date/Publication: 2022-11-20 12:20:02 UTC

Create waterfall charts

Description

Create waterfall charts

Usage

waterfall(
  .data = NULL,
  values,
  labels,
  rect_text_labels = values,
  rect_text_size = 1,
  rect_text_labels_anchor = "centre",
  put_rect_text_outside_when_value_below = 0.05 * (max(cumsum(values)) -
    min(cumsum(values))),
  calc_total = FALSE,
  total_axis_text = "Total",
  total_rect_text = sum(values),
  total_rect_color = "black",
  total_rect_border_color = "black",
  total_rect_text_color = "white",
  fill_colours = NULL,
  fill_by_sign = TRUE,
  rect_width = 0.7,
  rect_border = "black",
  draw_lines = TRUE,
  lines_anchors = c("right", "left"),
  linetype = "dashed",
  draw_axis.x = "behind",
  theme_text_family = "",
  scale_y_to_waterfall = TRUE,
  print_plot = FALSE,
  ggplot_object_name = "mywaterfall"
)

Arguments

.data

a data.frame containing two columns, one with the values, the other with the labels

values

a numeric vector making up the heights of the rectangles in the waterfall

labels

the labels corresponding to each vector, marked on the x-axis

rect_text_labels

(character) a character vector of the same length as values that are placed on the rectangles

rect_text_size

size of the text in the rectangles

rect_text_labels_anchor

(character) How should rect_text_labels be positioned? In future releases, we might have support for north or south anchors, or for directed positioning (negative down, positive up) etc. For now, only centre is supported.

put_rect_text_outside_when_value_below

(numeric) the text labels accompanying a rectangle of this height will be placed outside the box: below if it's negative; above if it's positive.

calc_total

(logical, default: FALSE) should the final pool of the waterfall be calculated (and placed on the chart)

total_axis_text

(character) the text appearing on the axis underneath the total rectangle

total_rect_text

(character) the text in the middle of the rectangle of the total rectangle

total_rect_color

the color of the final rectangle

total_rect_border_color

the border color of the total rectangle

total_rect_text_color

the color of the final rectangle's label text

fill_colours

Colours to be used to fill the rectangles, in order. Disregarded if fill_by_sign is TRUE (the default).

fill_by_sign

(logical, default: TRUE) should positive and negative values each have the same colour?

rect_width

(numeric) the width of the rectangle, relative to the space between each label factor

rect_border

the border colour around the rectangles. Provide either a single color, that will be used for each rectangle, or one color for each rectangle. Choose NA if no border is desired.

draw_lines

(logical, default: TRUE) should lines be drawn between successive rectangles

lines_anchors

a character vector of length two specifying the horizontal placement of the drawn lines relative to the preceding and successive rectangles, respectively

linetype

the linetype for the draw_lines

draw_axis.x

(character) one of "none", "behind", "front" whether to draw an x.axis line and whether to draw it behind or in front of the rectangles, default is behind

theme_text_family

(character) Passed to the text argument in ggplot2::theme.

scale_y_to_waterfall

(logical, default: TRUE) Should the default range of the y-axis be from the bottom of the lowest pool to the top of the highest? If FALSE, which was the only option before version 0.1.2, the range of the plot is more balanced around the y-axis.

print_plot

(logical) Whether or not the plot should be printed. By default, TRUE, which means it cannot be assigned.

ggplot_object_name

(character) A quoted valid object name to which ggplot layers may be added after the function has run. Ignored if print is FALSE.

Author(s)

Based on grattan_waterfall from the 'grattanCharts' package (https://github.com/HughParsonage/grattanCharts).

Examples

waterfall(values = round(rnorm(5), 1), labels = letters[1:5], calc_total = TRUE)
waterfall(.data = data.frame(category = letters[1:5],
                             value = c(100, -20, 10, 20, 110)), 
          fill_colours = colorRampPalette(c("#1b7cd6", "#d5e6f2"))(5),
          fill_by_sign = FALSE)