oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/{comparison → utils/comparison}/mask.py

@@ -5,7 +5,7 @@ including eye diagram masks and custom polygon masks.
 
 
 Example:
-    >>> from oscura.comparison import mask_test, eye_mask
+    >>> from oscura.utils.comparison import mask_test, eye_mask
     >>> mask = eye_mask(0.5, 0.4, 0.3)
     >>> result = mask_test(trace, mask)
 
@@ -274,20 +274,77 @@ def mask_test(
         >>> result = mask_test(eye_trace, mask)
         >>> print(f"Violations: {result.num_violations}")
     """
-    # Get Y data
+    # Prepare test data
+    x_arr, y_arr = _prepare_mask_test_data(trace, x_data, normalize)
+
+    # Find all violations
+    violations, violations_by_region = _find_mask_violations(x_arr, y_arr, mask)
+
+    # Calculate statistics
+    unique_violations = list(set(violations))
+    num_violations = len(unique_violations)
+    violation_rate = num_violations / len(y_arr) if len(y_arr) > 0 else 0.0
+
+    # Calculate margin to mask boundary
+    margin = _calculate_mask_margin(x_arr, y_arr, mask, num_violations)
+
+    return MaskTestResult(
+        passed=num_violations == 0,
+        num_violations=num_violations,
+        violation_rate=violation_rate,
+        violation_points=unique_violations,
+        violations_by_region=violations_by_region,
+        margin=margin,
+    )
+
+
+def _prepare_mask_test_data(
+    trace: WaveformTrace,
+    x_data: NDArray[np.floating[Any]] | None,
+    normalize: bool,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Prepare X and Y data arrays for mask testing.
+
+    Args:
+        trace: Waveform trace.
+        x_data: Optional X coordinates (defaults to sample indices).
+        normalize: Whether to normalize Y data to [-1, 1].
+
+    Returns:
+        Tuple of (x_array, y_array) as float64.
+    """
     y_data = trace.data.astype(np.float64)
 
-    # Get or create X data
+    # Generate or use provided X data
     if x_data is None:
-        x_data = np.arange(len(y_data), dtype=np.float64)
+        x_arr = np.arange(len(y_data), dtype=np.float64)
+    else:
+        x_arr = x_data
 
-    # Normalize if requested
+    # Normalize Y data if requested
     if normalize:
         y_min, y_max = np.min(y_data), np.max(y_data)
         if y_max - y_min > 0:
             y_data = 2 * (y_data - y_min) / (y_max - y_min) - 1
 
-    # Test each point against mask regions
+    return (x_arr, y_data)
+
+
+def _find_mask_violations(
+    x_data: NDArray[np.float64],
+    y_data: NDArray[np.float64],
+    mask: Mask,
+) -> tuple[list[tuple[float, float]], dict[str, int]]:
+    """Find all mask violations in waveform data.
+
+    Args:
+        x_data: X coordinates.
+        y_data: Y coordinates.
+        mask: Mask with regions to test.
+
+    Returns:
+        Tuple of (violation_points, violations_by_region_name).
+    """
     violations: list[tuple[float, float]] = []
     violations_by_region: dict[str, int] = {}
 
@@ -296,48 +353,97 @@ def mask_test(
         violations_by_region[region_name] = 0
 
         if region.region_type == "violation":
-            # Check if points are inside violation region
-            for i, (x, y) in enumerate(zip(x_data, y_data, strict=False)):  # noqa: B007
-                if region.contains_point(float(x), float(y)):
-                    violations.append((float(x), float(y)))
-                    violations_by_region[region_name] += 1
-
+            # Points inside violation region are violations
+            region_violations = _check_violation_region(x_data, y_data, region)
+            violations.extend(region_violations)
+            violations_by_region[region_name] = len(region_violations)
         elif region.region_type == "boundary":
-            # Check if points are outside boundary region
-            for i, (x, y) in enumerate(zip(x_data, y_data, strict=False)):  # noqa: B007
-                if not region.contains_point(float(x), float(y)):
-                    violations.append((float(x), float(y)))
-                    violations_by_region[region_name] += 1
+            # Points outside boundary region are violations
+            region_violations = _check_boundary_region(x_data, y_data, region)
+            violations.extend(region_violations)
+            violations_by_region[region_name] = len(region_violations)
 
-    # Remove duplicates
-    unique_violations = list(set(violations))
-    num_violations = len(unique_violations)
-    violation_rate = num_violations / len(y_data) if len(y_data) > 0 else 0.0
-
-    # Estimate margin (simplified - distance to nearest mask edge)
-    margin = None
-    if num_violations == 0 and mask.regions:
-        # Find minimum distance to any violation region
-        min_dist = float("inf")
-        for region in mask.regions:
-            if region.region_type == "violation":
-                for x, y in zip(x_data, y_data, strict=False):
-                    for i in range(len(region.vertices)):
-                        x1, y1 = region.vertices[i]
-                        x2, y2 = region.vertices[(i + 1) % len(region.vertices)]
-                        # Distance to line segment
-                        dist = _point_to_segment_distance(x, y, x1, y1, x2, y2)
-                        min_dist = min(min_dist, dist)
-        margin = min_dist if min_dist != float("inf") else None
+    return (violations, violations_by_region)
 
-    return MaskTestResult(
-        passed=num_violations == 0,
-        num_violations=num_violations,
-        violation_rate=violation_rate,
-        violation_points=unique_violations,
-        violations_by_region=violations_by_region,
-        margin=margin,
-    )
+
+def _check_violation_region(
+    x_data: NDArray[np.float64],
+    y_data: NDArray[np.float64],
+    region: MaskRegion,
+) -> list[tuple[float, float]]:
+    """Check for points inside violation region.
+
+    Args:
+        x_data: X coordinates.
+        y_data: Y coordinates.
+        region: Violation region.
+
+    Returns:
+        List of (x, y) points violating this region.
+    """
+    violations = []
+    for x, y in zip(x_data, y_data, strict=False):
+        if region.contains_point(float(x), float(y)):
+            violations.append((float(x), float(y)))
+    return violations
+
+
+def _check_boundary_region(
+    x_data: NDArray[np.float64],
+    y_data: NDArray[np.float64],
+    region: MaskRegion,
+) -> list[tuple[float, float]]:
+    """Check for points outside boundary region.
+
+    Args:
+        x_data: X coordinates.
+        y_data: Y coordinates.
+        region: Boundary region.
+
+    Returns:
+        List of (x, y) points violating this region.
+    """
+    violations = []
+    for x, y in zip(x_data, y_data, strict=False):
+        if not region.contains_point(float(x), float(y)):
+            violations.append((float(x), float(y)))
+    return violations
+
+
+def _calculate_mask_margin(
+    x_data: NDArray[np.float64],
+    y_data: NDArray[np.float64],
+    mask: Mask,
+    num_violations: int,
+) -> float | None:
+    """Calculate margin to nearest mask edge.
+
+    Only calculated when there are no violations.
+
+    Args:
+        x_data: X coordinates.
+        y_data: Y coordinates.
+        mask: Mask with regions.
+        num_violations: Number of violations found.
+
+    Returns:
+        Minimum distance to mask boundary, or None if violations exist or no regions.
+    """
+    if num_violations > 0 or not mask.regions:
+        return None
+
+    # Find minimum distance to any violation region edge
+    min_dist = float("inf")
+    for region in mask.regions:
+        if region.region_type == "violation":
+            for x, y in zip(x_data, y_data, strict=False):
+                for i in range(len(region.vertices)):
+                    x1, y1 = region.vertices[i]
+                    x2, y2 = region.vertices[(i + 1) % len(region.vertices)]
+                    dist = _point_to_segment_distance(x, y, x1, y1, x2, y2)
+                    min_dist = min(min_dist, dist)
+
+    return min_dist if min_dist != float("inf") else None
 
 
 def _point_to_segment_distance(

oscura/{comparison → utils/comparison}/trace_diff.py

@@ -6,7 +6,7 @@ discovery.comparison module to maintain API compatibility.
 
 
 Example:
-    >>> from oscura.comparison import compare_traces
+    >>> from oscura.utils.comparison import compare_traces
     >>> diff = compare_traces(trace1, trace2)
     >>> for d in diff.differences:
     ...     print(f"{d.category}: {d.description}")

oscura/{comparison → utils/comparison}/visualization.py

@@ -5,7 +5,7 @@ overlay plots, difference plots, and comparison heat maps.
 
 
 Example:
-    >>> from oscura.comparison.visualization import (
+    >>> from oscura.utils.comparison.visualization import (
     ...     plot_overlay,
     ...     plot_difference,
     ...     plot_comparison_heatmap
@@ -24,12 +24,14 @@ from typing import TYPE_CHECKING, Any
 import matplotlib.pyplot as plt
 import numpy as np
 from matplotlib.gridspec import GridSpec
+from numpy.typing import NDArray
 
 if TYPE_CHECKING:
+    from matplotlib.axes import Axes
     from matplotlib.figure import Figure
 
-    from oscura.comparison.compare import ComparisonResult
     from oscura.core.types import WaveformTrace
+    from oscura.utils.comparison.compare import ComparisonResult
 
 
 def plot_overlay(
@@ -61,7 +63,7 @@ def plot_overlay(
         Matplotlib Figure object
 
     Example:
-        >>> from oscura.comparison.visualization import plot_overlay
+        >>> from oscura.utils.comparison.visualization import plot_overlay
         >>> fig = plot_overlay(measured, reference,
         ...                     labels=("Measured", "Reference"))
         >>> plt.show()
@@ -160,7 +162,7 @@ def plot_difference(
         Matplotlib Figure object
 
     Example:
-        >>> from oscura.comparison.visualization import plot_difference
+        >>> from oscura.utils.comparison.visualization import plot_difference
         >>> fig = plot_difference(measured, reference, normalize=True)
         >>> plt.show()
 
@@ -259,89 +261,111 @@ def plot_comparison_heatmap(
         Matplotlib Figure object
 
     Example:
-        >>> from oscura.comparison.visualization import plot_comparison_heatmap
+        >>> from oscura.utils.comparison.visualization import plot_comparison_heatmap
         >>> fig = plot_comparison_heatmap(trace1, trace2, window_size=50)
         >>> plt.show()
 
     References:
         CMP-003: Difference heat map showing where changes occur
     """
+    fig, (ax_heat, ax_trace) = _create_heatmap_axes(figsize)
+
+    # Align data and compute difference
+    data1, data2, diff, min_len = _prepare_diff_data(trace1, trace2)
+
+    # Create and plot heatmap
+    n_windows, window_size = _compute_window_params(min_len, window_size)
+    heatmap_data = _build_heatmap(data1, data2, diff, n_windows, window_size, min_len)
+    _plot_heatmap(ax_heat, heatmap_data, title, **kwargs)
+
+    # Plot difference trace
+    time, xlabel = _compute_time_axis(trace1, min_len)
+    _plot_diff_trace(ax_trace, time, diff, xlabel)
+
+    plt.tight_layout()
+    return fig
+
+
+def _create_heatmap_axes(figsize: tuple[float, float]) -> tuple[Figure, tuple[Axes, Axes]]:
+    """Create figure with heatmap and trace axes."""
     fig = plt.figure(figsize=figsize)
     gs = GridSpec(2, 1, height_ratios=[3, 1], hspace=0.3)
     ax_heat = fig.add_subplot(gs[0])
     ax_trace = fig.add_subplot(gs[1], sharex=ax_heat)
+    return fig, (ax_heat, ax_trace)
 
-    # Get data
+
+def _prepare_diff_data(
+    trace1: WaveformTrace, trace2: WaveformTrace
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], int]:
+    """Prepare aligned data and compute difference."""
     data1 = trace1.data.astype(np.float64)
     data2 = trace2.data.astype(np.float64)
-
-    # Align lengths
     min_len = min(len(data1), len(data2))
-    data1 = data1[:min_len]
-    data2 = data2[:min_len]
-
-    # Compute difference
+    data1, data2 = data1[:min_len], data2[:min_len]
     diff = np.abs(data1 - data2)
+    return data1, data2, diff, min_len
+
 
-    # Create windowed heatmap
+def _compute_window_params(min_len: int, window_size: int) -> tuple[int, int]:
+    """Compute window parameters for heatmap."""
     n_windows = min_len // window_size
     if n_windows == 0:
-        n_windows = 1
-        window_size = min_len
-
+        return 1, min_len
+    return n_windows, window_size
+
+
+def _build_heatmap(
+    data1: NDArray[np.float64],
+    data2: NDArray[np.float64],
+    diff: NDArray[np.float64],
+    n_windows: int,
+    window_size: int,
+    min_len: int,
+) -> NDArray[np.float64]:
+    """Build heatmap data from windowed differences."""
     heatmap_data = np.zeros((10, n_windows))
     for i in range(n_windows):
         start = i * window_size
         end = min(start + window_size, min_len)
-        window_diff = diff[start:end]
-
-        # Bin into 10 levels based on amplitude
-        window_data1 = data1[start:end]
-        window_data2 = data2[start:end]
-        y_min = min(np.min(window_data1), np.min(window_data2))
-        y_max = max(np.max(window_data1), np.max(window_data2))
-
+        window_data1, window_diff = data1[start:end], diff[start:end]
+        y_min, y_max = (
+            min(np.min(data1[start:end]), np.min(data2[start:end])),
+            max(np.max(data1[start:end]), np.max(data2[start:end])),
+        )
         if y_max - y_min > 0:
             bins = np.linspace(y_min, y_max, 11)
-            for sample_idx in range(len(window_diff)):
-                y_val = window_data1[sample_idx]  # window_data1 is already sliced
-                bin_idx = np.digitize(y_val, bins) - 1
-                bin_idx = max(0, min(9, bin_idx))
+            for sample_idx, y_val in enumerate(window_data1):
+                bin_idx = max(0, min(9, np.digitize(y_val, bins) - 1))
                 heatmap_data[bin_idx, i] += window_diff[sample_idx]
+    return heatmap_data / window_size
+
 
-    # Normalize heatmap
-    heatmap_data = heatmap_data / window_size
-
-    # Plot heatmap
-    im = ax_heat.imshow(
-        heatmap_data,
-        aspect="auto",
-        cmap="hot",
-        origin="lower",
-        interpolation="nearest",
-        **kwargs,
+def _plot_heatmap(ax: Axes, heatmap_data: NDArray[np.float64], title: str, **kwargs: Any) -> None:
+    """Plot heatmap on axes."""
+    im = ax.imshow(
+        heatmap_data, aspect="auto", cmap="hot", origin="lower", interpolation="nearest", **kwargs
     )
-    plt.colorbar(im, ax=ax_heat, label="Average Difference")
+    plt.colorbar(im, ax=ax, label="Average Difference")
+    ax.set_ylabel("Amplitude Bin")
+    ax.set_title(title)
 
-    ax_heat.set_ylabel("Amplitude Bin")
-    ax_heat.set_title(title)
 
-    # Plot difference trace below
-    if hasattr(trace1, "metadata") and trace1.metadata.sample_rate is not None:
-        sample_rate = trace1.metadata.sample_rate
-        time = np.arange(min_len) / sample_rate
-        xlabel = "Time (s)"
-    else:
-        time = np.arange(min_len, dtype=np.float64)
-        xlabel = "Sample"
+def _compute_time_axis(trace: WaveformTrace, min_len: int) -> tuple[NDArray[np.float64], str]:
+    """Compute time axis and label."""
+    if hasattr(trace, "metadata") and trace.metadata.sample_rate is not None:
+        return np.arange(min_len) / trace.metadata.sample_rate, "Time (s)"
+    return np.arange(min_len, dtype=np.float64), "Sample"
 
-    ax_trace.plot(time, diff, linewidth=0.5)
-    ax_trace.set_xlabel(xlabel)
-    ax_trace.set_ylabel("Difference")
-    ax_trace.grid(True, alpha=0.3)
 
-    plt.tight_layout()
-    return fig
+def _plot_diff_trace(
+    ax: Axes, time: NDArray[np.float64], diff: NDArray[np.float64], xlabel: str
+) -> None:
+    """Plot difference trace on axes."""
+    ax.plot(time, diff, linewidth=0.5)
+    ax.set_xlabel(xlabel)
+    ax.set_ylabel("Difference")
+    ax.grid(True, alpha=0.3)
 
 
 def plot_comparison_summary(
@@ -363,8 +387,8 @@ def plot_comparison_summary(
         Matplotlib Figure object
 
     Example:
-        >>> from oscura.comparison import compare_traces
-        >>> from oscura.comparison.visualization import plot_comparison_summary
+        >>> from oscura.utils.comparison import compare_traces
+        >>> from oscura.utils.comparison.visualization import plot_comparison_summary
         >>> result = compare_traces(trace1, trace2)
         >>> fig = plot_comparison_summary(result)
         >>> plt.show()
@@ -375,7 +399,28 @@ def plot_comparison_summary(
     fig = plt.figure(figsize=figsize)
     gs = GridSpec(3, 2, hspace=0.4, wspace=0.3)
 
-    # Statistics table
+    # Create statistics table
+    _plot_statistics_table(fig, gs, result, title)
+
+    # Plot difference trace
+    if result.difference_trace is not None:
+        _plot_difference_trace(fig, gs, result.difference_trace)
+        _plot_difference_histogram(fig, gs, result.difference_trace)
+
+    # Plot violation locations
+    _plot_violations(fig, gs, result)
+
+    plt.tight_layout()
+    return fig
+
+
+def _plot_statistics_table(
+    fig: Figure,
+    gs: GridSpec,
+    result: ComparisonResult,
+    title: str,
+) -> None:
+    """Plot statistics table at top of summary."""
     ax_stats = fig.add_subplot(gs[0, :])
     ax_stats.axis("off")
 
@@ -415,34 +460,50 @@ def plot_comparison_summary(
 
     ax_stats.set_title(title, fontsize=14, fontweight="bold", pad=20)
 
-    # Overlay plot
-    if result.difference_trace is not None:
-        # Plot difference trace
-        ax_overlay = fig.add_subplot(gs[1, :])
-        n_samples = len(result.difference_trace.data)
-        time = np.arange(n_samples)
-        ax_overlay.plot(time, result.difference_trace.data, label="Difference")
-        ax_overlay.axhline(y=0, color="k", linestyle="--", alpha=0.5)
-        ax_overlay.set_xlabel("Sample")
-        ax_overlay.set_ylabel("Difference")
-        ax_overlay.set_title("Difference Trace")
-        ax_overlay.legend()
-        ax_overlay.grid(True, alpha=0.3)
-
-    # Histogram of differences
-    if result.difference_trace is not None:
-        ax_hist = fig.add_subplot(gs[2, 0])
-        diff_data = result.difference_trace.data
-        ax_hist.hist(diff_data, bins=50, edgecolor="black", alpha=0.7)
-        ax_hist.axvline(x=0, color="r", linestyle="--", linewidth=2, label="Zero difference")
-        ax_hist.set_xlabel("Difference")
-        ax_hist.set_ylabel("Count")
-        ax_hist.set_title("Difference Distribution")
-        ax_hist.legend()
-        ax_hist.grid(True, alpha=0.3)
-
-    # Violation locations
+
+def _plot_difference_trace(
+    fig: Figure,
+    gs: GridSpec,
+    difference_trace: Any,
+) -> None:
+    """Plot difference trace in middle row."""
+    ax_overlay = fig.add_subplot(gs[1, :])
+    n_samples = len(difference_trace.data)
+    time = np.arange(n_samples)
+    ax_overlay.plot(time, difference_trace.data, label="Difference")
+    ax_overlay.axhline(y=0, color="k", linestyle="--", alpha=0.5)
+    ax_overlay.set_xlabel("Sample")
+    ax_overlay.set_ylabel("Difference")
+    ax_overlay.set_title("Difference Trace")
+    ax_overlay.legend()
+    ax_overlay.grid(True, alpha=0.3)
+
+
+def _plot_difference_histogram(
+    fig: Figure,
+    gs: GridSpec,
+    difference_trace: Any,
+) -> None:
+    """Plot histogram of differences."""
+    ax_hist = fig.add_subplot(gs[2, 0])
+    diff_data = difference_trace.data
+    ax_hist.hist(diff_data, bins=50, edgecolor="black", alpha=0.7)
+    ax_hist.axvline(x=0, color="r", linestyle="--", linewidth=2, label="Zero difference")
+    ax_hist.set_xlabel("Difference")
+    ax_hist.set_ylabel("Count")
+    ax_hist.set_title("Difference Distribution")
+    ax_hist.legend()
+    ax_hist.grid(True, alpha=0.3)
+
+
+def _plot_violations(
+    fig: Figure,
+    gs: GridSpec,
+    result: ComparisonResult,
+) -> None:
+    """Plot violation locations."""
     ax_viol = fig.add_subplot(gs[2, 1])
+
     if result.violations is not None and len(result.violations) > 0:
         ax_viol.scatter(
             result.violations,
@@ -469,9 +530,6 @@ def plot_comparison_summary(
         )
         ax_viol.axis("off")
 
-    plt.tight_layout()
-    return fig
-
 
 __all__ = [
     "plot_comparison_heatmap",

oscura/{component → utils/component}/__init__.py

@@ -4,17 +4,17 @@ This module provides TDR-based impedance extraction, capacitance/inductance
 measurement, parasitic extraction, and transmission line analysis.
 """
 
-from oscura.component.impedance import (
+from oscura.utils.component.impedance import (
     discontinuity_analysis,
     extract_impedance,
     impedance_profile,
 )
-from oscura.component.reactive import (
+from oscura.utils.component.reactive import (
     extract_parasitics,
     measure_capacitance,
     measure_inductance,
 )
-from oscura.component.transmission_line import (
+from oscura.utils.component.transmission_line import (
     characteristic_impedance,
     propagation_delay,
     transmission_line_analysis,