Crear gráficos de cascada en Word usando Python

Un gráfico de cascada muestra cómo un valor inicial cambia a través de una serie de aumentos y disminuciones. Por ejemplo, puedes usar uno en un informe financiero para mostrar cómo las ventas, los gastos y otros ingresos contribuyen a un saldo final.

En este tutorial, crearás un gráfico de cascada en un documento de Word usando Python y Aspose.Words for Python via .NET. También aprenderás cómo identificar los puntos totales en el gráfico y examinar los gráficos de cascada en documentos existentes.

Biblioteca de Python para crear gráficos de cascada en Word

Aspose.Words for Python via .NET le permite crear y modificar documentos Word en Python. Puede usarlo para agregar gráficos a los informes y trabajar con series de gráficos y puntos de datos.

Instala la biblioteca desde PyPI:

pip install aspose-words

Utilice Aspose.Words for Python via .NET 26.10 o posterior para el tutorial completo. Esta versión introdujo las API utilizadas para comprobar si un punto de gráfico de cascada es un total.

Para los requisitos de plataforma y otros detalles de instalación, consulte la documentación de instalación.

Comprender el gráfico de cascada de muestra

Los ejemplos utilizan los siguientes datos para mostrar los cambios de un saldo inicial a un saldo final:

Las ventas, los gastos y los demás ingresos representan cambios. El saldo de apertura, el subtotal y el saldo de cierre representan valores en etapas particulares.

Para crear la serie del gráfico, proporcionará tres listas en el mismo orden:

• Categories: Etiquetas para los puntos del gráfico.
• Values: Los cambios y los valores totales suministrados explícitamente.
• Total flags: Valores booleanos que designan los puntos correspondientes como totales.

Las banderas identifican los puntos totales; no los calculan. En este ejemplo, el subtotal se suministra como 120 y el saldo de cierre se suministra como 130.

Crear un gráfico de cascada en Word usando Python

Siga estos pasos para crear el gráfico:

1. Crea un Document y un DocumentBuilder.
2. Inserta un gráfico usando ChartType.WATERFALL.
3. Establece el título del gráfico y elimina la serie predeterminada.
4. Añade las categorías, valores y banderas de total.
5. Guarda el documento como un archivo DOCX.

El siguiente ejemplo crea el gráfico completo:

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

El método add() específico de waterfall acepta el nombre de la serie, categorías, valores y banderas booleanas. Cada elemento en un índice dado describe el mismo punto del gráfico. Aunque el argumento booleano se llama is_subtotal, el ejemplo documentado lo usa para designar el valor inicial, un subtotal intermedio y el valor final como totales.

El archivo resultante waterfall-chart.docx contiene un gráfico de seis puntos que muestra el saldo inicial, los cambios, el subtotal y el saldo final.

Verificar si un punto del gráfico de cascada es un total

Puedes comprobar la designación de cada punto con series.is_total(index). Añade el siguiente bucle después de la llamada chart.series.add(...) en el ejemplo anterior:

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

Para los datos de muestra, la salida esperada es:

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

El método is_total() recibe un índice basado en cero y devuelve True si el punto está designado como total. No identifica si el punto es un saldo de apertura, un subtotal intermedio o un total final.

Comprobar un total usando ChartDataPoint.is_total

Si ya tienes un punto de datos del gráfico, puedes leer su propiedad is_total. El siguiente ejemplo verifica el subtotal en el índice 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 es una propiedad read-only para gráficos de cascada. Al igual que series.is_total(index), informa la designación del punto; no establece ni calcula el total.

Inspeccionar un gráfico de cascada en un documento Word existente

También puedes cargar un documento de Word existente y buscar en él series de gráficos de cascada. El siguiente ejemplo independiente verifica cada forma, omite las formas sin gráficos y examina cada serie de cascada que encuentra.

Reemplace waterfall-chart.docx con la ruta a su documento:

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

El ejemplo informa cada punto por su índice basado en cero. Procesa múltiples series de cascada si están presentes y muestra un mensaje si no encuentra ninguna. La propiedad series_type permite que el código verifique ChartSeriesType.WATERFALL antes de llamar a is_total().

Obtén una licencia gratuita

Puede solicitar una licencia temporal gratuita para evaluar Aspose.Words for Python via .NET. Aplique la licencia en su aplicación antes de ejecutar los ejemplos.

Conclusión

Puedes crear un gráfico de cascada en un documento de Word usando Python e identificar sus puntos totales de forma programática. Utiliza el mismo enfoque para agregar gráficos a los informes generados o inspeccionar series de cascada en documentos existentes.

Preguntas frecuentes

¿Cómo crear un gráfico de cascada en Word usando Python?

Inserte un gráfico usando ChartType.WATERFALL, añada una serie con categorías, valores y banderas de total, y guarde el documento como un archivo DOCX.

¿Cómo especificar puntos totales en un gráfico de cascada?

Pase una lista de valores booleanos a través del argumento is_subtotal al agregar la serie. Establezca una entrada en True para cada punto que debe designarse como total.

¿Cómo puedo comprobar si un punto del gráfico de cascada es un total?

Llame a series.is_total(index) con el índice basado en cero del punto, o lea la propiedad is_total de su objeto de punto de datos.

¿Los APIs is_total establecen o calculan totales?

No. Informan si un punto está designado como total. Proporcione los valores y sus indicadores de total al crear la serie.

¿Puedo inspeccionar un gráfico de cascada en un documento de Word existente?

Sí. Cargue el documento, encuentre las formas que contienen gráficos y verifique cada serie para ChartSeriesType.WATERFALL antes de examinar sus puntos.

Véase también

• Trabajar con gráficos en Aspose.Words for Python
• Referencia de API de ChartSeries.is_total
• Referencia de API de ChartDataPoint.is_total
• Foro de soporte de Aspose.Words