waterfall_plot#

waterfall_plot(data, x, y, *, measure=None, group=None, color=None, fill=None, size=None, alpha=None, linetype=None, width=None, show_legend=None, relative_tooltips=None, absolute_tooltips=None, sorted_value=None, threshold=None, max_values=None, base=None, calc_total=None, total_title=None, hline=None, hline_ontop=None, connector=None, label=None, label_format=None) → PlotSpec#

A waterfall plot shows the cumulative effect of sequentially introduced positive or negative values.

Parameters:
datadict or Pandas or Polars DataFrame

The data to be displayed.

xstr

Name of a variable.

ystr

Name of a numeric variable.

measurestr

Kind of a calculation. Values in ‘measure’ column could be:

‘absolute’ - the value is shown as is; ‘relative’ - the value is shown as a difference from the previous value; ‘total’ - the value is shown as a cumulative sum of all previous values.

groupstr

Grouping variable. Each group calculates its own statistics.

colorstr

Color of the box boundary lines. For more info see Color and Fill. Use ‘flow_type’ to color lines by the direction of the flow.

fillstr

Fill color of the boxes. For more info see Color and Fill. Use ‘flow_type’ to color boxes by the direction of the flow.

sizefloat, default=0.0

Line width of the box boundary lines.

alphafloat

Transparency level of the boxes. Accept values between 0 and 1.

linetypeint or str or list

Type of the box boundary lines. Accept codes or names (0 = ‘blank’, 1 = ‘solid’, 2 = ‘dashed’, 3 = ‘dotted’, 4 = ‘dotdash’, 5 = ‘longdash’, 6 = ‘twodash’), a hex string (up to 8 digits for dash-gap lengths), or a list pattern [offset, [dash, gap, …]] / [dash, gap, …]. For more info see Line Types.

widthfloat, default=0.9

Width of the boxes. Typically range between 0 and 1. Values that are greater than 1 lead to overlapping of the boxes.

show_legendbool, default=False

True - show the legend.

relative_tooltipslayer_tooltips or str

Tooltips for boxes with relative values. Result of the call to the layer_tooltips() function. Specify appearance, style and content. When ‘none’, tooltips are not shown. When ‘detailed’, a more detailed (compared to the default) version of the tooltips is shown.

absolute_tooltipslayer_tooltips or str

Tooltips for boxes with absolute values. Result of the call to the layer_tooltips() function. Specify appearance, style and content. When ‘none’, tooltips are not shown. When ‘detailed’, a more detailed (compared to the default) version of the tooltips is shown.

sorted_valuebool, default=False

Sorts categories by absolute value of the changes.

thresholdfloat

Groups all categories under a certain threshold value into “Other” category.

max_valuesint

Groups all categories with the smallest changes, except the first max_values, into “Other” category.

basefloat, default=0.0

Values with measure ‘absolute’ or ‘total’ are relative to this value.

calc_totalbool, default=True

Setting the calc_total to True will put the final cumulative sum into a new separate box. Taken into account only if the ‘measure’ column isn’t provided.

total_titlestr

The header of the last box with the final cumulative sum, if ‘measure’ column isn’t provided. Also used as a title in the legend for columns of type ‘total’.

hlinestr or dict

Horizontal line passing through 0. Set ‘blank’ or result of element_blank() to draw nothing. Set element_line() to specify parameters.

hline_ontopbool, default=True

Option to place horizontal line over the other layers.

connectorstr or dict

Line between neighbouring boxes connecting the end of the previous box and the beginning of the next box. Set ‘blank’ or result of element_blank() to draw nothing. Set element_line() to specify parameters.

labelstr or dict

Label on the box. Shows change value. Set ‘blank’ or result of element_blank() to draw nothing. Set element_text() to specify parameters. Use ‘flow_type’ for color parameter of the element_text() to color labels by the direction of the flow.

label_formatstr

Format used to transform label mapping values to a string. Examples:

  • ‘.2f’ -> ‘12.45’

  • ‘Num {}’ -> ‘Num 12.456789’

  • ‘TTL: {.2f}$’ -> ‘TTL: 12.45$’

For more info see Formatting.

Returns:
PlotSpec

Plot object specification.

Notes

Computed variables:

  • ..x.. : category id.

  • ..xlabel.. : category name.

  • ..ymin.. : lower value of the change.

  • ..ymax.. : upper value of the change.

  • ..measure.. : kind of a calculation: absolute, relative or total.

  • ..flow_type.. : direction of the flow: increasing, decreasing, or the result (total).

  • ..initial.. : initial value of the change.

  • ..value.. : current cumsum (result of the change) or absolute value (depending on the ‘measure’ column).

  • ..dy.. : value of the change.

Examples

 1import numpy as np
 2from lets_plot import *
 3from lets_plot.bistro.waterfall import *
 4LetsPlot.setup_html()
 5categories = list("ABCDEF")
 6np.random.seed(42)
 7data = {
 8    'x': categories,
 9    'y': np.random.normal(size=len(categories))
10}
11waterfall_plot(data, 'x', 'y')


 1import numpy as np
 2from lets_plot import *
 3from lets_plot.bistro.waterfall import *
 4LetsPlot.setup_html()
 5n, m = 10, 5
 6categories = list(range(n))
 7np.random.seed(42)
 8data = {
 9    'x': categories,
10    'y': np.random.randint(2 * m + 1, size=len(categories)) - m
11}
12waterfall_plot(data, 'x', 'y', \
13               threshold=2, \
14               width=.7, size=1, fill="white", color='flow_type', \
15               hline=element_line(linetype='solid'), hline_ontop=False, \
16               connector=element_line(linetype='dotted'), \
17               label=element_text(color='flow_type'), \
18               total_title="Result", show_legend=True)


 1import numpy as np
 2from lets_plot import *
 3from lets_plot.bistro.waterfall import *
 4LetsPlot.setup_html()
 5categories = list("ABCDEFGHIJKLMNOP")
 6np.random.seed(42)
 7data = {
 8    'x': categories,
 9    'y': np.random.uniform(-1, 1, size=len(categories))
10}
11waterfall_plot(data, 'x', 'y', sorted_value=True, max_values=5, calc_total=False, \
12               relative_tooltips=layer_tooltips().title("Category: @..xlabel..")
13                                                 .format("@..initial..", ".2~f")
14                                                 .format("@..value..", ".2~f")
15                                                 .format("@..dy..", ".2~f")
16                                                 .line("@{..flow_type..}d from @..initial.. to @..value..")
17                                                 .line("Difference: @..dy..")
18                                                 .disable_splitting(), \
19               size=1, alpha=.5, \
20               label=element_text(color="black"), label_format=".4f")


 1from lets_plot import *
 2from lets_plot.bistro.waterfall import *
 3LetsPlot.setup_html()
 4data = {
 5    'company': ["Badgersoft"] * 7 + ["AIlien Co."] * 7,
 6    'accounts': ["initial", "revenue", "costs", "Q1", "revenue", "costs", "Q2"] * 2,
 7    'values': [200, 200, -100, None, 250, -100, None, \
 8               150, 50, -100, None, 100, -100, None],
 9    'measure': ['absolute', 'relative', 'relative', 'total', 'relative', 'relative', 'total'] * 2,
10}
11waterfall_plot(data, 'accounts', 'values', measure='measure', group='company') + \
12    facet_wrap(facets='company', scales='free_x')
On this page