ウォーターフォールチャートは、開始値が増減の連続を通じてどのように変化するかを示します。たとえば、財務報告書で売上、費用、その他の収入が最終残高にどのように寄与するかを示すために使用できます。

このチュートリアルでは、Python と Aspose.Words for Python via .NET を使用して Word ドキュメントに滝グラフを作成します。また、グラフ内の合計ポイントを特定する方法と、既存のドキュメント内の滝グラフを検査する方法も学びます。

Wordでウォーターフォールチャートを作成するPythonライブラリ

Aspose.Words for Python via .NET は、Python で Word ドキュメントを作成および変更できるようにします。レポートにチャートを追加したり、チャートシリーズやデータポイントを操作したりすることができます。

PyPI からライブラリをインストールします:

pip install aspose-words

完全なチュートリアルには Aspose.Words for Python via .NET 26.10 or later を使用してください。このバージョンでは、滝型チャートのポイントが合計かどうかを確認するために使用される API が導入されました。

プラットフォーム要件やその他のインストールの詳細については、インストール ドキュメントをご覧ください。

サンプルの滝型チャートを理解する

例では、開始残高から終了残高への変化を示すために、以下のデータを使用します。

カテゴリ値ポイントタイプ
期首残高100合計
売上+40増加
経費−20減少
小計120合計
その他の収入+10増加
期末残高130合計

売上、費用、その他の収入項目は変動を表します。期首残高、サブトータル、期末残高は特定の段階での値を表します。

チャートシリーズを作成するには、同じ順序で3つのリストを提供します:

  • カテゴリ: チャートポイントのラベル。
  • 値: 変更と明示的に提供された合計値。
  • 合計フラグ: 対応するポイントを合計として指定するブール値。

フラグは総ポイントを識別しますが、計算は しません。この例では、小計が 120 として提供され、期末残高が 130 として提供されます。

Python を使用して Word でウォーターフォール チャートを作成する

チャートを作成する手順は次のとおりです。

  1. Document と DocumentBuilder を作成します。
  2. ChartType.WATERFALL を使用してチャートを挿入します。
  3. チャートのタイトルを設定し、デフォルトの系列をクリアします。
  4. カテゴリ、値、および合計フラグを追加します。
  5. ドキュメントを DOCX ファイルとして保存します。

以下の例は完全なチャートを作成します:

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")

ウォーターフォール固有の add() メソッドは、シリーズ名、カテゴリ、値、およびブールフラグを受け取ります。指定されたインデックスの各項目は同じチャートポイントを表します。ブール引数は is_subtotal という名前ですが、ドキュメント例では開始値、中間の小計、最終値を合計として指定するために使用されています。

生成された waterfall-chart.docx には、開始残高、変動、サブトータル、終了残高を示す6点のチャートが含まれています。

Python を使用して Word でウォーターフォールチャートを作成する。

Python を使用して Word でウォーターフォールチャートを作成する。

ウォーターフォールチャートのポイントが合計かどうかを確認する

各ポイントの指定を series.is_total(index) で確認できます。前の例の chart.series.add(...) 呼び出しの後に、次のループを追加してください：

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}")

サンプルデータの場合、期待される出力は次のとおりです:

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

is_total() メソッドは ゼロベースのインデックス を受け取り、ポイントが合計として指定されている場合に True を返します。ポイントが期首残高、途中の小計、または最終合計のいずれであるかは識別しません。

ChartDataPoint.is_total を使用して合計を確認する

既にチャート データ ポイントがある場合は、その is_total プロパティを読み取ることができます。次の例はインデックス 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 はウォーターフォールチャート用の 読み取り専用 プロパティです。series.is_total(index) と同様に、ポイントの指定を報告しますが、合計を設定したり計算したりはしません。

既存の Word ドキュメントでウォーターフォール チャートを検査する

既存の Word ドキュメントをロードし、滝型チャート系列を検索することもできます。次のスタンドアロン例では、すべてのシェイプをチェックし、チャートがないシェイプをスキップし、見つかった各滝型系列を検査します。

waterfall-chart.docx をドキュメントへのパスに置き換えてください:

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.")

この例では、各ポイントをゼロベースのインデックスで報告します。存在する場合は複数のウォーターフォールシリーズを処理し、見つからない場合はメッセージを出力します。series_type プロパティにより、コードは ChartSeriesType.WATERFALL をチェックしてから is_total() を呼び出すことができます。

無料ライセンスを取得

Aspose.Words for Python via .NET を評価するために、無料の一時ライセンス をリクエストできます。サンプルを実行する前に、アプリケーションにライセンスを適用してください。

結論

Python を使用して Word 文書にウォーターフォール チャートを作成し、プログラムで合計ポイントを特定できます。同じアプローチを使用して、生成されたレポートにチャートを追加したり、既存の文書内のウォーターフォール シリーズを検査したりできます。

よくある質問

Python を使用して Word でウォーターフォール チャートを作成する方法は？

ChartType.WATERFALL を使用してチャートを挿入し、カテゴリ、値、合計フラグを持つシリーズを追加し、ドキュメントを DOCX ファイルとして保存します。

ウォーターフォールチャートで合計ポイントを指定するにはどうすればよいですか？

シリーズを追加するときに is_subtotal 引数にブールリストを渡します。合計として指定すべき各ポイントに対して、エントリを True に設定します。

ウォーターフォール チャートのポイントが合計かどうかを確認するにはどうすればよいですか？

Call series.is_total(index) でポイントのゼロベースインデックスを指定するか、データポイントオブジェクトの is_total プロパティを読み取ります。

is_total APIは合計を設定しますか、それとも計算しますか？

いいえ。ポイントが合計として指定されているかどうかを報告します。シリーズを作成する際に、値とそれらの合計フラグを提供してください。

既存の Word ドキュメントでウォーターフォール チャートを検査できますか？

はい。ドキュメントをロードし、チャートを含むシェイプを見つけ、ポイントを調べる前に各シリーズが ChartSeriesType.WATERFALL かどうかをチェックします。

参照