Waterfall Tutorials

Step by step tutorial

The user story

I’m a C-level manager in an international company.

Last year my revenue was 64 M$ and this year my revenue is 161 M$.

Awesome! Does that mean every region/country performed well?

Which county contributed the most to this increase? Which one needs more attention to make sure the sales will go back up?

As I’m analyzing the variation between 2 points in time, let’s do a waterfall

Warning

Before you start!

Make sure you added your datasource to your application. Once you’re done create a new story.

Pick some data

To create a nice waterfall, the chart needs to understand what is value to begining with, what is the value at the end, what is in between, etc…

So your data should reflect this structure in some way.

You need :

  • a type column: this will help understand where goes what. Is this line the value for the start? the end? the lowest level of detail (child)? The highest one (parent)?

  • a label column: what i’m I showing at the lowest level?

    In our case my countries.

  • a value column: what is the number I want to show?

    In our case my revenue

  • and sometimes a group column : only if I want to drill and display a parent group before drilling into the lowest level of detail

If your data is alredy in this format, move on to the next step.

In our case my data does not look like that. I just have the data for the countries by year…

raw data

Don’t worry! We created a data function to get the data ready for our waterfall. It will take just a few minutes.

📖 Learn more on how to make your data waterfall compliant with this tutorial

Also, you can create fake data fitting the waterfall format with our awesome fake data generator Fakir.

After following the tutorial, this is how my query should look like in the Dataset Editor.

See on the left side how the data has been formatted!

waterfall post process

Add units to your revenue column to contextualize the information and give meaning to your story.

Chart Parameters

Once my data has been setup I can now choose to configure a waterfall.

I just need to follow the steps, and in 3 clicks I’m done!

waterfall parameters

Add a drill

Pretty cool what I did in a few clicks, but it would be nice to have a summary by region before looking into the countries…

Let’s add a drill functionality!

Let’s edit the chart and go to the Dataset Editor.

From there, in the post-process section, I just need to make sure I add a insideGroup parameter and I update the upperGroup one.

Just like below:

waterfall post process

Then I go the chart parameters menu and I add the optional parameter group to my configuration

drill parameters

Add steps

Don’t want to have to click to see the countries? Hum, what if I add steps instead?

Tip

Re-create a brand new waterfall (without drill) to be able to compare the 2 graphs and choose between them

In the optional parameters activate the steps options. Then define where to put the steps.

waterfall steps

Other configuration examples

Warning

These examples are from the code mode. ⚠️ the chartOptions & data are deprecated, make sure to use de datasets/charts configuration.

The mode 2 has been deprecated and is not available anymore. You don’t need to change your mode 2 configuration, it’s still compatible”.

Overview

The waterfall chart is particular because it accepts data in two different formats and has two types of configuration.

The first mode needs expects data in aggregated and detailed versions while the second mode takes only the detailed data and performs the aggregations inside groups on the fly.

In both cases the first and last data records have groups = label and the value of the last record is overriden by the sum of all other values.

Configuration Mode 1

The difference between mode 1 and mode 2 is the drill configuration.

Mandatory config options - Mode #1:

  • value: name of the column containing the value
  • label: name of the column containing the text label to display
  • type: name of the column that provides the drill level for each element (i.e. is it a parent or a child, the type should be -1 for the first and last labels)

Available options (available for mode 2 as well) :

  • groups: name of the column that provides the groups (i.e. the parentand all of its child)
  • variation: name of the column containing the variation value you wish to display below the main value; it needs to be given for both inner and outer drill levels
  • meta: additional meta information to display (see the meta documentation for more details on the syntax)
  • zeroBaseline: number that sets a new baseline value (default to 0)
  • hideParenthesisEvolution: Set true if you want to hide the parenthesis around evolution text
  • reverseSentiment: true/false (default to false), whether to reverse the sentiment (i.e. negative values are positive/green)
  • groupsOrder: array with the custom order for your groups [my_group1, my_group2,…] or name of the column in your data that you want to use to sort the groups
  • labelsOrder: array with the custom order for your labels [my_label1, my_label2,…] or name of the column in your data that you want to use to sort the labels. The same common order rule will be used for each group. Ordering labels will have an impact on groups order (unless a groupsOrder is specified) if different labels are present in the different groups.
  • steps - Array of steps to get intermediate values in the bridge. A step object is composed of to keys:
    • label : label after which to insert the step
    • step : label to display for the step

The order of the data will be kept in the waterfall chart. So if you need a specific order for your labels, order your data in your query. A good way to do this is by adding a labels_order column and using a $sort stage in your data query.

Preparing the data in the right shape can be complicated with the waterfallchart, especially if you have multiple filters and an order to keep. Luckily, we created a postprocess helper for this. Check out the waterfall postprocess step in the documentation, it might save you a lot of time.

Data Structure

These datasets are used in the Mode 1 configuration examples.

Waterfall without drill - mode 1

country region my_type nb_movies var
N-1 N-1 -1 100  
Europe Europe parent -20 -0,04
Asia Asia parent 40 0,1
America America parent 30 0,02
N N -1 150  

Waterfall with drill - mode 1

country region my_type nb_movies var order revenue
N-1 N-1 -1 100   0 250
Europe Europe parent -20 -0,04 2 -50
France Europe child -10 -0,03 3 -25
Germany Europe child -15 -0,1 5 -38
UK Europe child 5 0,02 4 13
Asia Asia parent 40 0,1 6 100
India Asia child 25 0,01 8 63
China Asia child 15 0,05 7 38
Africa Africa parent 15 0,2 9 38
America America parent 30 0,02 10 75
USA America child -10 -0,03 12 -25
Canada America child 10 0,06 11 25
Mexico America child 30 0,01 13 75
N N -1 165   14 413
Ex1: Simple Waterfall
Image of chart

Image of chart

{
    level: 3
    parent_id: 120
    id:120000
    title: "Waterfall simple"

    chartOptions:
      data:
        query:
          domain:"waterfall_simple"
      chartType: "waterfallchart"
      value:"nb_movies"
      label:"country"
      type:"my_type"
}
Ex2: Waterfall drill
Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120001
  title: "Waterfall drill"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
}
Ex3: Waterfall with variation

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120002
  title: "Waterfall with variation"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
}
Ex4: Waterfall with units and precision

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120003
  title: "Waterfall with units and precision"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
    units:
      nb_movies: " films"
      var: " "
}
Ex5: Waterfall with hideParenthesisEvolution

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120004
  title: "Waterfall with hideParenthesisEvolution"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
    hideParenthesisEvolution: true
    units:
      nb_movies: " films"
      var: " "
}
Ex6: Waterfall with groupsOrder

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120005
  title: "Waterfall with groupsOrder"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
    groupsOrder: ["N-1","America", "Europe", "Asia", "Africa", "N"]
    units:
      nb_movies: " films"
      var: " "
}
Ex7: Waterfall with labelsOrder

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120006
  title: "Waterfall with labelsOrder"

  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
    labelsOrder: "order" #can also be an array with the custom order for your labels [my_label1, my_label2,…]
    units:
      nb_movies: " films"
      var: " "
}
Ex8: Waterfall with reverseSentiment

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120007
  title: "Waterfall with reverseSentiment"

  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    variation:"var"
    labelsOrder: "order" #can also be an array with the custom order for your labels [my_label1, my_label2,…]
    reverseSentiment: true
    units:
      nb_movies: " films"
      var: " "
}
Ex9: Waterfall with steps

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120008
  title: "Waterfall with steps"

  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    steps: [
      { label: "Europe", step: "U.E."}
      { label: "Africa",step: "Rest of world"}
    ]
    units:
      nb_movies: " films"
      var: " "
}
Ex10: Waterfall with zeroBaseline

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120009
  title: "Waterfall with zeroBaseline"

  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    zeroBaseline: 20
    units:
      nb_movies: " films"
      var: " "
}
Ex11: Waterfall with meta

This option is also available for the mode 2.

Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:120010
  title: "Waterfall with meta"

  chartOptions:
    data:
      query:
        domain:"waterfall_drill"
      precision:
        var: ".0%"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    type:"my_type"
    groups:"region"
    meta: ["revenue"]
    units:
      nb_movies: " films"
      var: " "
      revenue: " $"
}
Configuration Mode 2 (deprecated)

The difference between mode 1 and mode 2 is the drill configuration.

Mandatory config options - Mode #2:

  • value: name of the column containing the value; the values shown in grouped levels will be the sum of the inner values
  • label: name of the column containing the text label to display for the most detailed drill level
  • drillGroup: name of the column that provides the groups (i.e. it will be used as the label of the uppermost level)
  • drillLevel: name of the column that provides the drill level for each element (i.e. is it a parent or a child, the type should be empty for the first and last labels)

Available options (available for mode 1 as well) :

  • variation: name of the column containing the variation value you wish to display below the main value
  • meta: additional meta information to display (see the meta documentation for more details on the syntax)
  • zeroBaseline: number that sets a new baseline value (default to 0)
  • hideParenthesisEvolution: Set true if you want to hide the parenthesis around evolution text
  • reverseSentiment: true/false (default to false), whether to reverse the sentiment (i.e. negative values are positive/green)
  • groupsOrder: array with the custom order for your groups [my_group1, my_group2,…] or name of the column in your data that you want to use to sort the groups
  • labelsOrder: array with the custom order for your labels [my_label1, my_label2,…] or name of the column in your data that you want to use to sort the labels. The same common order rule will be used for each group. Ordering labels will have an impact on groups order (unless a groupsOrder is specified) if different labels are present in the different groups.
  • steps - Array of steps to get intermediate values in the bridge. A step object is composed of to keys:
    • label : label after which to insert the step
    • step : label to display for the step
Data Structure

These datasets are used in the Mode 2 configuration examples.

Waterfall without drill - mode 2

country nb_movies var
N-1 100  
Europe -20 -0,04
Asia 40 0,1
America 30 0,02
N 150  

Waterfall with drill - mode 2

country region my_type nb_movies var order revenue
N-1 N-1   100   0 250
Europe Europe parent -20 -0,04 2 -50
France Europe child -10 -0,03 3 -25
Germany Europe child -15 -0,1 5 -38
UK Europe child 5 0,02 4 13
Asia Asia parent 40 0,1 6 100
India Asia child 25 0,01 8 63
China Asia child 15 0,05 7 38
Africa Africa parent 15 0,2 9 38
America America parent 30 0,02 10 75
USA America child -10 -0,03 12 -25
Canada America child 10 0,06 11 25
Mexico America child 30 0,01 13 75
N N   165   14 413
Mode 2 : Ex1: Simple Waterfall
Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:1200001
  title: "Waterfall simple - mode 2"
  chartOptions:
    data:
      query:
        domain:"waterfall_simple2"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
}
Mode 2 : Ex2: Waterfall drill
Image of chart

Image of chart

{
  level: 3
  parent_id: 120
  id:1200002
  title: "Waterfall drill - mode 2"
  chartOptions:
    data:
      query:
        domain:"waterfall_drill2"
    chartType: "waterfallchart"
    value:"nb_movies"
    label:"country"
    drillLevel: "my_type"
    drillGroup: "region"
}

That’s it!