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

oscura/visualization/eye.py

@@ -0,0 +1,420 @@
+"""Eye diagram visualization for signal integrity analysis.
+
+This module provides eye diagram plotting with clock recovery and
+eye opening measurements.
+
+
+Example:
+    >>> from oscura.visualization.eye import plot_eye
+    >>> fig = plot_eye(trace, bit_rate=1e9)
+    >>> plt.show()
+
+References:
+    IEEE 802.3 Ethernet standards for eye diagram testing
+    JEDEC eye diagram measurement specifications
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+import numpy as np
+
+try:
+    import matplotlib.pyplot as plt
+    from matplotlib.colors import LinearSegmentedColormap  # noqa: F401
+
+    HAS_MATPLOTLIB = True
+except ImportError:
+    HAS_MATPLOTLIB = False
+
+from oscura.core.exceptions import InsufficientDataError
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from numpy.typing import NDArray
+
+    from oscura.core.types import WaveformTrace
+
+
+def plot_eye(
+    trace: WaveformTrace,
+    *,
+    bit_rate: float | None = None,
+    clock_recovery: Literal["fft", "edge"] = "edge",
+    samples_per_bit: int | None = None,
+    ax: Axes | None = None,
+    cmap: str = "hot",
+    alpha: float = 0.3,
+    show_measurements: bool = True,
+    title: str | None = None,
+    colorbar: bool = False,
+) -> Figure:
+    """Plot eye diagram for signal integrity analysis.
+
+    Creates an eye diagram by overlaying multiple bit periods from a
+    serial data signal. Automatically recovers clock from signal if
+    bit_rate is not specified.
+
+    Args:
+        trace: Input waveform trace (serial data signal).
+        bit_rate: Bit rate in bits/second. If None, auto-recovered from signal.
+        clock_recovery: Method for clock recovery ("fft" or "edge").
+        samples_per_bit: Number of samples per bit period. Auto-calculated if None.
+        ax: Matplotlib axes. If None, creates new figure.
+        cmap: Colormap for density visualization ("hot", "viridis", "Blues").
+        alpha: Transparency for overlaid traces (0.0 to 1.0).
+        show_measurements: Annotate eye opening measurements.
+        title: Plot title.
+        colorbar: Show colorbar for density plot.
+
+    Returns:
+        Matplotlib Figure object.
+
+    Raises:
+        ImportError: If matplotlib is not available.
+        InsufficientDataError: If trace is too short for analysis.
+        ValueError: If clock recovery failed.
+
+    Example:
+        >>> # With known bit rate
+        >>> fig = plot_eye(trace, bit_rate=1e9)  # 1 Gbps
+        >>> plt.show()
+
+        >>> # Auto-recover clock
+        >>> fig = plot_eye(trace, clock_recovery="fft")
+        >>> plt.show()
+
+    References:
+        IEEE 802.3: Ethernet eye diagram specifications
+        JEDEC JESD65B: High-Speed Interface Eye Diagram Measurements
+    """
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib is required for visualization")
+
+    if len(trace.data) < 100:
+        raise InsufficientDataError(
+            "Eye diagram requires at least 100 samples",
+            required=100,
+            available=len(trace.data),
+            analysis_type="eye_diagram",
+        )
+
+    # Recover clock if bit_rate not provided
+    if bit_rate is None:
+        from oscura.analyzers.digital.timing import (
+            recover_clock_edge,
+            recover_clock_fft,
+        )
+
+        result = recover_clock_fft(trace) if clock_recovery == "fft" else recover_clock_edge(trace)
+
+        if np.isnan(result.frequency):
+            raise ValueError("Clock recovery failed - cannot determine bit rate")
+
+        bit_rate = result.frequency
+        bit_period = result.period
+    else:
+        bit_period = 1.0 / bit_rate
+
+    # Calculate samples per bit
+    if samples_per_bit is None:
+        samples_per_bit = int(bit_period / trace.metadata.time_base)
+
+    if samples_per_bit < 10:
+        raise InsufficientDataError(
+            f"Insufficient samples per bit period (need ≥10, got {samples_per_bit})",
+            required=10,
+            available=samples_per_bit,
+            analysis_type="eye_diagram",
+        )
+
+    # Create figure
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(8, 6))
+    else:
+        fig_temp = ax.get_figure()
+        if fig_temp is None:
+            raise ValueError("Axes must have an associated figure")
+        fig = cast("Figure", fig_temp)
+
+    # Extract overlaid bit periods
+    data = trace.data
+    n_bits = len(data) // samples_per_bit
+
+    if n_bits < 2:
+        raise InsufficientDataError(
+            f"Not enough complete bit periods (need ≥2, got {n_bits})",
+            required=2,
+            available=n_bits,
+            analysis_type="eye_diagram",
+        )
+
+    # Time axis for one bit period (normalized to UI - Unit Interval)
+    time_ui = np.linspace(0, 1, samples_per_bit)
+
+    # Overlay traces with density tracking
+    if cmap != "none":
+        # Use density plot (histogram2d)
+        all_times: list[np.floating[Any]] = []
+        all_voltages: list[np.floating[Any]] = []
+
+        for i in range(n_bits - 1):
+            start_idx = i * samples_per_bit
+            end_idx = start_idx + samples_per_bit
+            if end_idx <= len(data):
+                all_times.extend(time_ui)
+                all_voltages.extend(data[start_idx:end_idx])
+
+        # Create 2D histogram
+        h, xedges, yedges = np.histogram2d(
+            all_times,
+            all_voltages,
+            bins=[200, 200],
+        )
+
+        # Plot as image
+        extent_list = [float(xedges[0]), float(xedges[-1]), float(yedges[0]), float(yedges[-1])]
+        im = ax.imshow(
+            h.T,
+            extent=tuple(extent_list),  # type: ignore[arg-type]
+            origin="lower",
+            aspect="auto",
+            cmap=cmap,
+            interpolation="bilinear",
+        )
+
+        if colorbar:
+            fig.colorbar(im, ax=ax, label="Sample Density")
+    else:
+        # Simple line overlay
+        for i in range(min(n_bits - 1, 1000)):  # Limit to 1000 traces for performance
+            start_idx = i * samples_per_bit
+            end_idx = start_idx + samples_per_bit
+            if end_idx <= len(data):
+                ax.plot(
+                    time_ui,
+                    data[start_idx:end_idx],
+                    color="blue",
+                    alpha=alpha,
+                    linewidth=0.5,
+                )
+
+    # Labels and formatting
+    ax.set_xlabel("Time (UI)")
+    ax.set_ylabel("Voltage (V)")
+    ax.set_xlim(0, 1)
+
+    if title:
+        ax.set_title(title)
+    else:
+        ax.set_title(f"Eye Diagram @ {bit_rate / 1e6:.1f} Mbps")
+
+    ax.grid(True, alpha=0.3)
+
+    # Add eye opening measurements
+    if show_measurements:
+        eye_metrics = _calculate_eye_metrics(data, samples_per_bit, n_bits)
+        _add_eye_measurements(ax, eye_metrics, time_ui)
+
+    fig.tight_layout()
+    return fig
+
+
+def _calculate_eye_metrics(
+    data: NDArray[np.floating[Any]],
+    samples_per_bit: int,
+    n_bits: int,
+) -> dict[str, float]:
+    """Calculate eye diagram opening metrics.
+
+    Args:
+        data: Waveform data.
+        samples_per_bit: Samples per bit period.
+        n_bits: Number of complete bit periods.
+
+    Returns:
+        Dictionary with eye metrics:
+            - eye_height: Vertical eye opening (V)
+            - eye_width: Horizontal eye opening (UI)
+            - crossing_voltage: Zero-crossing voltage (V)
+            - ber_margin: Bit error rate margin estimate
+    """
+    # Extract center samples (middle 50% of bit period)
+    center_start = samples_per_bit // 4
+    center_end = 3 * samples_per_bit // 4
+
+    # Collect center samples from all bit periods
+    center_samples_list: list[np.floating[Any]] = []
+    for i in range(n_bits - 1):
+        start_idx = i * samples_per_bit + center_start
+        end_idx = i * samples_per_bit + center_end
+        if end_idx <= len(data):
+            center_samples_list.extend(data[start_idx:end_idx])
+
+    center_samples = np.array(center_samples_list)
+
+    if len(center_samples) == 0:
+        return {
+            "eye_height": np.nan,
+            "eye_width": np.nan,
+            "crossing_voltage": np.nan,
+            "ber_margin": np.nan,
+        }
+
+    # Estimate logic levels using histogram
+    hist, bin_edges = np.histogram(center_samples, bins=100)
+    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+    # Find peaks for logic 0 and logic 1
+    mid_idx = len(hist) // 2
+    low_peak_idx = np.argmax(hist[:mid_idx])
+    high_peak_idx = mid_idx + np.argmax(hist[mid_idx:])
+
+    v_low = bin_centers[low_peak_idx]
+    v_high = bin_centers[high_peak_idx]
+
+    # Crossing voltage (midpoint)
+    v_cross = (v_low + v_high) / 2
+
+    # Eye height (vertical opening)
+    # Use 20th-80th percentile for robustness
+    low_samples = center_samples[center_samples < v_cross]
+    high_samples = center_samples[center_samples >= v_cross]
+
+    if len(low_samples) > 0 and len(high_samples) > 0:
+        v_low_80 = np.percentile(low_samples, 80)
+        v_high_20 = np.percentile(high_samples, 20)
+        eye_height = v_high_20 - v_low_80
+    else:
+        eye_height = v_high - v_low
+
+    # Eye width estimation (simplified)
+    # Find the time span where eye is open (center region)
+    eye_width = 0.5  # 50% of UI is typical for good signal
+
+    # BER margin (simplified estimate)
+    signal_swing = v_high - v_low
+    ber_margin = (eye_height / signal_swing) if signal_swing > 0 else 0.0
+
+    return {
+        "eye_height": float(eye_height),
+        "eye_width": float(eye_width),
+        "crossing_voltage": float(v_cross),
+        "ber_margin": float(ber_margin),
+    }
+
+
+def _add_eye_measurements(
+    ax: Axes,
+    metrics: dict[str, float],
+    time_ui: NDArray[np.float64],
+) -> None:
+    """Add measurement annotations to eye diagram.
+
+    Args:
+        ax: Matplotlib axes.
+        metrics: Eye diagram metrics.
+        time_ui: Time axis in UI.
+    """
+    # Create measurement text
+    lines = []
+    if not np.isnan(metrics["eye_height"]):
+        lines.append(f"Eye Height: {metrics['eye_height'] * 1e3:.1f} mV")
+    if not np.isnan(metrics["eye_width"]):
+        lines.append(f"Eye Width: {metrics['eye_width']:.2f} UI")
+    if not np.isnan(metrics["crossing_voltage"]):
+        lines.append(f"Crossing: {metrics['crossing_voltage']:.3f} V")
+    if not np.isnan(metrics["ber_margin"]):
+        lines.append(f"BER Margin: {metrics['ber_margin'] * 100:.1f}%")
+
+    if lines:
+        text = "\n".join(lines)
+        ax.annotate(
+            text,
+            xy=(0.02, 0.98),
+            xycoords="axes fraction",
+            verticalalignment="top",
+            fontfamily="monospace",
+            fontsize=9,
+            bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.9},
+        )
+
+
+def plot_bathtub(
+    trace: WaveformTrace,
+    *,
+    bit_rate: float | None = None,
+    ber_target: float = 1e-12,
+    ax: Axes | None = None,
+    title: str | None = None,
+) -> Figure:
+    """Plot bathtub curve for BER analysis.
+
+    Creates a bathtub curve showing bit error rate vs. sampling position
+    within the unit interval. Used for determining optimal sampling point
+    and timing margin.
+
+    Args:
+        trace: Input waveform trace.
+        bit_rate: Bit rate in bits/second.
+        ber_target: Target bit error rate for margin calculation.
+        ax: Matplotlib axes.
+        title: Plot title.
+
+    Returns:
+        Matplotlib Figure object.
+
+    Raises:
+        ImportError: If matplotlib is not available.
+        ValueError: If axes has no associated figure.
+
+    Example:
+        >>> fig = plot_bathtub(trace, bit_rate=1e9, ber_target=1e-12)
+
+    References:
+        IEEE 802.3: Bathtub curve methodology
+    """
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib is required for visualization")
+
+    # Placeholder implementation for bathtub curve
+    # Full implementation would require statistical analysis of jitter
+    # and noise distributions
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(8, 5))
+    else:
+        fig_temp = ax.get_figure()
+        if fig_temp is None:
+            raise ValueError("Axes must have an associated figure")
+        fig = cast("Figure", fig_temp)
+
+    # Simplified bathtub curve visualization
+    ui = np.linspace(0, 1, 100)
+    # Bathtub shape: high BER at edges, low in center
+    ber = 1e-2 * (np.exp(-(((ui - 0.5) / 0.2) ** 2) * 10) + 1e-12)
+
+    ax.semilogy(ui, ber, linewidth=2, color="C0")
+    ax.axhline(ber_target, color="red", linestyle="--", label=f"BER Target: {ber_target:.0e}")
+
+    ax.set_xlabel("Sample Position (UI)")
+    ax.set_ylabel("Bit Error Rate")
+    ax.set_xlim(0, 1)
+    ax.grid(True, alpha=0.3, which="both")
+    ax.legend()
+
+    if title:
+        ax.set_title(title)
+    else:
+        ax.set_title("Bathtub Curve")
+
+    fig.tight_layout()
+    return fig
+
+
+__all__ = [
+    "plot_bathtub",
+    "plot_eye",
+]

oscura/visualization/histogram.py

@@ -0,0 +1,281 @@
+"""Histogram utilities with automatic bin optimization.
+
+This module provides intelligent histogram bin calculation using
+established statistical rules.
+
+
+Example:
+    >>> from oscura.visualization.histogram import calculate_optimal_bins
+    >>> bins = calculate_optimal_bins(data, method="freedman-diaconis")
+
+References:
+    Sturges' rule (1926)
+    Freedman-Diaconis rule (1981)
+    Scott's rule (1979)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def calculate_optimal_bins(
+    data: NDArray[np.float64],
+    *,
+    method: Literal["auto", "sturges", "freedman-diaconis", "scott"] = "auto",
+    min_bins: int = 5,
+    max_bins: int = 200,
+) -> int:
+    """Calculate optimal histogram bin count using statistical rules.
+
+    : Automatically calculate optimal histogram bin count
+    using Sturges, Freedman-Diaconis, or Scott's rule.
+
+    Args:
+        data: Input data array
+        method: Binning method to use
+            - "auto": Auto-select based on data characteristics
+            - "sturges": Sturges' rule (good for normal distributions)
+            - "freedman-diaconis": Freedman-Diaconis rule (robust to outliers)
+            - "scott": Scott's rule (good for smooth distributions)
+        min_bins: Minimum number of bins (default: 5)
+        max_bins: Maximum number of bins (default: 200)
+
+    Returns:
+        Optimal number of bins (clamped to [min_bins, max_bins])
+
+    Raises:
+        ValueError: If data is empty or invalid
+
+    Example:
+        >>> data = np.random.randn(1000)
+        >>> bins = calculate_optimal_bins(data, method="freedman-diaconis")
+        >>> hist, edges = np.histogram(data, bins=bins)
+
+        >>> # Auto-select method
+        >>> bins = calculate_optimal_bins(data, method="auto")
+
+    References:
+        VIS-025: Histogram Bin Optimization
+        Sturges (1926): k = ceil(log2(n) + 1)
+        Freedman-Diaconis (1981): h = 2 * IQR * n^(-1/3)
+        Scott (1979): h = 3.5 * std * n^(-1/3)
+    """
+    if len(data) == 0:
+        raise ValueError("Data array cannot be empty")
+    if min_bins < 1:
+        raise ValueError("min_bins must be >= 1")
+    if max_bins < min_bins:
+        raise ValueError("max_bins must be >= min_bins")
+
+    # Remove NaN values
+    clean_data = data[~np.isnan(data)]
+
+    if len(clean_data) < 2:
+        return min_bins
+
+    # Auto-select method based on data characteristics
+    if method == "auto":
+        method = _auto_select_method(clean_data)
+
+    # Calculate bins using selected method
+    if method == "sturges":
+        bins = _sturges_bins(clean_data)
+    elif method == "freedman-diaconis":
+        bins = _freedman_diaconis_bins(clean_data)
+    elif method == "scott":
+        bins = _scott_bins(clean_data)
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+    # Clamp to valid range
+    bins = max(min_bins, min(max_bins, bins))
+
+    return bins
+
+
+def calculate_bin_edges(
+    data: NDArray[np.float64],
+    n_bins: int,
+) -> NDArray[np.float64]:
+    """Calculate histogram bin edges for given bin count.
+
+    Args:
+        data: Input data array
+        n_bins: Number of bins
+
+    Returns:
+        Array of bin edges (length n_bins + 1)
+
+    Raises:
+        ValueError: If data is empty or n_bins < 1.
+
+    Example:
+        >>> data = np.random.randn(1000)
+        >>> n_bins = calculate_optimal_bins(data)
+        >>> edges = calculate_bin_edges(data, n_bins)
+    """
+    if len(data) == 0:
+        raise ValueError("Data array cannot be empty")
+    if n_bins < 1:
+        raise ValueError("n_bins must be >= 1")
+
+    # Remove NaN values
+    clean_data = data[~np.isnan(data)]
+
+    if len(clean_data) == 0:
+        return np.array([0.0, 1.0])
+
+    # Calculate edges
+    data_min = np.min(clean_data)
+    data_max = np.max(clean_data)
+
+    # Handle single-value data
+    if data_min == data_max:
+        return np.array([data_min - 0.5, data_max + 0.5])
+
+    edges: NDArray[np.float64] = np.linspace(data_min, data_max, n_bins + 1)
+    return edges
+
+
+def _sturges_bins(data: NDArray[np.float64]) -> int:
+    """Calculate bins using Sturges' rule.
+
+    Sturges' rule: k = ceil(log2(n) + 1)
+
+    Good for: Normal distributions, small to moderate sample sizes
+
+    Args:
+        data: Input data
+
+    Returns:
+        Number of bins
+    """
+    n = len(data)
+    bins = int(np.ceil(np.log2(n) + 1))
+    return bins
+
+
+def _freedman_diaconis_bins(data: NDArray[np.float64]) -> int:
+    """Calculate bins using Freedman-Diaconis rule.
+
+    Freedman-Diaconis rule: h = 2 * IQR(x) / n^(1/3)
+    where h is bin width and IQR is interquartile range
+
+    Good for: Robust estimation, data with outliers
+
+    Args:
+        data: Input data
+
+    Returns:
+        Number of bins
+    """
+    n = len(data)
+
+    # Calculate IQR
+    q75, q25 = np.percentile(data, [75, 25])
+    iqr = q75 - q25
+
+    if iqr == 0:
+        # Fall back to Sturges if IQR is zero
+        return _sturges_bins(data)
+
+    # Calculate bin width
+    bin_width = 2.0 * iqr / (n ** (1.0 / 3.0))
+
+    # Calculate number of bins
+    data_range = np.ptp(data)  # peak-to-peak (max - min)
+
+    if bin_width == 0:
+        return _sturges_bins(data)
+
+    bins = int(np.ceil(data_range / bin_width))
+
+    return max(1, bins)
+
+
+def _scott_bins(data: NDArray[np.float64]) -> int:
+    """Calculate bins using Scott's rule.
+
+    Scott's rule: h = 3.5 * std(x) / n^(1/3)
+    where h is bin width
+
+    Good for: Smooth distributions, normally distributed data
+
+    Args:
+        data: Input data
+
+    Returns:
+        Number of bins
+    """
+    n = len(data)
+
+    # Calculate standard deviation
+    std = np.std(data)
+
+    if std == 0:
+        # Fall back to Sturges if std is zero
+        return _sturges_bins(data)
+
+    # Calculate bin width
+    bin_width = 3.5 * std / (n ** (1.0 / 3.0))
+
+    # Calculate number of bins
+    data_range = np.ptp(data)
+
+    if bin_width == 0:
+        return _sturges_bins(data)
+
+    bins = int(np.ceil(data_range / bin_width))
+
+    return max(1, bins)
+
+
+def _auto_select_method(
+    data: NDArray[np.float64],
+) -> Literal["sturges", "freedman-diaconis", "scott"]:
+    """Auto-select binning method based on data characteristics.
+
+    Selection criteria:
+    - Use Sturges for small samples (n < 100)
+    - Use Freedman-Diaconis for data with outliers (high skewness)
+    - Use Scott for smooth, normal-like distributions
+
+    Args:
+        data: Input data
+
+    Returns:
+        Selected method name
+    """
+    n = len(data)
+
+    # Small samples: use Sturges
+    if n < 100:
+        return "sturges"
+
+    # Calculate skewness to detect outliers
+    mean = np.mean(data)
+    std = np.std(data)
+
+    if std == 0:
+        return "sturges"
+
+    skewness = np.mean(((data - mean) / std) ** 3)
+
+    # High skewness indicates outliers: use Freedman-Diaconis (robust)
+    if abs(skewness) > 0.5:
+        return "freedman-diaconis"
+
+    # Normal-like distribution: use Scott
+    return "scott"
+
+
+__all__ = [
+    "calculate_bin_edges",
+    "calculate_optimal_bins",
+]