Report Utils

Report Utils#

class Hydrological_model_validator.Report.report_utils.MyDocTemplate(filename, **kwargs)[source]#

Bases: SimpleDocTemplate

Custom document template that extends ReportLab’s SimpleDocTemplate.

This class overrides the afterFlowable method to detect headings in the flowables added to the document. When a heading with an outlineLevel attribute is encountered, it registers the heading with the Table of Contents (TOC) system by notifying the TOCEntry event. This enables automatic building of the Table of Contents with correct page numbers.

_headings#

Internal list to keep track of headings added (optional use).

Type:

list

afterFlowable(flowable)[source]#

Hook method called by ReportLab after each flowable is processed.

Checks if the flowable has an ‘outlineLevel’ attribute. If so, it considers the flowable as a heading and notifies the TOC system with the heading level, text content, and current page number.

This notification allows the Table of Contents to be built dynamically during PDF generation.

Parameters:

flowable (Flowable) – The flowable object just added to the document.

class Hydrological_model_validator.Report.report_utils.PDFReportBuilder(pdf_path)[source]#

Bases: object

A builder class for creating PDF reports using ReportLab.

This class manages the document structure, styles, and content to generate professional-looking PDF reports with title pages, table of contents, and formatted sections.

pdf_path#

Path where the PDF will be saved.

Type:

str

styles#

ReportLab stylesheet object for styling text.

Type:

StyleSheet1

story#

List of flowables representing the PDF content.

Type:

list

toc#

Table of contents flowable.

Type:

TableOfContents

add_heading(text, level=0)[source]#

Add a heading paragraph to the story with the specified level.

This method creates a paragraph with either Heading1 or Heading2 style, assigns a unique bookmark name, and sets outlineLevel and bookmark attributes to enable navigation and inclusion in the Table of Contents.

Parameters:

  • text (str) – The heading text.

  • level (int) – Heading level (0 for main heading, 1 for subheading).

build_title_page(title='Model Evaluation Report', subtitle='Comprehensive model performance evaluation', author='Alessandro Gozzoli', organization='Alma Mater Studiorum - Università di Bologna', email='alessandro.gozzoli4@studio.unibo.it', cellphone='', logo_path=None, package_name='hydrological_model_validator')[source]#

Build and append the title page content to the story.

This method resets the current story content and adds styled paragraphs including the title, subtitle, date, author info, version, and an optional logo image. Visual separators and spacing are also added for professional layout.

Parameters:

  • title (str) – Main report title text.

  • subtitle (str) – Subtitle or descriptive text.

  • author (str) – Name of the report author.

  • organization (str) – Affiliated organization or institution.

  • email (str) – Contact email address.

  • cellphone (str) – Contact phone number (optional).

  • logo_path (str or None) – Path to an image file for logo inclusion (optional).

  • package_name (str) – Package name for version info lookup.

Side Effects:

Clears and appends multiple flowables (paragraphs, images, spacers, lines) to the internal story list representing the PDF content.

build_toc()[source]#

Build and append a styled Table of Contents page to the story.

This method adds a title with custom styling, a horizontal line, and the TableOfContents flowable configured in the constructor. A page break is appended at the end to separate the TOC from following content.

Side Effects:

Appends flowables to the internal story list representing the PDF content.

save()[source]#
class Hydrological_model_validator.Report.report_utils.PositionedTable(flowable, x_offset=0, y_offset=0)[source]#

Bases: Flowable

A wrapper Flowable that allows precise positioning of another Flowable (e.g., a Table) by applying horizontal and vertical offsets when drawn.

This is useful when you need to control the exact position of a table or any flowable element on the canvas, beyond the normal flow layout.

flowable#

The flowable object to be positioned.

Type:

Flowable

x_offset#

Horizontal shift from the current origin in points.

Type:

float

y_offset#

Vertical shift from the current origin in points.

Type:

float

draw()[source]#

Draw the wrapped flowable at the specified offsets.

The canvas state is saved and restored to avoid affecting other drawings. The canvas origin is translated by the given offsets, then the flowable is drawn at the translated origin (0, 0), effectively positioning it precisely relative to the original drawing point.

wrap(availWidth, availHeight)[source]#

Calculate the space required by the wrapped flowable.

Delegates the wrap calculation to the wrapped flowable, since the positioning offsets do not affect the required size.

Parameters:

  • availWidth (float) – Available width for the flowable.

  • availHeight (float) – Available height for the flowable.

Returns:

The size needed by the wrapped flowable.

Return type:

(width, height)

class Hydrological_model_validator.Report.report_utils.RotatedImage(img_path, frame_width=456.0, frame_height=636.0, margin=7.2, header_height=18.0, custom_offset_y=None)[source]#

Bases: Flowable

A Flowable that loads an image from disk and draws it rotated by 90 degrees within a fixed frame size, scaling the image to fit while preserving aspect ratio.

The image is rotated clockwise by 90 degrees and positioned inside a rectangular frame defined by frame_width and frame_height, with margins and optional vertical offset.

img_path#

Path to the image file.

Type:

str

frame_width#

Width of the frame where the image is drawn (in points).

Type:

float

frame_height#

Height of the frame where the image is drawn (in points).

Type:

float

margin#

Margin around the image inside the frame (in points).

Type:

float

header_height#

Additional space reserved for a header above the image (in points).

Type:

float

custom_offset_y#

Optional custom vertical offset for positioning.

Type:

float or None

orig_width#

Original width of the image in pixels.

Type:

int

orig_height#

Original height of the image in pixels.

Type:

int

draw_width#

Width of the scaled image for drawing (in points).

Type:

float

draw_height#

Height of the scaled image for drawing (in points).

Type:

float

draw()[source]#

Draw the rotated image on the canvas.

The image is rotated by 90 degrees clockwise and translated so that it fits centered within the frame, considering margins and optional vertical offset.

The canvas state is saved and restored to prevent side effects on subsequent drawings.

wrap(availWidth, availHeight)[source]#

Calculate the space required by the rotated image with margins and header.

The required width is the scaled image width plus horizontal margins. The required height is the scaled image height plus vertical margins and header space.

Parameters:

  • availWidth (float) – Available width for layout (ignored here).

  • availHeight (float) – Available height for layout (ignored here).

Returns:

(required width, required height) for layout.

Return type:

tuple

Hydrological_model_validator.Report.report_utils.add_efficiency_pages(pdf, efficiency_df, plot_titles, plots_path)[source]#

Adds multiple pages to the PDF, each with a section for an efficiency metric: a heading, the corresponding plot image, a monthly values table, and a total value table.

Parameters:

  • pdf – PDF builder object with .story, .add_heading, and .styles.

  • efficiency_df – pandas DataFrame indexed by metric keys, columns [‘Total’, month names].

  • plot_titles – dict mapping metric_key to human-readable title.

  • plots_path – Path to directory containing plot images named ‘<metric_key>.png’.

Hydrological_model_validator.Report.report_utils.add_multiple_images_grid(pdf, img_paths, section_title, columns=2, rows=None, max_width=216.0, spacing=14.4)[source]#

Add multiple images to the PDF in a neat grid layout with optional limits on rows and columns.

Parameters:

  • pdf (PDF builder object) – The PDF document builder that supports .story (list of flowables) and .add_heading.

  • img_paths (list of str or pathlib.Path) – List of file paths to images to be added.

  • section_title (str) – Title text displayed above the image grid.

  • columns (int, optional) – Number of columns in the grid (default is 2).

  • rows (int or None, optional) – Maximum number of rows to include; if None, include all images.

  • max_width (float, optional) – Maximum width of each image in points (default 3 inches).

  • spacing (float, optional) – Vertical spacing above and below the image grid (default 0.2 inch).

Returns:

Modifies the pdf object in place by appending image grid and spacing flowables.

Return type:

None

Hydrological_model_validator.Report.report_utils.add_multiple_rotated_images_grid(pdf, img_paths, cols=2, section_title=None, margin=18.0, frame_width=456.0, frame_height=636.0, header_height=36.0)[source]#

Adds a grid of rotated images to the PDF, arranging them in specified columns, centered within a defined frame size, with optional section title.

Parameters:

  • pdf (PDF builder object) – The PDF document builder supporting .story and .add_heading.

  • img_paths (list of str or pathlib.Path) – Paths to images that will be rotated and added.

  • cols (int, optional) – Number of columns in the grid (default 2).

  • section_title (str or None, optional) – Optional heading displayed above the image grid.

  • margin (float, optional) – Margin (in points) around each rotated image (default 0.25 inch).

  • frame_width (float, optional) – Width of the frame container for the grid (default 456 points).

  • frame_height (float, optional) – Height of the frame container for the grid (default 636 points).

  • header_height (float, optional) – Space allocated for header above the grid (default 0.5 inch).

Returns:

Appends positioned rotated images grid and page break to pdf.story.

Return type:

None

Hydrological_model_validator.Report.report_utils.add_plot_to_pdf(pdf, img_path, section_title, width=432.0)[source]#

Add a titled image section to a PDF document with proper spacing and page break.

This function inserts a section heading followed by an image into a PDF report. It adjusts the image size to a specified width while maintaining its aspect ratio. Spacers are added before and after the image to improve layout, and a page break is appended after the image to separate sections cleanly.

Parameters:

  • pdf (ReportLab PDF document object) – The PDF document to which the image and heading are added. Must support methods like add_heading and have a story attribute (a list of flowables).

  • img_path (str or pathlib.Path) – Path to the image file to insert into the PDF.

  • section_title (str) – Title text to be added as a heading before the image.

  • width (float, optional) – Desired width of the image in points (default is 6 inches).

Returns:

The function modifies the PDF object in-place by adding flowables to its story.

Return type:

None

Example

>>> add_plot_to_pdf(pdf, "plots/plot1.png", "Section 1: Overview")
Hydrological_model_validator.Report.report_utils.add_rotated_image_page(pdf, img_path, section_title=None, custom_offset_y=None)[source]#

Add a page with a rotated image to the PDF document, optionally with a section heading.

This function inserts an optional section heading followed by a rotated image that fits a predefined frame size. The image is rotated 90 degrees clockwise and positioned with optional vertical offset adjustment. A page break is added after the image to separate it from subsequent content.

Parameters:

  • pdf (ReportLab PDF document object) – The PDF document to which the rotated image and optional heading are added. Must support add_heading and have a story attribute (list of flowables).

  • img_path (str or pathlib.Path) – Path to the image file to be added, which will be rotated and scaled to fit.

  • section_title (str, optional) – Title text to add as a heading before the image. If None, no heading is added.

  • custom_offset_y (float, optional) – Custom vertical offset for positioning the rotated image. Overrides default positioning.

Returns:

Modifies the PDF object in-place by appending flowables to its story.

Return type:

None

Example

>>> add_rotated_image_page(pdf, "figures/diagram.png", "Rotated Diagram")
Hydrological_model_validator.Report.report_utils.add_seasonal_scatter_page(pdf, main_img_path, sub_img_paths, section_title='Seasonal Scatterplots')[source]#

Adds a page to the PDF with a main seasonal scatterplot image on top, followed by a 2x2 grid of smaller subplots below.

Parameters:

  • pdf – PDF builder object with .story and .add_heading.

  • main_img_path – Path to the main seasonal plot image.

  • sub_img_paths – List of 4 image paths for the 2x2 grid of subplots.

  • section_title – Title of the page section.

Hydrological_model_validator.Report.report_utils.add_tables_page(pdf, tables_dict, section_title='Summary Tables', columns=2, rows=None, cell_padding=6, spacing=14.4, max_table_width=216.0)[source]#

Add a page with multiple tables arranged in a grid layout to the PDF document.

This function creates a grid of summary tables, each with a title and metric-value pairs. The tables are arranged in a specified number of columns per row, with styling applied for readability. If a section title is provided, it is added at the top. The function handles incomplete rows by padding with empty spaces. A horizontal separator line is added after the first row if multiple rows exist. Finally, a page break is appended.

Parameters:

  • pdf (PDF document object) – PDF builder object which must have .story (a list of flowables) and .add_heading method.

  • tables_dict (dict of str to dict of str to float) – Dictionary mapping each table title (str) to a dictionary of metric names and values.

  • section_title (str, optional) – Title for the entire page section containing the tables. Default is “Summary Tables”.

  • columns (int, optional) – Number of tables to display per row. Default is 2.

  • rows (int or None, optional) – Optional maximum number of rows to display. If None, all tables are shown.

  • cell_padding (int, optional) – Padding inside each table cell in points. Default is 6.

  • spacing (float, optional) – Vertical spacing between elements, in points. Default is 0.2 inch.

  • max_table_width (float, optional) – Maximum width for each individual table in points. Default is 3.0 inch.

Returns:

The function modifies the pdf object in place by appending flowables.

Return type:

None

Example

>>> tables = {
...     "Correlation Metrics": {"NSE": 0.85, "RMSE": 1.23},
...     "Efficiency Metrics": {"KGE": 0.90, "R2": 0.88},
... }
>>> add_tables_page(pdf, tables, columns=2)
Contents