Reports API

HTML and Markdown report generation.

Overview

from phased_array_systems.reports import (
    ReportConfig,
    HTMLReport,
    MarkdownReport,
)

Classes

ReportConfig dataclass

ReportConfig(title: str = 'Trade Study Report', description: str | None = None, author: str | None = None, include_summary: bool = True, include_pareto: bool = True, include_plots: bool = True, max_rows: int = 50, objectives: list[tuple[str, str]] = list(), key_metrics: list[str] = list())

Configuration for report generation.

ATTRIBUTE	DESCRIPTION
title	Report title TYPE: str
description	Optional report description TYPE: str | None
author	Optional author name TYPE: str | None
include_summary	Include summary statistics section TYPE: bool
include_pareto	Include Pareto frontier analysis TYPE: bool
include_plots	Include visualization plots TYPE: bool
max_rows	Maximum rows to show in tables (0 = all) TYPE: int
objectives	List of (metric, direction) for Pareto analysis TYPE: list[tuple[str, str]]
key_metrics	Metrics to highlight in summary TYPE: list[str]

HTMLReport

HTMLReport(config: ReportConfig | None = None)

Bases: ReportGenerator

Generate HTML reports from trade study results.

Initialize the HTML report generator.

PARAMETER	DESCRIPTION
config	Report configuration TYPE: ReportConfig | None DEFAULT: None

Source code in src/phased_array_systems/reports/html.py

def __init__(self, config: ReportConfig | None = None):
    """Initialize the HTML report generator.

    Args:
        config: Report configuration
    """
    super().__init__(config)

generate

generate(results: DataFrame) -> str

Generate HTML report content.

PARAMETER	DESCRIPTION
results	DataFrame with trade study results TYPE: DataFrame

RETURNS	DESCRIPTION
str	Complete HTML document as string

Source code in src/phased_array_systems/reports/html.py

def generate(self, results: pd.DataFrame) -> str:
    """Generate HTML report content.

    Args:
        results: DataFrame with trade study results

    Returns:
        Complete HTML document as string
    """
    metadata = self._get_metadata()
    stats = self._compute_summary_stats(results)
    columns = self._identify_columns(results)

    sections = []

    # Summary section
    if self.config.include_summary:
        sections.append(self._generate_summary_section(stats, columns))

    # Results table section
    sections.append(self._generate_table_section(results, columns))

    # Statistics section
    sections.append(self._generate_statistics_section(results, columns))

    return self._wrap_html(sections, metadata)

MarkdownReport

MarkdownReport(config: ReportConfig | None = None)

Bases: ReportGenerator

Generate Markdown reports from trade study results.

Initialize the Markdown report generator.

PARAMETER	DESCRIPTION
config	Report configuration TYPE: ReportConfig | None DEFAULT: None

Source code in src/phased_array_systems/reports/markdown.py

def __init__(self, config: ReportConfig | None = None):
    """Initialize the Markdown report generator.

    Args:
        config: Report configuration
    """
    super().__init__(config)

generate

generate(results: DataFrame) -> str

Generate Markdown report content.

PARAMETER	DESCRIPTION
results	DataFrame with trade study results TYPE: DataFrame

RETURNS	DESCRIPTION
str	Markdown document as string

Source code in src/phased_array_systems/reports/markdown.py

def generate(self, results: pd.DataFrame) -> str:
    """Generate Markdown report content.

    Args:
        results: DataFrame with trade study results

    Returns:
        Markdown document as string
    """
    metadata = self._get_metadata()
    stats = self._compute_summary_stats(results)
    columns = self._identify_columns(results)

    sections = []

    # Title and metadata
    sections.append(self._generate_header(metadata))

    # Summary section
    if self.config.include_summary:
        sections.append(self._generate_summary_section(stats, columns))

    # Results table section
    sections.append(self._generate_table_section(results, columns))

    # Statistics section
    sections.append(self._generate_statistics_section(results, columns))

    # Footer
    sections.append(self._generate_footer(metadata))

    return "\n\n".join(sections)

Usage Examples

HTML Report

from phased_array_systems.reports import HTMLReport, ReportConfig
import pandas as pd

# Load results
results = pd.read_parquet("results.parquet")

# Configure report
config = ReportConfig(
    title="Communications Array Trade Study",
    description="Analysis of array configurations for X-band link",
    author="Engineering Team",
    version="1.0",
)

# Generate and save
report = HTMLReport(config)
content = report.generate(results)
report.save(content, "report.html")

Markdown Report

from phased_array_systems.reports import MarkdownReport, ReportConfig

config = ReportConfig(title="Trade Study Summary")
report = MarkdownReport(config)
content = report.generate(results)
report.save(content, "report.md")

Report Configuration

config = ReportConfig(
    title="Q4 Array Trade Study",
    description="""
    Systematic exploration of phased array configurations
    for 100 km X-band communications link.
    """,
    author="RF Engineering",
    version="2.1",
)

Report Contents

Reports automatically include:

Executive Summary

• Total cases evaluated
• Feasible design count and percentage
• Pareto-optimal design count
• Key metric statistics

Requirements Verification

• Pass/fail summary by requirement
• Overall compliance rate
• Margin statistics

Top Designs

• Ranked Pareto-optimal designs
• Key metrics for each design
• Configuration parameters

Statistics

• Metric distributions (min, max, mean, std)
• Variable ranges
• Correlation highlights

Customization

Extending Reports

class CustomHTMLReport(HTMLReport):
    def generate(self, results):
        html = super().generate(results)

        # Add custom section
        custom = "<section><h2>Custom Analysis</h2>...</section>"
        html = html.replace("</body>", f"{custom}</body>")

        return html

Adding Figures

import base64
from io import BytesIO

# Generate figure
fig = pareto_plot(results, x="cost_usd", y="eirp_dbw")

# Convert to base64
buffer = BytesIO()
fig.savefig(buffer, format='png', dpi=150)
buffer.seek(0)
img_data = base64.b64encode(buffer.getvalue()).decode()

# Embed in HTML
img_html = f'<img src="data:image/png;base64,{img_data}" alt="Pareto">'

CLI Usage

# HTML report (default)
pasys report results.parquet -o report.html

# Markdown report
pasys report results.parquet --format markdown -o report.md

# With title
pasys report results.parquet --title "Q4 Analysis"

See Also

• User Guide: Reports
• CLI: report
• Visualization API