Skip to main content

Create PDF and Word Reports with Python

workspace.report writes the same document as Download PDF and Download Word on the ESPlotter report page: a cover, an index, an optional introduction, every plot with a series from the included pages, interval-statistics and data-label tables, and optional conclusions. Use it when a script already prepares the plots of a study and should also deliver its report.

Fill the report​

report = workspace.report
report.set(
    title="HILLTOP 138 fault study",
    subtitle="Three-phase fault cleared after 100 ms",
    introduction="Voltages and angles recorded during the fault.\nAll values are in per unit.",
    conclusions="Voltages recover above 0.95 pu within one second.",
)
report.chart_theme = "light"

The title is required to export. Line breaks in the introduction and conclusions are kept as separate paragraphs. chart_theme draws the report charts "light" or "dark"; None follows Settings > General > Report charts. report.clear() empties the four texts and keeps the chart theme.

In Live mode these fields are the report form of the connected ESPlotter window, so the text you set appears in the form and text typed in the form is read by the script.

Choose the pages​

Every page starts included. Hide a page the same way as Hide from report:

workspace.get_page("Scratch").exclude_from_report()
for status in workspace.report.pages:
    print(status.page.name, status.status, status.plot_count)

status is included, hidden, or no_series when no plot on the page has a series yet. Plots without series are left out of the document.

Choose each page's chart grid​

Each page uses the chart grid from Settings unless it has its own, both on screen and in its report sheets:

page = workspace.get_page("Voltages")
page.set_layout(rows=2, plots_per_row=3, auto_adjust_width=False)
page.reset_layout()  # follow Settings again

rows goes from 1 to 3 and plots_per_row from 1 to 4. With auto_adjust_width=True, the plots of an incomplete last row stretch to the page width.

Export the document​

pdf = workspace.report.export("output/fault-study.pdf", format="pdf")
word = workspace.report.export("output/fault-study.docx", format="docx")
print(pdf["page_count"], pdf["plot_count"], pdf["table_count"])

The format is always explicit: pdf or docx. Each plot is drawn like plot.export(...) at the size of its report cell. Phasor plots show each vector at the first time of its channels, as ESPlotter shows the plot when you open it. Exporting raises ValidationError without a title, and ExportError with the report page's warning when every page is hidden or no included plot has a series.

Complete headless example​

This example uses hilltop-fault_100ms.csv. Save it as fault_report.py beside the CSV file:

import os
import sys
from pathlib import Path

# Load the ESPlotter module supplied by ESPlotter Desktop on Windows.
sys.path.insert(0, os.path.join(os.environ["APPDATA"], "ESPlotter", "python-sdk"))
import esplotter as esp

output = Path("output")
output.mkdir(exist_ok=True)

workspace = esp.headless()
channel_file = workspace.open_file("hilltop-fault_100ms.csv")[0]
page = workspace.active_page
page.rename("HILLTOP 138")

voltage = page.create_plot(title="Voltage at HILLTOP 138")
voltage.add_series(channel_file.get_channel("VOLT 3104 HILLTOP 138 (pu)"))
voltage.add_interval_cursor(x1=0.0, x2=1.0)
angle = page.create_plot(title="Angle at HILLTOP 138")
angle.add_series(channel_file.get_channel("ANGL 3104 HILLTOP 138 (deg)"))

workspace.report.set(title="HILLTOP 138 fault study", introduction="Fault cleared after 100 ms.")
result = workspace.report.export(output / "fault-study.pdf", format="pdf")
print(result)
workspace.close()

Run python fault_report.py. It writes output/fault-study.pdf with the voltage figure, its interval-statistics table and the angle figure. No ESPlotter window needs to stay open.

Next steps​