🛠️ report_builder¶

This module defines the ReportBuilder class, which orchestrates the generation of Exploratory Data Analysis (EDA) reports, including both textual and chart-based sections. It provides a flexible API to add, include, exclude, and reorder report sections and charts, and to output the report as a JSON file.

Classes and Data Structures¶

SectionContent¶

class owlmix.reporting.report_builder.SectionContent¶

Data class to represent the content of a report section.

Parameters:

data (Dict[str, Any]) – The data associated with the section, which can include analysis results, metrics, etc.
chart (Dict[str, Any]) – The chart information for the section, which can include the chart type, data for plotting, and any relevant metadata.

@dataclass
class SectionContent:
      data: Dict[str, Any]
      chart: Dict[str, Any]

ReportBuilder¶

class owlmix.reporting.report_builder.ReportBuilder(df: pd.DataFrame, target_col: str, date_col: str, config: ConfigBuilder = ConfigBuilder)¶

Class to build a comprehensive EDA report with multiple sections, including both textual data and charts.

Parameters:

df (pd.DataFrame) – The input DataFrame containing the data to be analyzed.
target_col (str) – The name of the target column in the DataFrame for analysis.
date_col (str) – The name of the date column in the DataFrame for time series analysis.
config (ConfigBuilder) – An instance of ConfigBuilder to manage configuration settings for the report.

Attributes:

sections (OrderedDict[str, SectionContent]): Stores the sections of the report, where keys are section names and values are SectionContent instances.
_report_data (Optional[Dict[str, Any]]): Cached report data after building.

Methods:

add_section(name: str, data: Dict[str, Any], chart: Dict[str, Any] | None = None) → Self¶

Adds a section to the report with the given name, data, and optional chart information.

Parameters:

name (str) – The name of the section to add.
data (Dict[str, Any]) – The data associated with the section.
chart (Optional[Dict[str, Any]]) – The chart information for the section (optional).

Returns:

The current instance of the ReportBuilder.

add_section_by_name(name: str) → Self¶

Adds a section to the report by looking up a registered section builder function by name and executing it.

Parameters:: name (str) – The name of the section to add.
Returns:: The current instance of the ReportBuilder.
Return type:: ReportBuilder
Raises:: ValueError – If no section builder is registered for the given name.

add_all_sections(verbose: bool = False) → Self¶

Adds all registered sections to the report by iterating through the SECTION_BUILDERS registry and adding each section by name.

Parameters:: verbose (bool) – If True, prints the name of each section as it is added to the report. Default is False.
Returns:: The current instance of the ReportBuilder.
Return type:: ReportBuilder

include_sections(section_names: list[str | SectionEnum]) → Self¶

Keep only the specified sections in the report.

Parameters:: section_names (list[Union[str, SectionEnum]]) – List of section names or SectionEnum members to include.
Returns:: The current instance of the ReportBuilder.
Return type:: ReportBuilder

exclude_sections(section_names: list[str | SectionEnum]) → Self¶

Excludes specified sections from the report by removing them from the sections dictionary.

Parameters:: section_names (list[Union[str, SectionEnum]]) – List of section names or SectionEnum members to be excluded from the report.
Returns:: The current instance of the ReportBuilder.
Return type:: ReportBuilder

build(output_path: str | None = None) → Dict[str, Any]¶

Builds the report data structure, which can be output as JSON or used for further processing.

Parameters:: output_path (Optional[str]) – The path where the report should be saved as a JSON file. If None, the report is not saved to a file.
Returns:: A dictionary representing the report data, including sections and their associated data and charts.
Return type:: Dict[str, Any]

Example Output:

{
    "sections": {
        "section_name": {
            "data": { ... },
            "chart": { ... }
        },
        ...
    }
}

image_to_base64(image_path: str) → str¶

Convert an image file to a base64 string for embedding in HTML.

Parameters:: image_path (str) – Path to the image file.
Returns:: Base64-encoded image string with MIME type, or empty string if not found.
Return type:: str

save(outfile_name: str | None = None) → None¶

Save the generated report as a JSON file.

Parameters:: outfile_name (Optional[str]) – The name of the output JSON file. If None, defaults to “report.json”.
Returns:: None
Return type:: None

Usage Example¶

import pandas as pd
from owlmix.reporting.report_builder import ReportBuilder

df = pd.read_csv("data.csv")
builder = ReportBuilder(df, target_col="target", date_col="date")
builder.add_all_sections()
builder.save("my_report.json")

Design Notes¶

Sections are registered via the SECTION_BUILDERS registry and can be added by name.
The report structure is designed for easy serialization to JSON and further rendering (e.g., to HTML).
Images can be embedded in the report as base64 strings for portability.

Dependencies¶

pandas
base64
json
dataclasses
collections
typing
ConfigBuilder from owlmix.config.config_builder

Back to Home