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

oscura/reporting/chart_selection.py

@@ -0,0 +1,223 @@
+"""Automated chart type selection for TraceKit reports.
+
+This module provides intelligent chart type selection based on data
+characteristics to optimize data visualization in reports.
+
+
+Example:
+    >>> from oscura.reporting import auto_select_chart
+    >>> chart_type = auto_select_chart("time_series", (1000, 2))
+    >>> print(chart_type)  # "line"
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+ChartType = Literal["line", "scatter", "bar", "histogram", "heatmap", "pie", "spectrum"]
+
+
+def auto_select_chart(
+    data_type: str,
+    data_shape: tuple[int, ...],
+    *,
+    data: NDArray[np.float64] | None = None,
+) -> ChartType:
+    """Automatically select appropriate chart type based on data characteristics.
+
+    Args:
+        data_type: Type of data - one of:
+            - "time_series": Time-domain waveform data
+            - "frequency": Frequency-domain spectral data
+            - "distribution": Statistical distribution data
+            - "comparison": Comparative measurements
+            - "correlation": Correlation or scatter data
+            - "categorical": Categorical comparison data
+            - "matrix": 2D matrix data
+            - "parts": Part-to-whole relationships
+        data_shape: Shape of the data array (rows, [columns]).
+        data: Optional actual data array for additional analysis.
+
+    Returns:
+        Recommended chart type: 'line', 'scatter', 'bar', 'histogram',
+        'heatmap', 'pie', or 'spectrum'.
+
+    Example:
+        >>> # Time series data → line plot
+        >>> auto_select_chart("time_series", (1000, 2))
+        'line'
+
+        >>> # Distribution data → histogram
+        >>> auto_select_chart("distribution", (500,))
+        'histogram'
+
+        >>> # Categorical comparison → bar chart
+        >>> auto_select_chart("categorical", (5,))
+        'bar'
+
+        >>> # 2D matrix → heatmap
+        >>> auto_select_chart("matrix", (100, 100))
+        'heatmap'
+
+    References:
+        REPORT-028: Automated Chart Type Selection
+    """
+    # Time series → line plot
+    if data_type == "time_series":
+        return "line"
+
+    # Frequency data → spectrum plot (log scale)
+    if data_type == "frequency":
+        return "spectrum"
+
+    # Distribution → histogram or box plot
+    if data_type == "distribution":
+        return "histogram"
+
+    # Categorical comparison → bar chart
+    if data_type == "categorical":
+        # If very few categories, pie chart might be appropriate
+        if len(data_shape) > 0 and data_shape[0] <= 6 and data is not None and np.all(data >= 0):
+            # Check if data represents parts of a whole
+            total = np.sum(data)
+            if total > 0 and np.allclose(data / total * 100, data / total * 100):
+                return "pie"
+        return "bar"
+
+    # Comparison (continuous) → scatter plot
+    if data_type == "comparison":
+        # If 2D data with moderate size, scatter plot
+        if len(data_shape) >= 2 and data_shape[0] < 10000:
+            return "scatter"
+        # Large comparison data → bar chart
+        return "bar"
+
+    # Correlation → scatter plot with potential regression
+    if data_type == "correlation":
+        return "scatter"
+
+    # 2D matrix → heatmap
+    if data_type == "matrix":
+        return "heatmap"
+
+    # Parts-to-whole → pie chart
+    if data_type == "parts":
+        return "pie"
+
+    # Default based on shape
+    if len(data_shape) == 1:
+        # 1D data: histogram for distributions, bar for small sets
+        if data_shape[0] < 20:
+            return "bar"
+        return "histogram"
+    elif len(data_shape) == 2:
+        # 2D data: heatmap for square-ish matrices, scatter for point clouds
+        if data_shape[0] > 50 and data_shape[1] > 50:
+            return "heatmap"
+        return "scatter"
+
+    # Fallback to line plot
+    return "line"
+
+
+def recommend_chart_with_reasoning(
+    data_type: str,
+    data_shape: tuple[int, ...],
+    *,
+    data: NDArray[np.float64] | None = None,
+) -> dict[str, str | ChartType]:
+    """Recommend chart type with reasoning explanation.
+
+    Args:
+        data_type: Type of data (see auto_select_chart).
+        data_shape: Shape of the data array.
+        data: Optional actual data array.
+
+    Returns:
+        Dictionary with 'chart_type' and 'reasoning' keys.
+
+    Example:
+        >>> result = recommend_chart_with_reasoning("time_series", (1000, 2))
+        >>> print(result['chart_type'])  # "line"
+        >>> print(result['reasoning'])  # "Time series data best shown with line plot"
+
+    References:
+        REPORT-028: Automated Chart Type Selection
+    """
+    chart_type = auto_select_chart(data_type, data_shape, data=data)
+
+    # Generate reasoning
+    reasoning_map = {
+        "line": "Time series or sequential data best visualized with line plot",
+        "scatter": "Point data or correlation best shown with scatter plot",
+        "bar": "Categorical or discrete comparison best shown with bar chart",
+        "histogram": "Distribution data best represented as histogram",
+        "heatmap": "2D matrix data best visualized as heatmap",
+        "pie": "Part-to-whole relationship best shown with pie chart",
+        "spectrum": "Frequency domain data best shown with log-scale spectrum plot",
+    }
+
+    reasoning = reasoning_map.get(
+        chart_type, f"Data characteristics suggest {chart_type} visualization"
+    )
+
+    return {
+        "chart_type": chart_type,
+        "reasoning": reasoning,
+    }
+
+
+def get_axis_scaling(
+    data_type: str,
+    data: NDArray[np.float64] | None = None,
+) -> dict[str, str]:
+    """Recommend axis scaling (linear vs log) based on data type.
+
+    Args:
+        data_type: Type of data.
+        data: Optional actual data array for range analysis.
+
+    Returns:
+        Dictionary with 'x_scale' and 'y_scale' keys ('linear' or 'log').
+
+    Example:
+        >>> scaling = get_axis_scaling("frequency")
+        >>> print(scaling)  # {'x_scale': 'log', 'y_scale': 'log'}
+
+    References:
+        REPORT-028: Automated Chart Type Selection
+    """
+    # Default linear scaling
+    x_scale = "linear"
+    y_scale = "linear"
+
+    # Frequency data: both axes log
+    if data_type == "frequency":
+        x_scale = "log"
+        y_scale = "log"
+
+    # Check data range if provided
+    if data is not None and len(data) > 0:
+        # If data spans > 3 orders of magnitude, use log scale
+        data_min = np.min(data[data > 0]) if np.any(data > 0) else 0
+        data_max = np.max(data)
+        if data_min > 0 and data_max / data_min > 1000:
+            y_scale = "log"
+
+    return {
+        "x_scale": x_scale,
+        "y_scale": y_scale,
+    }
+
+
+__all__ = [
+    "ChartType",
+    "auto_select_chart",
+    "get_axis_scaling",
+    "recommend_chart_with_reasoning",
+]

oscura/reporting/comparison.py

@@ -0,0 +1,330 @@
+"""Comparison report generation for TraceKit.
+
+This module provides utilities for comparing multiple traces or test runs
+and generating comparison reports with diff visualization.
+
+
+Example:
+    >>> from oscura.reporting.comparison import generate_comparison_report
+    >>> report = generate_comparison_report(baseline, current, "comparison.pdf")
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from oscura.reporting.core import Report, ReportConfig, Section
+from oscura.reporting.tables import create_comparison_table
+
+
+def generate_comparison_report(
+    baseline: dict[str, Any],
+    current: dict[str, Any],
+    *,
+    title: str = "Comparison Report",
+    mode: Literal["side_by_side", "inline"] = "side_by_side",
+    show_only_changes: bool = False,
+    highlight_changes: bool = False,
+    **kwargs: Any,
+) -> Report:
+    """Generate comparison report between baseline and current results.
+
+    Args:
+        baseline: Baseline results dictionary.
+        current: Current results dictionary.
+        title: Report title.
+        mode: Comparison mode (side_by_side or inline).
+        show_only_changes: Only show changed measurements.
+        highlight_changes: Highlight changes in output. Reserved for future use.
+        **kwargs: Additional report configuration options.
+
+    Returns:
+        Comparison Report object.
+
+    References:
+        REPORT-008
+    """
+    config = ReportConfig(title=title, **kwargs)
+    report = Report(config=config)
+
+    # Add summary
+    summary = _generate_comparison_summary(baseline, current)
+    report.add_section("Comparison Summary", summary, level=1)
+
+    # Add change details
+    changes_section = _create_changes_section(
+        baseline,
+        current,
+        show_only_changes=show_only_changes,
+    )
+    report.sections.append(changes_section)
+
+    # Add violations comparison
+    if "violations" in baseline or "violations" in current:
+        violations_section = _create_violations_comparison_section(
+            baseline,
+            current,
+        )
+        report.sections.append(violations_section)
+
+    # Add detailed comparison
+    if "measurements" in baseline or "measurements" in current:
+        detailed_section = _create_detailed_comparison_section(
+            baseline.get("measurements", {}),
+            current.get("measurements", {}),
+            mode=mode,
+        )
+        report.sections.append(detailed_section)
+
+    return report
+
+
+def _generate_comparison_summary(
+    baseline: dict[str, Any],
+    current: dict[str, Any],
+) -> str:
+    """Generate comparison summary."""
+    summary_parts = []
+
+    # Count changes
+    baseline_meas = baseline.get("measurements", {})
+    current_meas = current.get("measurements", {})
+
+    all_params = set(baseline_meas.keys()) | set(current_meas.keys())
+    changed_params = []
+    improved_params = []
+    degraded_params = []
+
+    for param in all_params:
+        base_val = baseline_meas.get(param, {}).get("value")
+        curr_val = current_meas.get(param, {}).get("value")
+
+        if base_val is not None and curr_val is not None:
+            if abs(curr_val - base_val) / abs(base_val) > 0.05:  # >5% change
+                changed_params.append(param)
+
+                # Determine if improved or degraded
+                base_passed = baseline_meas.get(param, {}).get("passed", True)
+                curr_passed = current_meas.get(param, {}).get("passed", True)
+
+                if not base_passed and curr_passed:
+                    improved_params.append(param)
+                elif base_passed and not curr_passed:
+                    degraded_params.append(param)
+
+    summary_parts.append(f"Comparing {len(all_params)} parameter(s) between baseline and current.")
+
+    if changed_params:
+        summary_parts.append(f"\n{len(changed_params)} measurement(s) changed significantly (>5%).")
+
+    if improved_params:
+        summary_parts.append(
+            f"\n✓ {len(improved_params)} parameter(s) improved (failures → passes)."
+        )
+
+    if degraded_params:
+        summary_parts.append(
+            f"\n✗ {len(degraded_params)} parameter(s) degraded (passes → failures)."
+        )
+
+    # Pass/fail comparison
+    baseline_pass = baseline.get("pass_count", 0)
+    baseline_total = baseline.get("total_count", 0)
+    current_pass = current.get("pass_count", 0)
+    current_total = current.get("total_count", 0)
+
+    if baseline_total > 0 and current_total > 0:
+        baseline_rate = baseline_pass / baseline_total * 100
+        current_rate = current_pass / current_total * 100
+        delta = current_rate - baseline_rate
+
+        summary_parts.append(
+            f"\nPass rate: {baseline_rate:.1f}% → {current_rate:.1f}% ({delta:+.1f}% change)"
+        )
+
+    return "\n".join(summary_parts)
+
+
+def _create_changes_section(
+    baseline: dict[str, Any],
+    current: dict[str, Any],
+    *,
+    show_only_changes: bool = False,
+) -> Section:
+    """Create section detailing changes."""
+    baseline_meas = baseline.get("measurements", {})
+    current_meas = current.get("measurements", {})
+
+    # Create comparison table
+    table = create_comparison_table(
+        baseline_meas,
+        current_meas,
+        format="dict",
+        show_delta=True,
+        show_percent_change=True,
+    )
+
+    # Filter to only changes if requested
+    if show_only_changes:
+        filtered_rows = []
+        for row in table["data"]:  # type: ignore[index]
+            # Check if delta is significant
+            if len(row) >= 4:  # Has delta column
+                delta_str = str(row[3])
+                if delta_str not in {"-", "0"}:
+                    filtered_rows.append(row)
+
+        table["data"] = filtered_rows  # type: ignore[index]
+
+    return Section(
+        title="Measurement Changes",
+        content=[table],
+        level=1,
+        visible=True,
+    )
+
+
+def _create_violations_comparison_section(
+    baseline: dict[str, Any],
+    current: dict[str, Any],
+) -> Section:
+    """Create section comparing violations."""
+    baseline_violations = {v.get("parameter") for v in baseline.get("violations", [])}
+    current_violations = {v.get("parameter") for v in current.get("violations", [])}
+
+    content_parts = []
+
+    # New violations
+    new_violations = current_violations - baseline_violations
+    if new_violations:
+        content_parts.append("**New Violations:**")
+        for param in sorted(new_violations):
+            content_parts.append(f"- {param}")
+
+    # Resolved violations
+    resolved_violations = baseline_violations - current_violations
+    if resolved_violations:
+        content_parts.append("\n**Resolved Violations:**")
+        for param in sorted(resolved_violations):
+            content_parts.append(f"- {param}")
+
+    # Persistent violations
+    persistent_violations = baseline_violations & current_violations
+    if persistent_violations:
+        content_parts.append("\n**Persistent Violations:**")
+        for param in sorted(persistent_violations):
+            content_parts.append(f"- {param}")
+
+    if not content_parts:
+        content_parts.append("No violations in either baseline or current.")
+
+    content = "\n".join(content_parts)
+
+    return Section(
+        title="Violations Comparison",
+        content=content,
+        level=1,
+        visible=True,
+    )
+
+
+def _create_detailed_comparison_section(
+    baseline_meas: dict[str, Any],
+    current_meas: dict[str, Any],
+    *,
+    mode: str = "side_by_side",
+) -> Section:
+    """Create detailed measurement comparison section."""
+    from oscura.reporting.formatting import NumberFormatter
+
+    formatter = NumberFormatter()
+
+    content_parts = []
+
+    all_params = sorted(set(baseline_meas.keys()) | set(current_meas.keys()))
+
+    for param in all_params:
+        base = baseline_meas.get(param, {})
+        curr = current_meas.get(param, {})
+
+        base_val = base.get("value")
+        curr_val = curr.get("value")
+        unit = base.get("unit", curr.get("unit", ""))
+
+        if base_val is not None and curr_val is not None:
+            delta = curr_val - base_val
+            pct_change = (delta / base_val * 100) if base_val != 0 else 0
+
+            base_str = formatter.format(base_val, unit)
+            curr_str = formatter.format(curr_val, unit)
+            delta_str = formatter.format(delta, unit)
+
+            # Determine if improved/degraded
+            base_passed = base.get("passed", True)
+            curr_passed = curr.get("passed", True)
+
+            status = ""
+            if not base_passed and curr_passed:
+                status = " ✓ IMPROVED"
+            elif base_passed and not curr_passed:
+                status = " ✗ DEGRADED"
+
+            content_parts.append(
+                f"**{param}:** {base_str} → {curr_str} (Δ {delta_str}, {pct_change:+.1f}%){status}"
+            )
+
+    content = "\n\n".join(content_parts) if content_parts else "No measurements to compare."
+
+    return Section(
+        title="Detailed Comparison",
+        content=content,
+        level=1,
+        visible=True,
+        collapsible=True,
+    )
+
+
+def compare_waveforms(
+    baseline_signal: dict[str, Any],
+    current_signal: dict[str, Any],
+) -> dict[str, Any]:
+    """Compare two waveforms and extract differences.
+
+    Args:
+        baseline_signal: Baseline waveform data.
+        current_signal: Current waveform data.
+
+    Returns:
+        Dictionary with comparison metrics.
+
+    References:
+        REPORT-008
+    """
+    import numpy as np
+
+    comparison = {
+        "correlation": None,
+        "rms_difference": None,
+        "max_difference": None,
+        "mean_difference": None,
+    }
+
+    base_data = baseline_signal.get("data")
+    curr_data = current_signal.get("data")
+
+    if base_data is not None and curr_data is not None:
+        # Ensure same length
+        min_len = min(len(base_data), len(curr_data))
+        base_data = base_data[:min_len]
+        curr_data = curr_data[:min_len]
+
+        # Correlation
+        comparison["correlation"] = np.corrcoef(base_data, curr_data)[0, 1]
+
+        # Differences
+        diff = curr_data - base_data
+        comparison["rms_difference"] = np.sqrt(np.mean(diff**2))
+        comparison["max_difference"] = np.max(np.abs(diff))
+        comparison["mean_difference"] = np.mean(diff)
+
+    return comparison