Create Waterfall Charts in Word Using Python

A waterfall chart shows how a starting value changes through a series of increases and decreases. For example, you can use one in a financial report to show how sales, expenses, and other income contribute to a closing balance.

In this tutorial, you’ll create a waterfall chart in a Word document using Python and Aspose.Words for Python via .NET. You’ll also learn how to identify total points in the chart and inspect waterfall charts in existing documents.

Python Library to Create Waterfall Charts in Word

Aspose.Words for Python via .NET lets you create and modify Word documents in Python. You can use it to add charts to reports and work with chart series and data points.

Install the library from PyPI:

pip install aspose-words

Use Aspose.Words for Python via .NET 26.10 or later for the complete tutorial. This version introduced the APIs used to check whether a waterfall chart point is a total.

For platform requirements and other installation details, see the installation documentation.

Understand the Sample Waterfall Chart

The examples use the following data to show changes from an opening balance to a closing balance:

The sales, expenses, and other income points represent changes. The opening balance, subtotal, and closing balance represent values at particular stages.

To create the chart series, you’ll provide three lists in the same order:

• Categories: Labels for the chart points.
• Values: The changes and explicitly supplied total values.
• Total flags: Boolean values that designate the corresponding points as totals.

The flags identify total points; they do not calculate them. In this example, the subtotal is supplied as 120, and the closing balance is supplied as 130.

Create a Waterfall Chart in Word Using Python

Follow these steps to create the chart:

1. Create a Document and a DocumentBuilder.
2. Insert a chart using ChartType.WATERFALL.
3. Set the chart title and clear the default series.
4. Add the categories, values, and total flags.
5. Save the document as a DOCX file.

The following example creates the complete chart:

import aspose.words as aw

# Create a document and document builder.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# Insert a waterfall chart.
shape = builder.insert_chart(
    chart_type=aw.drawing.charts.ChartType.WATERFALL,
    width=500,
    height=350
)

chart = shape.chart
chart.title.text = "Balance Changes"

# Remove the default chart series.
chart.series.clear()

# Define categories, values, and total flags.
categories = [
    "Opening balance",
    "Sales",
    "Expenses",
    "Subtotal",
    "Other income",
    "Closing balance"
]

values = [100, 40, -20, 120, 10, 130]

total_flags = [True, False, False, True, False, True]

# Add the waterfall series.
series = chart.series.add(
    series_name="Balance",
    categories=categories,
    values=values,
    is_subtotal=total_flags
)

# Save the Word document.
doc.save("waterfall-chart.docx")

The waterfall-specific add() method accepts the series name, categories, values, and Boolean flags. Each item at a given index describes the same chart point. Although the Boolean argument is named is_subtotal, the documented example uses it to designate the starting value, an intermediate subtotal, and the final value as totals.

The resulting waterfall-chart.docx contains a six-point chart showing the opening balance, changes, subtotal, and closing balance.

Check Whether a Waterfall Chart Point Is a Total

You can check each point’s designation with series.is_total(index). Add the following loop after the chart.series.add(...) call in the previous example:

for i in range(len(categories)):
    point_type = "Total" if series.is_total(i) else "Not a total"
    print(f"{categories[i]}: {values[i]} — {point_type}")

For the sample data, the expected output is:

Opening balance: 100 — Total
Sales: 40 — Not a total
Expenses: -20 — Not a total
Subtotal: 120 — Total
Other income: 10 — Not a total
Closing balance: 130 — Total

The is_total() method takes a zero-based index and returns True if the point is designated as a total. It does not identify whether the point is an opening balance, an intermediate subtotal, or a final total.

Check a Total Using ChartDataPoint.is_total

If you already have a chart data point, you can read its is_total property. The following example checks the subtotal at index 3:

is_subtotal = series.data_points[3].is_total
print(f"Subtotal is a total: {is_subtotal}")

Expected output:

Subtotal is a total: True

ChartDataPoint.is_total is a read-only property for waterfall charts. Like series.is_total(index), it reports the point’s designation; it does not set or calculate the total.

Inspect a Waterfall Chart in an Existing Word Document

You can also load an existing Word document and search it for waterfall chart series. The following standalone example checks every shape, skips shapes without charts, and inspects each waterfall series it finds.

Replace waterfall-chart.docx with the path to your document:

import aspose.words as aw

# Load an existing Word document.
doc = aw.Document("waterfall-chart.docx")

found_waterfall_series = False

# Search the document's shapes.
shapes = doc.get_child_nodes(aw.NodeType.SHAPE, True)

for node in shapes:
    shape = node.as_shape()

    if not shape.has_chart:
        continue

    for series in shape.chart.series:
        if series.series_type != aw.drawing.charts.ChartSeriesType.WATERFALL:
            continue

        found_waterfall_series = True
        print(f"Waterfall series: {series.name}")

        for i in range(series.y_values.count):
            point_type = "Total" if series.is_total(i) else "Not a total"
            print(f"Point {i}: {point_type}")

if not found_waterfall_series:
    print("No waterfall chart series found.")

The example reports each point by its zero-based index. It processes multiple waterfall series if they are present and prints a message if it finds none. The series_type property lets the code check for ChartSeriesType.WATERFALL before calling is_total().

Get a Free License

You can request a free temporary license to evaluate Aspose.Words for Python via .NET. Apply the license in your application before running the examples.

Conclusion

You can create a waterfall chart in a Word document using Python and identify its total points programmatically. Use the same approach to add charts to generated reports or inspect waterfall series in existing documents.

Frequently Asked Questions

How do I create a waterfall chart in Word using Python?

Insert a chart using ChartType.WATERFALL, add a series with categories, values, and total flags, and save the document as a DOCX file.

How do I specify total points in a waterfall chart?

Pass a Boolean list through the is_subtotal argument when adding the series. Set an entry to True for each point that should be designated as a total.

How can I check whether a waterfall chart point is a total?

Call series.is_total(index) with the point’s zero-based index, or read the is_total property of its data-point object.

Do the is_total APIs set or calculate totals?

No. They report whether a point is designated as a total. Supply the values and their total flags when creating the series.

Can I inspect a waterfall chart in an existing Word document?

Yes. Load the document, find shapes containing charts, and check each series for ChartSeriesType.WATERFALL before examining its points.

See Also

• Working with Charts in Aspose.Words for Python
• ChartSeries.is_total API Reference
• ChartDataPoint.is_total API Reference
• Aspose.Words Support Forum