Package 'waterfalls'

Title: Create Waterfall Charts using 'ggplot2' Simply
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.
Authors: Hugh Parsonage
Maintainer: Hugh Parsonage <[email protected]>
License: MIT + file LICENSE
Version: 1.1.0
Built: 2024-11-09 02:35:55 UTC
Source: https://github.com/hughparsonage/waterfalls

Help Index

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)