oscura 0.7.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

oscura/reporting/__init__.py

@@ -18,6 +18,12 @@ from oscura.reporting.auto_report import (
 from oscura.reporting.auto_report import (
     generate_report as generate_auto_report,
 )
+from oscura.reporting.automation import (
+    auto_interpret_results,
+    flag_anomalies,
+    identify_issues,
+    suggest_follow_up_analyses,
+)
 from oscura.reporting.batch import (
     BatchReportResult,
     aggregate_batch_measurements,
@@ -30,6 +36,13 @@ from oscura.reporting.chart_selection import (
     get_axis_scaling,
     recommend_chart_with_reasoning,
 )
+from oscura.reporting.citations import (
+    Citation,
+    CitationManager,
+    auto_cite_measurement,
+    get_standard_info,
+    list_available_standards,
+)
 from oscura.reporting.comparison import (
     compare_waveforms,
     generate_comparison_report,
@@ -73,8 +86,12 @@ from oscura.reporting.export import (
     export_report,
 )
 from oscura.reporting.formatting import (
+    MeasurementFormatter,
     NumberFormatter,
+    convert_to_measurement_dict,
     format_margin,
+    format_measurement,
+    format_measurement_dict,
     format_pass_fail,
     format_value,
     format_with_context,
@@ -82,6 +99,7 @@ from oscura.reporting.formatting import (
     format_with_units,
 )
 from oscura.reporting.html import (
+    embed_plots,
     generate_html_report,
     save_html_report,
 )
@@ -89,6 +107,16 @@ from oscura.reporting.index import (
     IndexGenerator,
     TemplateEngine,
 )
+from oscura.reporting.interpretation import (
+    ComplianceStatus,
+    MeasurementInterpretation,
+    QualityLevel,
+    compliance_check,
+    generate_finding,
+    interpret_measurement,
+    interpret_results_batch,
+    quality_score,
+)
 from oscura.reporting.multichannel import (
     generate_multichannel_report,
 )
@@ -127,6 +155,12 @@ from oscura.reporting.standards import (
     format_executive_summary_html,
     generate_executive_summary,
 )
+from oscura.reporting.summary import (
+    ExecutiveSummarySection,
+    identify_key_findings,
+    recommendations_from_findings,
+    summarize_measurements,
+)
 from oscura.reporting.summary_generator import (
     Finding,
     Summary,
@@ -144,6 +178,10 @@ from oscura.reporting.template_system import (
     list_templates,
     load_template,
 )
+from oscura.reporting.visualization import (
+    IEEEPlotGenerator,
+    PlotStyler,
+)
 
 __all__ = [
     # Comprehensive Analysis Report API (CAR-001 through CAR-007)
@@ -160,30 +198,46 @@ __all__ = [
     "BatchReportResult",
     # Chart Selection (REPORT-028)
     "ChartType",
+    # Citations (NEW)
+    "Citation",
+    "CitationManager",
     # Standards (REPORT-001, REPORT-002, REPORT-004)
     "ColorScheme",
+    # Compliance (NEW)
+    "ComplianceStatus",
     "DataOutputConfig",
     "DomainConfig",
     # Enhanced Reports (Feature 6)
     "EnhancedReportConfig",
     "EnhancedReportGenerator",
     "ExecutiveSummary",
+    # Executive Summary (NEW)
+    "ExecutiveSummarySection",
     # Summary Generation
     "Finding",
     "FormatStandards",
+    # IEEE Visualization (NEW)
+    "IEEEPlotGenerator",
     "IndexGenerator",
     "InputType",
+    # Formatting (REPORT-026)
+    "MeasurementFormatter",
+    # Measurement Interpretation (NEW)
+    "MeasurementInterpretation",
     # Multi-format (REPORT-010)
     "MultiFormatRenderer",
-    # Formatting (REPORT-026)
     "NumberFormatter",
     "OutputManager",
     # PPTX Export (REPORT-023)
     "PPTXPresentation",
     "PPTXSlide",
     "PlotGenerator",
+    # Plot Styling (NEW)
+    "PlotStyler",
     "ProgressCallback",
     "ProgressInfo",
+    # Quality Assessment (NEW)
+    "QualityLevel",
     # Core
     "Report",
     "ReportConfig",
@@ -199,12 +253,18 @@ __all__ = [
     "VisualEmphasis",
     "aggregate_batch_measurements",
     "analyze",
+    # Automation (NEW)
+    "auto_cite_measurement",
+    "auto_interpret_results",
     "auto_select_chart",
     # Export
     "batch_export_formats",
     "batch_report",
     # Comparison
     "compare_waveforms",
+    # Compliance (NEW)
+    "compliance_check",
+    "convert_to_measurement_dict",
     # Tables
     "create_comparison_table",
     # Sections
@@ -220,12 +280,18 @@ __all__ = [
     "create_violations_section",
     # Multi-format (REPORT-010)
     "detect_format_from_extension",
+    # HTML Generation
+    "embed_plots",
     "export_multiple_reports",
     "export_pptx",
     "export_report",
+    # Anomaly Detection (NEW)
+    "flag_anomalies",
     "format_batch_summary_table",
     "format_executive_summary_html",
     "format_margin",
+    "format_measurement",
+    "format_measurement_dict",
     "format_pass_fail",
     "format_value",
     "format_with_context",
@@ -235,6 +301,8 @@ __all__ = [
     "generate_batch_report",
     "generate_comparison_report",
     "generate_executive_summary",
+    # Findings (NEW)
+    "generate_finding",
     # HTML Generation
     "generate_html_report",
     # Multi-Channel
@@ -246,12 +314,31 @@ __all__ = [
     "generate_summary",
     "get_available_analyses",
     "get_axis_scaling",
+    # Citations (NEW)
+    "get_standard_info",
+    # Issue Identification (NEW)
+    "identify_issues",
+    # Key Findings (NEW)
+    "identify_key_findings",
+    # Interpretation (NEW)
+    "interpret_measurement",
+    "interpret_results_batch",
+    # Standards (NEW)
+    "list_available_standards",
     "list_templates",
     "load_template",
+    # Quality (NEW)
+    "quality_score",
     "recommend_chart_with_reasoning",
+    # Recommendations (NEW)
+    "recommendations_from_findings",
     "register_plot",
     # Multi-format (REPORT-010)
     "render_all_formats",
     "save_html_report",
     "save_pdf_report",
+    # Follow-up Analysis (NEW)
+    "suggest_follow_up_analyses",
+    # Summary (NEW)
+    "summarize_measurements",
 ]

oscura/reporting/automation.py

@@ -0,0 +1,348 @@
+"""Automated analysis and anomaly detection for reports.
+
+This module provides automated interpretation of results, anomaly flagging,
+and intelligent recommendations generation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from oscura.reporting.interpretation import MeasurementInterpretation, interpret_measurement
+from oscura.reporting.summary import (
+    identify_key_findings,
+    recommendations_from_findings,
+    summarize_measurements,
+)
+
+
+def auto_interpret_results(results: dict[str, Any]) -> dict[str, MeasurementInterpretation]:
+    """Automatically interpret all results in a dictionary.
+
+    Args:
+        results: Dictionary of measurement results. Can be nested.
+
+    Returns:
+        Dictionary mapping measurement names to interpretations.
+
+    Example:
+        >>> results = {"snr": 45.2, "bandwidth": 1e9, "jitter": 50e-12}
+        >>> interpretations = auto_interpret_results(results)
+        >>> len(interpretations) >= 3
+        True
+    """
+    interpretations = {}
+
+    for key, value in results.items():
+        if isinstance(value, dict):
+            # Nested dictionary - recurse
+            if "value" in value:
+                # This is a measurement dict with value and metadata
+                meas_value = value["value"]
+                units = value.get("units", "")
+                spec_min = value.get("spec_min")
+                spec_max = value.get("spec_max")
+
+                interp = interpret_measurement(key, meas_value, units, spec_min, spec_max)
+                interpretations[key] = interp
+            else:
+                # Recurse into nested dict
+                nested = auto_interpret_results(value)
+                interpretations.update(nested)
+        elif isinstance(value, int | float):
+            # Simple numeric value
+            interp = interpret_measurement(key, value)
+            interpretations[key] = interp
+
+    return interpretations
+
+
+def generate_summary(
+    results: dict[str, Any],
+    include_recommendations: bool = True,
+) -> dict[str, Any]:
+    """Generate comprehensive automated summary of results.
+
+    Args:
+        results: Dictionary of measurement results.
+        include_recommendations: Whether to include recommendations.
+
+    Returns:
+        Summary dictionary with statistics, findings, and recommendations.
+
+    Example:
+        >>> results = {"snr": 45.2, "thd": -60.5, "bandwidth": 1e9}
+        >>> summary = generate_summary(results)
+        >>> "statistics" in summary
+        True
+        >>> "key_findings" in summary
+        True
+    """
+    # Flatten results to simple dict
+    flat_results = _flatten_results(results)
+
+    # Generate statistics
+    statistics = summarize_measurements(flat_results)
+
+    # Interpret results
+    interpretations = auto_interpret_results(results)
+
+    # Identify key findings
+    key_findings = identify_key_findings(flat_results, interpretations, max_findings=10)
+
+    # Generate recommendations
+    recommendations = []
+    if include_recommendations:
+        recommendations = recommendations_from_findings(flat_results, interpretations)
+
+    # Flag anomalies
+    anomalies = flag_anomalies(flat_results)
+
+    return {
+        "statistics": statistics,
+        "key_findings": key_findings,
+        "recommendations": recommendations,
+        "anomalies": anomalies,
+        "interpretations": {k: v.__dict__ for k, v in interpretations.items()},
+    }
+
+
+def flag_anomalies(
+    measurements: dict[str, Any],
+    threshold_std: float = 3.0,
+) -> list[dict[str, Any]]:
+    """Flag anomalous measurements using statistical analysis.
+
+    Args:
+        measurements: Dictionary of measurements.
+        threshold_std: Number of standard deviations for outlier detection.
+
+    Returns:
+        List of anomaly dictionaries with name, value, and reason.
+
+    Example:
+        >>> measurements = {"m1": 10, "m2": 11, "m3": 12, "m4": 100}
+        >>> anomalies = flag_anomalies(measurements, threshold_std=2.0)
+        >>> len(anomalies) >= 1
+        True
+    """
+    anomalies: list[dict[str, Any]] = []
+
+    # Extract numeric values
+    numeric_measurements = {k: v for k, v in measurements.items() if isinstance(v, int | float)}
+
+    if len(numeric_measurements) < 3:
+        # Not enough data for statistical analysis
+        return anomalies
+
+    values = np.array(list(numeric_measurements.values()))
+    mean = np.mean(values)
+    std = np.std(values)
+
+    if std == 0:
+        return anomalies
+
+    # Check each measurement
+    for name, value in numeric_measurements.items():
+        z_score = abs((value - mean) / std)
+
+        if z_score > threshold_std:
+            anomalies.append(
+                {
+                    "name": name,
+                    "value": value,
+                    "z_score": float(z_score),
+                    "reason": f"Value is {z_score:.1f} std devs from mean ({mean:.3e})",
+                    "severity": "high" if z_score > 5 else "medium",
+                }
+            )
+
+    # Domain-specific anomaly checks
+    for name, value in measurements.items():
+        if not isinstance(value, int | float):
+            continue
+
+        # Negative SNR
+        if "snr" in name.lower() and value < 0:
+            anomalies.append(
+                {
+                    "name": name,
+                    "value": value,
+                    "reason": "Negative SNR indicates signal weaker than noise",
+                    "severity": "critical",
+                }
+            )
+
+        # Negative bandwidth
+        if "bandwidth" in name.lower() and value <= 0:
+            anomalies.append(
+                {
+                    "name": name,
+                    "value": value,
+                    "reason": "Invalid negative or zero bandwidth",
+                    "severity": "critical",
+                }
+            )
+
+        # Extremely high jitter (>1 second)
+        if "jitter" in name.lower() and value > 1.0:
+            anomalies.append(
+                {
+                    "name": name,
+                    "value": value,
+                    "reason": "Unrealistically high jitter value (>1 second)",
+                    "severity": "critical",
+                }
+            )
+
+        # Invalid power factor (must be -1 to +1)
+        if "power_factor" in name.lower() and abs(value) > 1.0:
+            anomalies.append(
+                {
+                    "name": name,
+                    "value": value,
+                    "reason": "Power factor must be between -1 and +1",
+                    "severity": "critical",
+                }
+            )
+
+    return anomalies
+
+
+def suggest_follow_up_analyses(
+    measurements: dict[str, Any],
+    interpretations: dict[str, MeasurementInterpretation] | None = None,
+) -> list[str]:
+    """Suggest follow-up analyses based on measurement results.
+
+    Args:
+        measurements: Dictionary of measurements.
+        interpretations: Optional measurement interpretations.
+
+    Returns:
+        List of suggested analysis descriptions.
+
+    Example:
+        >>> measurements = {"snr": 15.5, "thd": -40}
+        >>> suggestions = suggest_follow_up_analyses(measurements)
+        >>> len(suggestions) > 0
+        True
+    """
+    suggestions = []
+
+    # Low SNR - suggest noise analysis
+    if "snr" in measurements:
+        snr = measurements["snr"]
+        if isinstance(snr, int | float) and snr < 30:
+            suggestions.append("Perform detailed noise analysis to identify noise sources")
+            suggestions.append("Analyze frequency spectrum for interference peaks")
+
+    # High THD - suggest harmonic analysis
+    if "thd" in measurements:
+        thd = measurements["thd"]
+        if isinstance(thd, int | float) and abs(thd) < 40:  # THD typically negative dB
+            suggestions.append("Perform harmonic analysis to identify distortion sources")
+            suggestions.append("Check for clipping or saturation in signal path")
+
+    # Jitter present - suggest jitter decomposition
+    if any("jitter" in k.lower() for k in measurements):
+        suggestions.append("Perform jitter decomposition (RJ, DJ, PJ) for root cause analysis")
+        suggestions.append("Analyze clock quality and investigate timing sources")
+
+    # Power measurements - suggest power quality
+    if any("power" in k.lower() for k in measurements):
+        suggestions.append("Perform power quality analysis (harmonics, flicker, sags/swells)")
+
+    # Eye diagram quality issues
+    if interpretations:
+        poor_quality = [
+            k for k, v in interpretations.items() if v.quality.value in ("marginal", "poor")
+        ]
+        if poor_quality:
+            suggestions.append(
+                f"Investigate {len(poor_quality)} marginal/poor measurements: "
+                f"{', '.join(poor_quality[:3])}"
+            )
+
+    return suggestions
+
+
+def identify_issues(
+    measurements: dict[str, Any],
+    anomalies: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Identify issues from measurements and anomalies.
+
+    Args:
+        measurements: Dictionary of measurements.
+        anomalies: List of detected anomalies.
+
+    Returns:
+        List of issue dictionaries with severity and description.
+
+    Example:
+        >>> measurements = {"snr": 10}
+        >>> anomalies = [{"name": "snr", "value": 10, "severity": "high"}]
+        >>> issues = identify_issues(measurements, anomalies)
+        >>> len(issues) > 0
+        True
+    """
+    issues = []
+
+    # Add critical anomalies as issues
+    for anomaly in anomalies:
+        if anomaly.get("severity") == "critical":
+            issues.append(
+                {
+                    "severity": "critical",
+                    "measurement": anomaly["name"],
+                    "description": anomaly["reason"],
+                    "value": anomaly["value"],
+                }
+            )
+
+    # Domain-specific issue detection
+    if "snr" in measurements:
+        snr = measurements["snr"]
+        if isinstance(snr, int | float) and snr < 20:
+            issues.append(
+                {
+                    "severity": "high",
+                    "measurement": "snr",
+                    "description": f"Low SNR ({snr:.1f} dB) may impact measurement accuracy",
+                    "value": snr,
+                }
+            )
+
+    if "bandwidth" in measurements:
+        bw = measurements["bandwidth"]
+        if isinstance(bw, int | float) and bw < 10e6:
+            issues.append(
+                {
+                    "severity": "medium",
+                    "measurement": "bandwidth",
+                    "description": f"Limited bandwidth ({bw / 1e6:.1f} MHz) may restrict signal fidelity",
+                    "value": bw,
+                }
+            )
+
+    return issues
+
+
+def _flatten_results(results: dict[str, Any]) -> dict[str, Any]:
+    """Flatten nested results dictionary."""
+    flat = {}
+
+    for key, value in results.items():
+        if isinstance(value, dict):
+            if "value" in value:
+                flat[key] = value["value"]
+            else:
+                nested = _flatten_results(value)
+                flat.update(nested)
+        elif isinstance(value, int | float | str):
+            flat[key] = value
+
+    return flat