Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.reporting.generate_qc_report

brainprep.reporting.generate_qc_report(title, version, date, data)[source]

Generate a quality control (QC) report as an interactive HTML document.

This function compiles visual and tabular data into a structured HTML report using a predefined template. It is useful for documenting and reviewing steps in a data processing workflow.

Parameters:
titlestr

The title displayed at the top of the report.

versionstr

Version identifier for the report or associated software.

datestr

Timestamp indicating when the report was generated.

datalist[dict | File]

A list of dictionaries or JSON files containing dictionaries, each representing a workflow step. Each dictionary must contain the following keys:

  • name : str - Title of the step.

  • summary : str - A HTML string to be be displayed.

  • images : dict | None - A dictionary containing configurations for image plots. If provided, the dictionary must follow this specific schema.

  • carousels : dict | None - A dictionary containing configurations for a carousel plots. If provided, the dictionary must follow this specific schema.

  • tables : dict | None - A dictionary containing configurations for table plots. If provided, the dictionary must follow this specific schema.

  • scatters : dict | None - A dictionary containing configurations for interactive scatter plots. If provided, the dictionary must follow this specific schema.

Returns:
reportHTMLReport

An instance of HTMLReport containing the rendered HTML content.

Notes

Images are converted to base64 for inline embedding.

Tables are rendered as HTML using dataframe_to_html.

The images dictionary must follow this specific schema:

  • “chart_name”:

    • “record”: A list of strings representing the images to display.

    • “overlays”: A list of strings or None, representing the images to show over the main images. This can also be None.

    • “labels”: A list of strings or None, representing the text labels for each image. This can also be None.

The carousels dictionary must follow this specific schema:

  • “chart_name”:

    • “record”: A list of strings representing the images to include in the carousel.

    • “labels”: A list of strings or None, representing the text labels for each image. This can also be None.

The tables dictionary must follow this specific schema:

  • “chart_name”:

    • “record”: A list of DataFrames representing the tabular data to include.

    • “labels”: A list of strings or None, representing the text labels for each table. This can also be None.

The scatters dictionary must follow this specific schema:

  • “chart_name”:

    • “record”: A list of dictionaries representing the points in the scatter plot. Each dictionary must contain the keys ‘x’, ‘y’, and ‘img’.

    • “x_label”: A string representing the text label displayed along the X-axis of the scatter plot.

    • “y_label”: A string representing the text label displayed along the Y-axis of the scatter plot.

    • “with_img”: A boolean indicating whether to display images associated with each point. If False, only the points will be displayed.

Examples

>>> from pathlib import Path
>>> from pandas import DataFrame
>>>
>>> data = [{
...     "name": "Step 1",
...     "content": Path("/tmp/image1.png"),
...     "overlay": Path("/tmp/image1_overlay.png"),
...     "tables": DataFrame({"A": [1, 2], "B": [3, 4]})
... }]
>>> report = generate_qc_report(
...     title="QC Summary",
...     docstring="Overview of preprocessing steps.",
...     version="1.0",
...     date="2025-10-03",
...     data=data
... ) 
>>> report.save_as_html("/tmp/qc_report.html")

Examples using brainprep.reporting.generate_qc_report

HTML reporting

HTML reporting