Waterfall code sample

A waterfall visualization shows how an initial value is increased and decreased by a series of intermediate values, leading to a final cumulative value shown in the far right column.

About this task

For more information about the waterfall custom visualization code sample on IBM Accelerator Catalog, see https://community.ibm.com/accelerators/catalog/content/Waterfall .

Note: This code sample is intended for an advanced custom visualization developer. It provides an opportunity for developers to extend their visualizations. If you are not a visualization developer, IBM® Cognos® Analytics comes with a full set of powerful visualizations that are ready to use.

Waterfall visualizations are supported as of IBM Cognos Analytics 11.1.6

This custom visualization code sample provides a way to show very specific data (see waterfall_sample_data.xlslx) within a waterfall visualization.

Some examples of waterfall visualizations are as follows:
  • Viewing the net income after you add the increases and decreases of revenue and costs for an enterprise over a quarter.
  • Cumulative sales for products across a year with an annual total.
The Value Type field must use a column that contains these specific values:
  • TOTAL (gray): the total value at a point
  • ADJUSTMENT (yellow): an optional manual adjustment that might not be suitable to be categorized as DELTA
  • DELTA (green or red): a positive or negative change in the value

There are code samples available for developers of custom visualizations. The code samples illustrate certain aspects of the customvis library and tools. The main focus of each sample is not the completeness of the visualization, but rather to demonstrate how specific features work.

To view the source code and packed bundle (.zip file) for the waterfall visualization sample, go to this public GitHub repository. To download the files, browse to the root of this directory and click Clone or download.

For more information, see Custom visualizations code samples.

For more information about custom visualizations, see Developing custom visualizations. For an excellent tutorial to get you started, see Custom visualizations - tutorial.

There are three ways to use this sample custom visualization.
  • You can upload the packed bundle (.zip file).

    For more information, see Packaging the custom visualization.

  • You can package a sample with customvis pack and upload the bundle (zip file) to IBM Cognos Analytics

    For more information, see Packaging the custom visualization.

  • You can run any sample locally by running customvis start inside the folder that contains the sample. After that, you can use the Preview Vis in IBM Cognos Analytics Dashboard or Reporting to insert the custom visualization in your dashboard or report.

    For more information, see Using a D3 sample in your custom visualization.

The following steps demonstrate how to use the waterfall visualization and populate it with data.

Procedure

  1. Create a dashboard and click the Visualization Change visualization icon icon in the toolbar.
  2. Click the Custom tab.
    If there are no custom visuals available, then you can add a custom visual by clicking the Add a custom visual Add a custom visual icon on the Custom tab.
  3. From the Custom visuals pane, select the waterfall visualization.
  4. Upload Waterfall_sample_data.xlsx (https://public.dhe.ibm.com/software/data/sw-library/cognos/mobile/C11/custom_visualizations/data/Waterfall_sample_data.xlsx) and use it as the data source.
  5. Create the waterfall visualization by dragging the following data items from Waterfall_sample_data.xlsx in the Sources pane Data icon:
    • Drag Month onto the Categories field.
    • Drag Type onto the Value type field.
    • Drag Police Holders onto the Value field.

    This sample Waterfall visualization displays data from a fictional insurance company. It shows the change in the total number of policy holders by month in 2019.

    Waterfall

What to do next

An explanation of the specific properties within this visualization that can be adjusted:

Property Purpose
Ratio of base Ratio of base over chart height. Base is placed under Total columns. If you want to adjust the height of total bars, then use this property.
Show changes Toggles to see the changes by the bridges.
Total rows To classify a row as the Total rows category, the value of the row in your data must match the Type classes string that is specified in this property.
Adjustment rows To classify a row as the Adjustment rows category, the value of the row in your data must match the Type classes string that is specified in this property.
Delta rows To classify a row as the Delta rows category, the value of the row in your data must match the Type classes string that is specified in this property.