oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/reporting/multichannel.py

@@ -0,0 +1,296 @@
+"""Multi-channel report generation for TraceKit.
+
+This module provides utilities for generating reports across multiple channels
+with channel comparison and aggregation.
+
+
+Example:
+    >>> from oscura.reporting.multichannel import generate_multichannel_report
+    >>> report = generate_multichannel_report(channel_results, "multi_report.pdf")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from oscura.reporting.core import Report, ReportConfig, Section
+from oscura.reporting.tables import create_measurement_table
+
+
+def generate_multichannel_report(
+    channel_results: dict[str, dict[str, Any]],
+    *,
+    title: str = "Multi-Channel Analysis Report",
+    compare_channels: bool = True,
+    aggregate_statistics: bool = True,
+    individual_sections: bool = True,
+    **kwargs: Any,
+) -> Report:
+    """Generate report for multi-channel analysis.
+
+    Args:
+        channel_results: Dictionary mapping channel name to results.
+        title: Report title.
+        compare_channels: Include channel comparison section.
+        aggregate_statistics: Include aggregate statistics across channels.
+        individual_sections: Include individual channel sections.
+        **kwargs: Additional report configuration options.
+
+    Returns:
+        Multi-channel Report object.
+
+    References:
+        REPORT-007
+    """
+    config = ReportConfig(title=title, **kwargs)
+    report = Report(config=config)
+
+    # Add executive summary
+    summary_content = _generate_multichannel_summary(channel_results)
+    report.add_section("Executive Summary", summary_content, level=1)
+
+    # Add aggregate statistics
+    if aggregate_statistics:
+        stats_section = _create_aggregate_statistics_section(channel_results)
+        report.sections.append(stats_section)
+
+    # Add channel comparison
+    if compare_channels and len(channel_results) > 1:
+        comparison_section = _create_channel_comparison_section(channel_results)
+        report.sections.append(comparison_section)
+
+    # Add individual channel sections
+    if individual_sections:
+        for channel_name, results in channel_results.items():
+            channel_section = _create_channel_section(channel_name, results)
+            report.sections.append(channel_section)
+
+    return report
+
+
+def _generate_multichannel_summary(channel_results: dict[str, dict[str, Any]]) -> str:
+    """Generate summary for multi-channel report."""
+    summary_parts = []
+
+    total_channels = len(channel_results)
+    summary_parts.append(f"Analyzed {total_channels} channel(s).")
+
+    # Aggregate pass/fail across channels
+    total_tests = 0
+    total_passed = 0
+
+    for results in channel_results.values():
+        total_tests += results.get("total_count", 0)
+        total_passed += results.get("pass_count", 0)
+
+    if total_tests > 0:
+        total_failed = total_tests - total_passed
+        summary_parts.append(
+            f"\nOverall: {total_passed}/{total_tests} tests passed "
+            f"({total_passed / total_tests * 100:.1f}% pass rate)."
+        )
+
+        if total_failed > 0:
+            summary_parts.append(f"{total_failed} test(s) failed across all channels.")
+
+    # Channel-specific summary
+    failed_channels = []
+    for channel_name, results in channel_results.items():
+        pass_count = results.get("pass_count", 0)
+        total_count = results.get("total_count", 0)
+        if total_count > 0 and pass_count < total_count:
+            failed_channels.append(channel_name)
+
+    if failed_channels:
+        summary_parts.append(f"\nChannels with failures: {', '.join(failed_channels)}")
+    else:
+        summary_parts.append("\nAll channels passed all tests.")
+
+    return "\n".join(summary_parts)
+
+
+def _create_aggregate_statistics_section(
+    channel_results: dict[str, dict[str, Any]],
+) -> Section:
+    """Create aggregate statistics section across all channels."""
+    # Collect all measurement parameters
+    all_params = set()
+    for results in channel_results.values():
+        if "measurements" in results:
+            all_params.update(results["measurements"].keys())
+
+    # Build aggregate table
+    import numpy as np
+
+    headers = ["Parameter", "Min", "Mean", "Max", "Std Dev"]
+    rows = []
+
+    for param in sorted(all_params):
+        values = []
+        unit = ""
+
+        for results in channel_results.values():
+            if "measurements" in results and param in results["measurements"]:
+                meas = results["measurements"][param]
+                if "value" in meas and meas["value"] is not None:
+                    values.append(meas["value"])
+                    if not unit and "unit" in meas:
+                        unit = meas["unit"]
+
+        if values:
+            from oscura.reporting.formatting import NumberFormatter
+
+            formatter = NumberFormatter()
+            rows.append(
+                [
+                    param,
+                    formatter.format(np.min(values), unit),
+                    formatter.format(np.mean(values), unit),
+                    formatter.format(np.max(values), unit),
+                    formatter.format(np.std(values), unit),
+                ]
+            )
+
+    table = {"type": "table", "headers": headers, "data": rows}
+
+    return Section(
+        title="Aggregate Statistics",
+        content=[table],
+        level=1,
+        visible=True,
+    )
+
+
+def _create_channel_comparison_section(
+    channel_results: dict[str, dict[str, Any]],
+) -> Section:
+    """Create channel-to-channel comparison section."""
+    from oscura.reporting.formatting import NumberFormatter
+
+    formatter = NumberFormatter()
+
+    # Build comparison table
+    channel_names = list(channel_results.keys())
+    headers = ["Parameter", *channel_names]
+
+    # Collect all parameters
+    all_params = set()
+    for results in channel_results.values():
+        if "measurements" in results:
+            all_params.update(results["measurements"].keys())
+
+    rows = []
+    for param in sorted(all_params):
+        row = [param]
+
+        for channel_name in channel_names:
+            results = channel_results[channel_name]
+            if "measurements" in results and param in results["measurements"]:
+                meas = results["measurements"][param]
+                value = meas.get("value")
+                unit = meas.get("unit", "")
+                if value is not None:
+                    row.append(formatter.format(value, unit))
+                else:
+                    row.append("-")
+            else:
+                row.append("-")
+
+        rows.append(row)
+
+    table = {"type": "table", "headers": headers, "data": rows}
+
+    return Section(
+        title="Channel Comparison",
+        content=[table],
+        level=1,
+        visible=True,
+    )
+
+
+def _create_channel_section(
+    channel_name: str,
+    results: dict[str, Any],
+) -> Section:
+    """Create individual channel section."""
+    subsections = []
+
+    # Channel summary
+    summary_parts = []
+    if "pass_count" in results and "total_count" in results:
+        pass_count = results["pass_count"]
+        total = results["total_count"]
+        summary_parts.append(
+            f"{pass_count}/{total} tests passed ({pass_count / total * 100:.1f}% pass rate)."
+        )
+
+    # Measurements
+    if "measurements" in results:
+        table = create_measurement_table(results["measurements"], format="dict")
+        subsections.append(
+            Section(
+                title="Measurements",
+                content=[table],
+                level=3,
+                visible=True,
+            )
+        )
+
+    return Section(
+        title=f"Channel: {channel_name}",
+        content="\n".join(summary_parts) if summary_parts else "",
+        level=2,
+        visible=True,
+        subsections=subsections,
+    )
+
+
+def create_channel_crosstalk_section(
+    crosstalk_results: dict[str, Any],
+) -> Section:
+    """Create channel crosstalk analysis section.
+
+    Args:
+        crosstalk_results: Crosstalk analysis results between channels.
+
+    Returns:
+        Crosstalk Section object.
+
+    References:
+        REPORT-007
+    """
+    from oscura.reporting.formatting import NumberFormatter
+
+    formatter = NumberFormatter()
+
+    if "crosstalk_matrix" in crosstalk_results:
+        matrix = crosstalk_results["crosstalk_matrix"]
+        channels = crosstalk_results.get("channels", [])
+
+        headers = ["Aggressor → Victim", *channels]
+        rows = []
+
+        for i, aggressor in enumerate(channels):
+            row = [aggressor]
+            for j, _victim in enumerate(channels):
+                if i == j:
+                    row.append("-")
+                else:
+                    crosstalk_db = matrix[i][j]
+                    row.append(formatter.format(crosstalk_db, "dB"))
+            rows.append(row)
+
+        table = {"type": "table", "headers": headers, "data": rows}
+        content = [
+            "Channel-to-channel crosstalk measurements:\n",
+            table,
+        ]
+    else:
+        content = "No crosstalk analysis available."  # type: ignore[assignment]
+
+    return Section(
+        title="Channel Crosstalk Analysis",
+        content=content,
+        level=2,
+        visible=True,
+    )

oscura/reporting/output.py

@@ -0,0 +1,379 @@
+"""Output management for comprehensive analysis reports.
+
+This module provides directory structure and file management for analysis
+report outputs, including plots, JSON/YAML data exports, and logs.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import yaml
+
+from oscura.reporting.config import AnalysisDomain  # noqa: TC001
+
+
+def _sanitize_for_serialization(obj: Any, max_depth: int = 10) -> Any:
+    """Convert non-serializable objects for JSON/YAML output.
+
+    Handles generators, numpy arrays, and other problematic types
+    that can appear in analysis results.
+
+    Args:
+        obj: Object to sanitize.
+        max_depth: Maximum recursion depth to prevent infinite loops.
+
+    Returns:
+        Serialization-safe version of the object.
+    """
+    import types
+
+    from oscura.core.types import DigitalTrace, TraceMetadata, WaveformTrace
+
+    if max_depth <= 0:
+        return "<max depth exceeded>"
+
+    try:
+        # Don't sanitize TraceKit types - let the JSONEncoder handle them
+        if isinstance(obj, WaveformTrace | DigitalTrace | TraceMetadata):
+            return obj
+        if isinstance(obj, dict):
+            # Sanitize both keys and values, convert non-string keys to strings
+            sanitized = {}
+            for k, v in obj.items():
+                # Convert bytes keys to hex strings
+                if isinstance(k, bytes):
+                    k = f"0x{k.hex()}"
+                # Convert other non-string keys to strings
+                elif not isinstance(k, str | int | float | bool | type(None)):
+                    k = str(k)
+                sanitized[k] = _sanitize_for_serialization(v, max_depth - 1)
+            return sanitized
+        elif isinstance(obj, list | tuple):
+            return [_sanitize_for_serialization(item, max_depth - 1) for item in obj]
+        elif isinstance(obj, types.GeneratorType):
+            # Convert generators to lists, but catch errors
+            try:
+                items = list(obj)
+                return [_sanitize_for_serialization(item, max_depth - 1) for item in items]
+            except Exception:
+                # Return None for incompatible generators (cleaner than error string)
+                return None
+        elif isinstance(obj, np.ndarray):
+            # Limit large arrays
+            if obj.size > 10000:
+                return f"<ndarray shape={obj.shape} dtype={obj.dtype}>"
+            return obj.tolist()
+        elif isinstance(obj, np.generic):
+            # Catch all numpy scalar types (int, float, complex, bool, str, etc.)
+            # This includes np.integer, np.floating, np.bool_, np.complexfloating, etc.
+            return obj.item()
+        elif isinstance(obj, np.integer | np.floating):
+            # Redundant but kept for clarity
+            return obj.item()
+        elif isinstance(obj, np.bool_):
+            # Redundant but kept for clarity
+            return bool(obj)
+        elif isinstance(obj, float):
+            # Handle Python float inf/nan (not caught by JSONEncoder.default)
+            import math
+
+            if math.isinf(obj) or math.isnan(obj):
+                return None
+            return obj
+        elif isinstance(obj, complex):
+            # Handle complex numbers with inf/nan components
+            import math
+
+            if (
+                math.isinf(obj.real)
+                or math.isnan(obj.real)
+                or math.isinf(obj.imag)
+                or math.isnan(obj.imag)
+            ):
+                return None
+            return {"real": obj.real, "imag": obj.imag}
+        elif isinstance(obj, bytes):
+            # Limit large byte sequences
+            if len(obj) > 1000:
+                return f"<bytes len={len(obj)}>"
+            return obj.hex()
+        elif hasattr(obj, "__dict__") and not isinstance(obj, type):
+            # Convert dataclasses and objects to dicts
+            try:
+                return {
+                    k: _sanitize_for_serialization(v, max_depth - 1)
+                    for k, v in obj.__dict__.items()
+                }
+            except Exception:
+                return str(obj)
+        elif callable(obj):
+            return f"<callable: {getattr(obj, '__name__', str(obj))}>"
+        else:
+            # Try to convert to string as last resort
+            try:
+                return obj
+            except Exception:
+                return str(obj)
+    except Exception as e:
+        return f"<error: {type(e).__name__}: {str(e)[:50]}>"
+
+
+class OutputManager:
+    """Manages output directory structure and file operations for analysis reports.
+
+    Creates timestamped output directories with organized subdirectories for
+    different types of analysis outputs (plots, data files, logs, errors).
+
+    Attributes:
+        root: Root directory path for this analysis output.
+        timestamp: Timestamp for this output session.
+        timestamp_str: Formatted timestamp string.
+
+    Requirements:
+    """
+
+    def __init__(
+        self,
+        base_dir: Path,
+        input_name: str,
+        timestamp: datetime | None = None,
+    ) -> None:
+        """Initialize output manager.
+
+        Args:
+            base_dir: Base directory for all outputs.
+            input_name: Name of the input file/dataset being analyzed.
+            timestamp: Timestamp for this session (defaults to now).
+
+        Examples:
+            >>> manager = OutputManager(Path("/output"), "signal_data")
+            >>> manager.root.name
+            '20260101_120000_signal_data_analysis'
+        """
+        self._timestamp = timestamp or datetime.now()
+        self._timestamp_str = self._timestamp.strftime("%Y%m%d_%H%M%S")
+
+        # Create timestamped directory name
+        dirname = f"{self._timestamp_str}_{input_name}_analysis"
+        self._root = base_dir / dirname
+
+    @property
+    def root(self) -> Path:
+        """Root directory path for this analysis output."""
+        return self._root
+
+    @property
+    def timestamp(self) -> datetime:
+        """Timestamp for this output session."""
+        return self._timestamp
+
+    @property
+    def timestamp_str(self) -> str:
+        """Formatted timestamp string (YYYYMMDD_HHMMSS)."""
+        return self._timestamp_str
+
+    def create(self) -> Path:
+        """Create output directory structure.
+
+        Creates the root directory and standard subdirectories:
+        - plots/: Visualization outputs
+        - errors/: Error logs and diagnostics
+        - logs/: Analysis logs
+        - input/: Input file copies/metadata
+
+        Returns:
+            Path to the created root directory.
+
+        Note:
+            This method is idempotent - calling it multiple times is safe.
+
+        Requirements:
+
+        Examples:
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> root = manager.create()
+            >>> (root / "plots").exists()
+            True
+        """
+        self._root.mkdir(parents=True, exist_ok=True)
+
+        # Create standard subdirectories
+        subdirs = ["plots", "errors", "logs", "input"]
+        for subdir in subdirs:
+            (self._root / subdir).mkdir(exist_ok=True)
+
+        return self._root
+
+    def create_domain_dir(self, domain: AnalysisDomain) -> Path:
+        """Create and return domain-specific subdirectory.
+
+        Creates a subdirectory for organizing outputs from a specific
+        analysis domain (e.g., spectral/, digital/, jitter/).
+
+        Args:
+            domain: Analysis domain.
+
+        Returns:
+            Path to the created domain directory.
+
+        Requirements:
+
+        Examples:
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> manager.create()
+            >>> domain_dir = manager.create_domain_dir(AnalysisDomain.SPECTRAL)
+            >>> domain_dir.name
+            'spectral'
+        """
+        domain_dir = self._root / domain.value
+        domain_dir.mkdir(parents=True, exist_ok=True)
+        return domain_dir
+
+    def save_json(
+        self,
+        name: str,
+        data: dict[str, Any],
+        subdir: str | None = None,
+    ) -> Path:
+        """Save data as JSON file with pretty formatting.
+
+        Args:
+            name: Filename (without .json extension).
+            data: Dictionary to serialize.
+            subdir: Optional subdirectory within root.
+
+        Returns:
+            Path to the saved JSON file.
+
+        Requirements:
+
+        Examples:
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> manager.create()
+            >>> path = manager.save_json("metrics", {"snr": 42.5})
+            >>> path.name
+            'metrics.json'
+        """
+        target_dir = self._root / subdir if subdir else self._root
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        filepath = target_dir / f"{name}.json"
+        with filepath.open("w") as f:
+            json.dump(data, f, indent=2, default=str)
+
+        return filepath
+
+    def save_yaml(
+        self,
+        name: str,
+        data: dict[str, Any],
+        subdir: str | None = None,
+    ) -> Path:
+        """Save data as YAML file.
+
+        Args:
+            name: Filename (without .yaml extension).
+            data: Dictionary to serialize.
+            subdir: Optional subdirectory within root.
+
+        Returns:
+            Path to the saved YAML file.
+
+        Requirements:
+
+        Examples:
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> manager.create()
+            >>> path = manager.save_yaml("config", {"enabled": True})
+            >>> path.name
+            'config.yaml'
+        """
+        target_dir = self._root / subdir if subdir else self._root
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        filepath = target_dir / f"{name}.yaml"
+        # Sanitize data to handle generators, numpy arrays, etc.
+        sanitized_data = _sanitize_for_serialization(data)
+        with filepath.open("w") as f:
+            yaml.dump(sanitized_data, f, default_flow_style=False, sort_keys=False)
+
+        return filepath
+
+    def save_plot(
+        self,
+        domain: AnalysisDomain,
+        name: str,
+        fig: Any,
+        format: str = "png",
+        dpi: int = 150,
+    ) -> Path:
+        """Save matplotlib figure to plots directory.
+
+        Saves plot with domain-prefixed filename in the plots/ subdirectory.
+
+        Args:
+            domain: Analysis domain for this plot.
+            name: Plot name (without extension).
+            fig: Matplotlib figure object.
+            format: Image format (png, pdf, svg, etc.).
+            dpi: Resolution in dots per inch.
+
+        Returns:
+            Path to the saved plot file.
+
+        Requirements:
+
+        Examples:
+            >>> import matplotlib.pyplot as plt
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> manager.create()
+            >>> fig, ax = plt.subplots()
+            >>> path = manager.save_plot(AnalysisDomain.SPECTRAL, "fft", fig)
+            >>> path.name
+            'spectral_fft.png'
+        """
+        plots_dir = self._root / "plots"
+        plots_dir.mkdir(parents=True, exist_ok=True)
+
+        filename = f"{domain.value}_{name}.{format}"
+        filepath = plots_dir / filename
+
+        fig.savefig(filepath, format=format, dpi=dpi, bbox_inches="tight")
+
+        return filepath
+
+    def save_text(
+        self,
+        name: str,
+        content: str,
+        subdir: str | None = None,
+    ) -> Path:
+        """Save text content to file.
+
+        Args:
+            name: Filename (with extension).
+            content: Text content to write.
+            subdir: Optional subdirectory within root.
+
+        Returns:
+            Path to the saved text file.
+
+        Examples:
+            >>> manager = OutputManager(Path("/tmp/output"), "test")
+            >>> manager.create()
+            >>> path = manager.save_text("summary.txt", "Analysis complete")
+            >>> path.name
+            'summary.txt'
+        """
+        target_dir = self._root / subdir if subdir else self._root
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        filepath = target_dir / name
+        filepath.write_text(content)
+
+        return filepath