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

oscura/visualization/jitter.py

@@ -44,6 +44,138 @@ __all__ = [
 ]
 
 
+def _determine_tie_time_unit(
+    tie_data: NDArray[np.floating[Any]], time_unit: str
+) -> tuple[str, float]:
+    """Determine time unit and multiplier for TIE display.
+
+    Args:
+        tie_data: TIE values in seconds.
+        time_unit: Requested time unit or "auto".
+
+    Returns:
+        Tuple of (time_unit, time_multiplier).
+    """
+    if time_unit == "auto":
+        max_tie = np.max(np.abs(tie_data))
+        if max_tie < 1e-12:
+            return "fs", 1e15
+        elif max_tie < 1e-9:
+            return "ps", 1e12
+        elif max_tie < 1e-6:
+            return "ns", 1e9
+        else:
+            return "us", 1e6
+    else:
+        time_mult_map = {
+            "s": 1,
+            "ms": 1e3,
+            "us": 1e6,
+            "ns": 1e9,
+            "ps": 1e12,
+            "fs": 1e15,
+        }
+        if time_unit in time_mult_map:
+            return time_unit, time_mult_map[time_unit]
+        else:
+            # Fallback to ps for invalid unit
+            return "ps", 1e12
+
+
+def _calculate_tie_statistics(
+    tie_scaled: NDArray[np.floating[Any]],
+) -> tuple[float, float, float, float]:
+    """Calculate TIE statistical metrics.
+
+    Args:
+        tie_scaled: Scaled TIE values.
+
+    Returns:
+        Tuple of (mean, std, peak-to-peak, rms).
+    """
+    mean_val = float(np.mean(tie_scaled))
+    std_val = float(np.std(tie_scaled))
+    pp_val = float(np.ptp(tie_scaled))
+    rms_val = float(np.sqrt(np.mean(tie_scaled**2)))
+    return mean_val, std_val, pp_val, rms_val
+
+
+def _add_gaussian_fit(
+    ax: Axes, bin_edges: NDArray[np.floating[Any]], mean_val: float, std_val: float, time_unit: str
+) -> None:
+    """Add Gaussian fit overlay to histogram.
+
+    Args:
+        ax: Matplotlib axes to plot on.
+        bin_edges: Histogram bin edges.
+        mean_val: Mean value.
+        std_val: Standard deviation.
+        time_unit: Time unit string for label.
+    """
+    if not HAS_SCIPY:
+        return
+
+    x_fit = np.linspace(bin_edges[0], bin_edges[-1], 200)
+    y_fit = norm.pdf(x_fit, mean_val, std_val)
+    ax.plot(
+        x_fit, y_fit, "r-", linewidth=2, label=f"Gaussian Fit (sigma={std_val:.2f} {time_unit})"
+    )
+
+
+def _add_rj_dj_indicators(ax: Axes, mean_val: float, std_val: float) -> None:
+    """Add RJ/DJ separation indicators to plot.
+
+    Args:
+        ax: Matplotlib axes to plot on.
+        mean_val: Mean value.
+        std_val: Standard deviation.
+    """
+    # Mark ±3sigma region (RJ contribution)
+    ax.axvline(mean_val - 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1.5, alpha=0.7)
+    ax.axvline(mean_val + 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1.5, alpha=0.7)
+
+    # Shade RJ region
+    ax.axvspan(
+        mean_val - 3 * std_val,
+        mean_val + 3 * std_val,
+        alpha=0.1,
+        color="#E74C3C",
+        label="±3sigma (99.7% RJ)",
+    )
+
+
+def _add_statistics_box(
+    ax: Axes, mean_val: float, rms_val: float, std_val: float, pp_val: float, time_unit: str
+) -> None:
+    """Add statistics text box to plot.
+
+    Args:
+        ax: Matplotlib axes to plot on.
+        mean_val: Mean value.
+        rms_val: RMS value.
+        std_val: Standard deviation.
+        pp_val: Peak-to-peak value.
+        time_unit: Time unit string.
+    """
+    stats_text = (
+        f"Mean: {mean_val:.2f} {time_unit}\n"
+        f"RMS: {rms_val:.2f} {time_unit}\n"
+        f"Std Dev: {std_val:.2f} {time_unit}\n"
+        f"Peak-Peak: {pp_val:.2f} {time_unit}"
+    )
+    ax.text(
+        0.98,
+        0.98,
+        stats_text,
+        transform=ax.transAxes,
+        fontsize=9,
+        verticalalignment="top",
+        horizontalalignment="right",
+        bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.9},
+        fontfamily="monospace",
+    )
+
+
 def plot_tie_histogram(
     tie_data: NDArray[np.floating[Any]],
     *,
@@ -68,7 +200,7 @@ def plot_tie_histogram(
         ax: Matplotlib axes. If None, creates new figure.
         figsize: Figure size in inches.
         title: Plot title.
-        time_unit: Time unit ("s", "ms", "us", "ns", "ps", "auto").
+        time_unit: Time unit ("s", "ms", "us", "ns", "ps", "fs", "auto").
         bins: Number of bins or "auto" for automatic selection.
         show_gaussian_fit: Overlay Gaussian fit for RJ estimation.
         show_statistics: Show statistics box.
@@ -86,7 +218,34 @@ def plot_tie_histogram(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
-    # Create figure if needed
+    fig, ax = _setup_tie_figure(ax, figsize)
+    time_unit, time_mult = _determine_tie_time_unit(tie_data, time_unit)
+    tie_scaled = tie_data * time_mult
+    mean_val, std_val, pp_val, rms_val = _calculate_tie_statistics(tie_scaled)
+
+    counts, bin_edges, patches = _plot_tie_histogram_data(ax, tie_scaled, bins)
+    _add_tie_overlays(ax, show_gaussian_fit, show_rj_dj, bin_edges, mean_val, std_val, time_unit)
+    _format_tie_plot(ax, show_statistics, mean_val, rms_val, std_val, pp_val, time_unit, title)
+
+    fig.tight_layout()
+    _save_and_show_tie_plot(fig, save_path, show)
+
+    return fig
+
+
+def _setup_tie_figure(ax: Axes | None, figsize: tuple[float, float]) -> tuple[Figure, Axes]:
+    """Setup figure and axes for TIE plot.
+
+    Args:
+        ax: Existing axes or None.
+        figsize: Figure size.
+
+    Returns:
+        Tuple of (figure, axes).
+
+    Raises:
+        ValueError: If axes has no figure.
+    """
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
     else:
@@ -94,42 +253,23 @@ def plot_tie_histogram(
         if fig_temp is None:
             raise ValueError("Axes must have an associated figure")
         fig = cast("Figure", fig_temp)
+    return fig, ax
 
-    # Select time unit
-    if time_unit == "auto":
-        max_tie = np.max(np.abs(tie_data))
-        if max_tie < 1e-12:
-            time_unit = "fs"
-            time_mult = 1e15
-        elif max_tie < 1e-9:
-            time_unit = "ps"
-            time_mult = 1e12
-        elif max_tie < 1e-6:
-            time_unit = "ns"
-            time_mult = 1e9
-        else:
-            time_unit = "us"
-            time_mult = 1e6
-    else:
-        time_mult = {
-            "s": 1,
-            "ms": 1e3,
-            "us": 1e6,
-            "ns": 1e9,
-            "ps": 1e12,
-            "fs": 1e15,
-        }.get(time_unit, 1e12)
 
-    tie_scaled = tie_data * time_mult
+def _plot_tie_histogram_data(
+    ax: Axes, tie_scaled: NDArray[np.floating[Any]], bins: int | str
+) -> tuple[Any, NDArray[Any], Any]:
+    """Plot histogram data.
 
-    # Calculate statistics
-    mean_val = np.mean(tie_scaled)
-    std_val = np.std(tie_scaled)
-    pp_val = np.ptp(tie_scaled)
-    rms_val = np.sqrt(np.mean(tie_scaled**2))
+    Args:
+        ax: Matplotlib axes.
+        tie_scaled: Scaled TIE data.
+        bins: Bin specification.
 
-    # Plot histogram
-    counts, bin_edges, patches = ax.hist(
+    Returns:
+        Tuple of (counts, bin_edges, patches) from matplotlib hist.
+    """
+    result: tuple[Any, NDArray[Any], Any] = ax.hist(
         tie_scaled,
         bins=bins,
         density=True,
@@ -138,75 +278,82 @@ def plot_tie_histogram(
         edgecolor="black",
         linewidth=0.5,
     )
+    return result
 
-    # Gaussian fit overlay
-    if show_gaussian_fit and HAS_SCIPY:
-        x_fit = np.linspace(bin_edges[0], bin_edges[-1], 200)
-        y_fit = norm.pdf(x_fit, mean_val, std_val)
-        ax.plot(
-            x_fit, y_fit, "r-", linewidth=2, label=f"Gaussian Fit (sigma={std_val:.2f} {time_unit})"
-        )
 
-    # RJ/DJ indicators
+def _add_tie_overlays(
+    ax: Axes,
+    show_gaussian_fit: bool,
+    show_rj_dj: bool,
+    bin_edges: NDArray[Any],
+    mean_val: float,
+    std_val: float,
+    time_unit: str,
+) -> None:
+    """Add Gaussian fit and RJ/DJ overlays to TIE plot.
+
+    Args:
+        ax: Matplotlib axes.
+        show_gaussian_fit: Whether to show Gaussian fit.
+        show_rj_dj: Whether to show RJ/DJ indicators.
+        bin_edges: Histogram bin edges.
+        mean_val: Mean TIE value.
+        std_val: Standard deviation.
+        time_unit: Time unit string.
+    """
+    if show_gaussian_fit:
+        _add_gaussian_fit(ax, bin_edges, mean_val, std_val, time_unit)
     if show_rj_dj:
-        # Mark ±3sigma region (RJ contribution)
-        ax.axvline(
-            mean_val - 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1.5, alpha=0.7
-        )
-        ax.axvline(
-            mean_val + 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1.5, alpha=0.7
-        )
+        _add_rj_dj_indicators(ax, mean_val, std_val)
 
-        # Shade RJ region
-        ax.axvspan(
-            mean_val - 3 * std_val,
-            mean_val + 3 * std_val,
-            alpha=0.1,
-            color="#E74C3C",
-            label="±3sigma (99.7% RJ)",
-        )
 
-    # Statistics box
+def _format_tie_plot(
+    ax: Axes,
+    show_statistics: bool,
+    mean_val: float,
+    rms_val: float,
+    std_val: float,
+    pp_val: float,
+    time_unit: str,
+    title: str | None,
+) -> None:
+    """Format TIE plot axes and labels.
+
+    Args:
+        ax: Matplotlib axes.
+        show_statistics: Whether to show statistics box.
+        mean_val: Mean value.
+        rms_val: RMS value.
+        std_val: Standard deviation.
+        pp_val: Peak-to-peak value.
+        time_unit: Time unit.
+        title: Plot title.
+    """
     if show_statistics:
-        stats_text = (
-            f"Mean: {mean_val:.2f} {time_unit}\n"
-            f"RMS: {rms_val:.2f} {time_unit}\n"
-            f"Std Dev: {std_val:.2f} {time_unit}\n"
-            f"Peak-Peak: {pp_val:.2f} {time_unit}"
-        )
-        ax.text(
-            0.98,
-            0.98,
-            stats_text,
-            transform=ax.transAxes,
-            fontsize=9,
-            verticalalignment="top",
-            horizontalalignment="right",
-            bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.9},
-            fontfamily="monospace",
-        )
+        _add_statistics_box(ax, mean_val, rms_val, std_val, pp_val, time_unit)
 
-    # Labels
     ax.set_xlabel(f"TIE ({time_unit})", fontsize=11)
     ax.set_ylabel("Probability Density", fontsize=11)
     ax.grid(True, alpha=0.3)
     ax.legend(loc="upper left")
 
-    if title:
-        ax.set_title(title, fontsize=12, fontweight="bold")
-    else:
-        ax.set_title("Time Interval Error Distribution", fontsize=12, fontweight="bold")
+    final_title = title if title else "Time Interval Error Distribution"
+    ax.set_title(final_title, fontsize=12, fontweight="bold")
 
-    fig.tight_layout()
 
+def _save_and_show_tie_plot(fig: Figure, save_path: str | Path | None, show: bool) -> None:
+    """Save and/or show TIE plot.
+
+    Args:
+        fig: Matplotlib figure.
+        save_path: Path to save file.
+        show: Whether to display interactively.
+    """
     if save_path is not None:
         fig.savefig(save_path, dpi=300, bbox_inches="tight")
-
     if show:
         plt.show()
 
-    return fig
-
 
 def plot_bathtub_full(
     positions: NDArray[np.floating[Any]],
@@ -257,6 +404,35 @@ def plot_bathtub_full(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
+    fig, ax = _get_or_create_figure(ax, figsize)
+    ber_total = ber_total if ber_total is not None else ber_left + ber_right
+
+    # Plot BER curves
+    ber_total_plot = _plot_bathtub_ber_curves(ax, positions, ber_left, ber_right, ber_total)
+
+    # Optional annotations
+    if show_target:
+        _add_target_ber_line(ax, target_ber)
+
+    if show_eye_opening:
+        _add_eye_opening_annotation(ax, positions, ber_total_plot, target_ber, eye_opening)
+
+    # Styling
+    _style_bathtub_plot(ax, positions, ber_total_plot, title)
+
+    fig.tight_layout()
+
+    if save_path is not None:
+        fig.savefig(save_path, dpi=300, bbox_inches="tight")
+
+    if show:
+        plt.show()
+
+    return fig
+
+
+def _get_or_create_figure(ax: Axes | None, figsize: tuple[float, float]) -> tuple[Figure, Axes]:
+    """Get existing figure or create new one."""
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
     else:
@@ -264,92 +440,104 @@ def plot_bathtub_full(
         if fig_temp is None:
             raise ValueError("Axes must have an associated figure")
         fig = cast("Figure", fig_temp)
+    return fig, ax
 
-    # Compute total BER if not provided
-    if ber_total is None:
-        ber_total = ber_left + ber_right
 
-    # Clip very small values for log plot
+def _plot_bathtub_ber_curves(
+    ax: Axes,
+    positions: NDArray[np.floating[Any]],
+    ber_left: NDArray[np.floating[Any]],
+    ber_right: NDArray[np.floating[Any]],
+    ber_total: NDArray[np.floating[Any]],
+) -> NDArray[np.floating[Any]]:
+    """Plot BER curves and return clipped total BER."""
     ber_left_plot = np.clip(ber_left, 1e-18, 1)
     ber_right_plot = np.clip(ber_right, 1e-18, 1)
     ber_total_plot = np.clip(ber_total, 1e-18, 1)
 
-    # Plot BER curves
     ax.semilogy(positions, ber_left_plot, "b-", linewidth=2, label="BER Left", alpha=0.8)
     ax.semilogy(positions, ber_right_plot, "r-", linewidth=2, label="BER Right", alpha=0.8)
     ax.semilogy(positions, ber_total_plot, "k-", linewidth=2.5, label="BER Total")
 
-    # Target BER line
-    if show_target:
-        ax.axhline(
-            target_ber,
-            color="#27AE60",
-            linestyle="--",
-            linewidth=2,
-            label=f"Target BER = {target_ber:.0e}",
-        )
+    return ber_total_plot
 
-    # Eye opening annotation
-    if show_eye_opening:
-        # Find eye opening at target BER
-        if eye_opening is None:
-            # Find crossover points
-            left_cross = np.where(ber_total_plot < target_ber)[0]
-            if len(left_cross) > 0:
-                left_edge = positions[left_cross[0]]
-                right_edge = positions[left_cross[-1]]
-                eye_opening = right_edge - left_edge
-            else:
-                eye_opening = 0
-
-        if eye_opening > 0:
-            # Draw eye opening bracket
-            center = 0.5
-            left_edge = center - eye_opening / 2
-            right_edge = center + eye_opening / 2
-
-            ax.annotate(
-                "",
-                xy=(right_edge, target_ber),
-                xytext=(left_edge, target_ber),
-                arrowprops={"arrowstyle": "<->", "color": "#27AE60", "lw": 2},
-            )
-            ax.text(
-                center,
-                target_ber * 0.1,
-                f"Eye Opening: {eye_opening:.3f} UI",
-                ha="center",
-                va="top",
-                fontsize=10,
-                fontweight="bold",
-                color="#27AE60",
-            )
-
-    # Shading for bathtub
-    ax.fill_between(positions, 1e-18, ber_total_plot, alpha=0.1, color="gray")
 
-    # Labels
+def _add_target_ber_line(ax: Axes, target_ber: float) -> None:
+    """Add target BER horizontal line."""
+    ax.axhline(
+        target_ber,
+        color="#27AE60",
+        linestyle="--",
+        linewidth=2,
+        label=f"Target BER = {target_ber:.0e}",
+    )
+
+
+def _add_eye_opening_annotation(
+    ax: Axes,
+    positions: NDArray[np.floating[Any]],
+    ber_total_plot: NDArray[np.floating[Any]],
+    target_ber: float,
+    eye_opening: float | None,
+) -> None:
+    """Add eye opening annotation if applicable."""
+    if eye_opening is None:
+        eye_opening = _calculate_eye_opening(positions, ber_total_plot, target_ber)
+
+    if eye_opening <= 0:
+        return
+
+    center = 0.5
+    left_edge = center - eye_opening / 2
+    right_edge = center + eye_opening / 2
+
+    ax.annotate(
+        "",
+        xy=(right_edge, target_ber),
+        xytext=(left_edge, target_ber),
+        arrowprops={"arrowstyle": "<->", "color": "#27AE60", "lw": 2},
+    )
+    ax.text(
+        center,
+        target_ber * 0.1,
+        f"Eye Opening: {eye_opening:.3f} UI",
+        ha="center",
+        va="top",
+        fontsize=10,
+        fontweight="bold",
+        color="#27AE60",
+    )
+
+
+def _calculate_eye_opening(
+    positions: NDArray[np.floating[Any]],
+    ber_total: NDArray[np.floating[Any]],
+    target_ber: float,
+) -> float:
+    """Calculate eye opening at target BER."""
+    left_cross = np.where(ber_total < target_ber)[0]
+    if len(left_cross) > 0:
+        left_edge = positions[left_cross[0]]
+        right_edge = positions[left_cross[-1]]
+        return float(right_edge - left_edge)
+    return 0.0
+
+
+def _style_bathtub_plot(
+    ax: Axes,
+    positions: NDArray[np.floating[Any]],
+    ber_total_plot: NDArray[np.floating[Any]],
+    title: str | None,
+) -> None:
+    """Apply styling to bathtub plot."""
+    ax.fill_between(positions, 1e-18, ber_total_plot, alpha=0.1, color="gray")
     ax.set_xlabel("Sample Position (UI)", fontsize=11)
     ax.set_ylabel("Bit Error Rate", fontsize=11)
     ax.set_xlim(0, 1)
     ax.set_ylim(1e-15, 1)
     ax.grid(True, which="both", alpha=0.3)
     ax.legend(loc="upper right")
-
-    if title:
-        ax.set_title(title, fontsize=12, fontweight="bold")
-    else:
-        ax.set_title("Bathtub Curve", fontsize=12, fontweight="bold")
-
-    fig.tight_layout()
-
-    if save_path is not None:
-        fig.savefig(save_path, dpi=300, bbox_inches="tight")
-
-    if show:
-        plt.show()
-
-    return fig
+    ax.set_title(title or "Bathtub Curve", fontsize=12, fontweight="bold")
 
 
 def plot_ddj(
@@ -389,6 +577,13 @@ def plot_ddj(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
+    # Validate input lengths match
+    if len(patterns) != len(jitter_values):
+        raise ValueError(
+            f"Mismatched lengths: patterns has {len(patterns)} elements "
+            f"but jitter_values has {len(jitter_values)} elements"
+        )
+
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
     else:
@@ -443,76 +638,71 @@ def plot_ddj(
     return fig
 
 
-def plot_dcd(
-    high_times: NDArray[np.floating[Any]],
-    low_times: NDArray[np.floating[Any]],
-    *,
-    ax: Axes | None = None,
-    figsize: tuple[float, float] = (10, 6),
-    title: str | None = None,
-    time_unit: str = "auto",
-    show: bool = True,
-    save_path: str | Path | None = None,
-) -> Figure:
-    """Plot Duty Cycle Distortion (DCD) analysis.
-
-    Creates overlaid histograms of high and low pulse times to visualize
-    duty cycle distortion.
+def _determine_dcd_time_unit(
+    high_times: NDArray[np.floating[Any]], low_times: NDArray[np.floating[Any]], time_unit: str
+) -> tuple[str, float]:
+    """Determine time unit and scaling for DCD plot.
 
     Args:
-        high_times: Array of high-state durations.
-        low_times: Array of low-state durations.
-        ax: Matplotlib axes.
-        figsize: Figure size.
-        title: Plot title.
-        time_unit: Time unit.
-        show: Display plot.
-        save_path: Save path.
+        high_times: High-state durations.
+        low_times: Low-state durations.
+        time_unit: Requested time unit or "auto".
 
     Returns:
-        Matplotlib Figure object.
+        Tuple of (time_unit, time_multiplier).
     """
-    if not HAS_MATPLOTLIB:
-        raise ImportError("matplotlib is required for visualization")
-
-    if ax is None:
-        fig, ax = plt.subplots(figsize=figsize)
-    else:
-        fig_temp = ax.get_figure()
-        if fig_temp is None:
-            raise ValueError("Axes must have an associated figure")
-        fig = cast("Figure", fig_temp)
-
-    # Select time unit
     if time_unit == "auto":
         max_time = max(np.max(high_times), np.max(low_times))
         if max_time < 1e-9:
-            time_unit = "ps"
-            time_mult = 1e12
+            return "ps", 1e12
         elif max_time < 1e-6:
-            time_unit = "ns"
-            time_mult = 1e9
+            return "ns", 1e9
         else:
-            time_unit = "us"
-            time_mult = 1e6
+            return "us", 1e6
     else:
         time_mult = {"s": 1, "ms": 1e3, "us": 1e6, "ns": 1e9, "ps": 1e12}.get(time_unit, 1e9)
+        return time_unit, time_mult
 
-    high_scaled = high_times * time_mult
-    low_scaled = low_times * time_mult
 
-    # Calculate statistics
-    mean_high = np.mean(high_scaled)
-    mean_low = np.mean(low_scaled)
+def _compute_dcd_statistics(
+    high_scaled: NDArray[np.floating[Any]], low_scaled: NDArray[np.floating[Any]]
+) -> tuple[float, float, float, float]:
+    """Compute DCD statistics.
+
+    Args:
+        high_scaled: Scaled high-state durations.
+        low_scaled: Scaled low-state durations.
+
+    Returns:
+        Tuple of (mean_high, mean_low, duty_cycle, dcd).
+    """
+    mean_high = float(np.mean(high_scaled))
+    mean_low = float(np.mean(low_scaled))
     period = mean_high + mean_low
     duty_cycle = mean_high / period * 100
     dcd = (mean_high - mean_low) / 2
+    return mean_high, mean_low, duty_cycle, dcd
+
+
+def _plot_dcd_histograms(
+    ax: Axes,
+    high_scaled: NDArray[np.floating[Any]],
+    low_scaled: NDArray[np.floating[Any]],
+    mean_high: float,
+    mean_low: float,
+) -> None:
+    """Plot DCD histograms with mean lines.
 
-    # Determine common bins
+    Args:
+        ax: Matplotlib axes.
+        high_scaled: Scaled high-state durations.
+        low_scaled: Scaled low-state durations.
+        mean_high: Mean high value.
+        mean_low: Mean low value.
+    """
     all_times = np.concatenate([high_scaled, low_scaled])
     bins = np.linspace(np.min(all_times) * 0.95, np.max(all_times) * 1.05, 50)
 
-    # Plot histograms
     ax.hist(
         high_scaled,
         bins=bins,
@@ -532,10 +722,55 @@ def plot_dcd(
         linewidth=0.5,
     )
 
-    # Mean lines
     ax.axvline(mean_high, color="#E74C3C", linestyle="--", linewidth=2, alpha=0.8)
     ax.axvline(mean_low, color="#3498DB", linestyle="--", linewidth=2, alpha=0.8)
 
+
+def plot_dcd(
+    high_times: NDArray[np.floating[Any]],
+    low_times: NDArray[np.floating[Any]],
+    *,
+    ax: Axes | None = None,
+    figsize: tuple[float, float] = (10, 6),
+    title: str | None = None,
+    time_unit: str = "auto",
+    show: bool = True,
+    save_path: str | Path | None = None,
+) -> Figure:
+    """Plot Duty Cycle Distortion (DCD) analysis.
+
+    Creates overlaid histograms of high and low pulse times to visualize
+    duty cycle distortion.
+
+    Args:
+        high_times: Array of high-state durations.
+        low_times: Array of low-state durations.
+        ax: Matplotlib axes.
+        figsize: Figure size.
+        title: Plot title.
+        time_unit: Time unit.
+        show: Display plot.
+        save_path: Save path.
+
+    Returns:
+        Matplotlib Figure object.
+    """
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib is required for visualization")
+
+    fig, ax = _get_or_create_figure(ax, figsize)
+
+    # Scale times
+    time_unit, time_mult = _determine_dcd_time_unit(high_times, low_times, time_unit)
+    high_scaled = high_times * time_mult
+    low_scaled = low_times * time_mult
+
+    # Calculate statistics
+    mean_high, mean_low, duty_cycle, dcd = _compute_dcd_statistics(high_scaled, low_scaled)
+
+    # Plot histograms
+    _plot_dcd_histograms(ax, high_scaled, low_scaled, mean_high, mean_low)
+
     # Statistics box
     stats_text = (
         f"Mean High: {mean_high:.2f} {time_unit}\n"
@@ -614,6 +849,36 @@ def plot_jitter_trend(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
+    fig, ax = _setup_jitter_trend_figure(ax, figsize)
+    jitter_unit, jitter_mult = _determine_jitter_unit(jitter_values, jitter_unit)
+    jitter_scaled = jitter_values * jitter_mult
+
+    mean_val, std_val = _plot_jitter_data(ax, time_axis, jitter_scaled, jitter_unit)
+    _add_jitter_bounds(ax, time_axis, mean_val, std_val, jitter_unit, show_bounds)
+    _add_jitter_trend(ax, time_axis, jitter_scaled, jitter_unit, show_trend)
+    _format_jitter_trend_plot(ax, time_unit, jitter_unit, title)
+
+    fig.tight_layout()
+    _save_and_show_jitter_trend(fig, save_path, show)
+
+    return fig
+
+
+def _setup_jitter_trend_figure(
+    ax: Axes | None, figsize: tuple[float, float]
+) -> tuple[Figure, Axes]:
+    """Setup figure and axes for jitter trend plot.
+
+    Args:
+        ax: Existing axes or None.
+        figsize: Figure size.
+
+    Returns:
+        Tuple of (figure, axes).
+
+    Raises:
+        ValueError: If axes has no figure.
+    """
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
     else:
@@ -621,31 +886,56 @@ def plot_jitter_trend(
         if fig_temp is None:
             raise ValueError("Axes must have an associated figure")
         fig = cast("Figure", fig_temp)
+    return fig, ax
+
 
-    # Auto-select jitter unit
+def _determine_jitter_unit(
+    jitter_values: NDArray[np.floating[Any]], jitter_unit: str
+) -> tuple[str, float]:
+    """Determine jitter unit and multiplier.
+
+    Args:
+        jitter_values: Jitter value array.
+        jitter_unit: Requested unit or "auto".
+
+    Returns:
+        Tuple of (unit_str, multiplier).
+    """
     if jitter_unit == "auto":
         max_jitter = np.max(np.abs(jitter_values))
         if max_jitter < 1e-9:
-            jitter_unit = "ps"
-            jitter_mult = 1e12
+            return "ps", 1e12
         elif max_jitter < 1e-6:
-            jitter_unit = "ns"
-            jitter_mult = 1e9
+            return "ns", 1e9
         else:
-            jitter_unit = "us"
-            jitter_mult = 1e6
+            return "us", 1e6
     else:
         jitter_mult = {"s": 1, "ms": 1e3, "us": 1e6, "ns": 1e9, "ps": 1e12}.get(jitter_unit, 1e12)
+        return jitter_unit, jitter_mult
 
-    jitter_scaled = jitter_values * jitter_mult
 
-    # Plot jitter values
+def _plot_jitter_data(
+    ax: Axes,
+    time_axis: NDArray[np.floating[Any]],
+    jitter_scaled: NDArray[np.floating[Any]],
+    jitter_unit: str,
+) -> tuple[float, float]:
+    """Plot jitter data and mean line.
+
+    Args:
+        ax: Matplotlib axes.
+        time_axis: Time array.
+        jitter_scaled: Scaled jitter values.
+        jitter_unit: Jitter unit string.
+
+    Returns:
+        Tuple of (mean_val, std_val).
+    """
     ax.plot(time_axis, jitter_scaled, "b-", linewidth=0.8, alpha=0.7, label="Jitter")
 
-    mean_val = np.mean(jitter_scaled)
-    std_val = np.std(jitter_scaled)
+    mean_val = float(np.mean(jitter_scaled))
+    std_val = float(np.std(jitter_scaled))
 
-    # Mean line
     ax.axhline(
         mean_val,
         color="gray",
@@ -654,49 +944,99 @@ def plot_jitter_trend(
         label=f"Mean: {mean_val:.2f} {jitter_unit}",
     )
 
-    # Statistical bounds
-    if show_bounds:
-        ax.axhline(mean_val + 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1, alpha=0.7)
-        ax.axhline(
-            mean_val - 3 * std_val,
-            color="#E74C3C",
-            linestyle="--",
-            linewidth=1,
-            alpha=0.7,
-            label=f"±3sigma: {3 * std_val:.2f} {jitter_unit}",
-        )
-        ax.fill_between(
-            time_axis, mean_val - 3 * std_val, mean_val + 3 * std_val, alpha=0.1, color="#E74C3C"
-        )
+    return mean_val, std_val
+
+
+def _add_jitter_bounds(
+    ax: Axes,
+    time_axis: NDArray[np.floating[Any]],
+    mean_val: float,
+    std_val: float,
+    jitter_unit: str,
+    show_bounds: bool,
+) -> None:
+    """Add statistical bounds to plot.
+
+    Args:
+        ax: Matplotlib axes.
+        time_axis: Time array.
+        mean_val: Mean value.
+        std_val: Standard deviation.
+        jitter_unit: Unit string.
+        show_bounds: Whether to show bounds.
+    """
+    if not show_bounds:
+        return
+
+    ax.axhline(mean_val + 3 * std_val, color="#E74C3C", linestyle="--", linewidth=1, alpha=0.7)
+    ax.axhline(
+        mean_val - 3 * std_val,
+        color="#E74C3C",
+        linestyle="--",
+        linewidth=1,
+        alpha=0.7,
+        label=f"±3sigma: {3 * std_val:.2f} {jitter_unit}",
+    )
+    ax.fill_between(
+        time_axis, mean_val - 3 * std_val, mean_val + 3 * std_val, alpha=0.1, color="#E74C3C"
+    )
+
+
+def _add_jitter_trend(
+    ax: Axes,
+    time_axis: NDArray[np.floating[Any]],
+    jitter_scaled: NDArray[np.floating[Any]],
+    jitter_unit: str,
+    show_trend: bool,
+) -> None:
+    """Add trend line to plot.
+
+    Args:
+        ax: Matplotlib axes.
+        time_axis: Time array.
+        jitter_scaled: Scaled jitter values.
+        jitter_unit: Unit string.
+        show_trend: Whether to show trend.
+    """
+    if not show_trend:
+        return
+
+    z = np.polyfit(time_axis, jitter_scaled, 1)
+    p = np.poly1d(z)
+    ax.plot(
+        time_axis, p(time_axis), "g-", linewidth=2, label=f"Trend: {z[0]:.2e} {jitter_unit}/unit"
+    )
 
-    # Trend line
-    if show_trend:
-        z = np.polyfit(time_axis, jitter_scaled, 1)
-        p = np.poly1d(z)
-        ax.plot(
-            time_axis,
-            p(time_axis),
-            "g-",
-            linewidth=2,
-            label=f"Trend: {z[0]:.2e} {jitter_unit}/unit",
-        )
 
+def _format_jitter_trend_plot(
+    ax: Axes, time_unit: str, jitter_unit: str, title: str | None
+) -> None:
+    """Format jitter trend plot axes and labels.
+
+    Args:
+        ax: Matplotlib axes.
+        time_unit: Time unit string.
+        jitter_unit: Jitter unit string.
+        title: Plot title.
+    """
     ax.set_xlabel(f"Time ({time_unit})" if time_unit != "auto" else "Sample Index", fontsize=11)
     ax.set_ylabel(f"Jitter ({jitter_unit})", fontsize=11)
     ax.grid(True, alpha=0.3)
     ax.legend(loc="upper right")
 
-    if title:
-        ax.set_title(title, fontsize=12, fontweight="bold")
-    else:
-        ax.set_title("Jitter Trend Analysis", fontsize=12, fontweight="bold")
+    final_title = title if title else "Jitter Trend Analysis"
+    ax.set_title(final_title, fontsize=12, fontweight="bold")
 
-    fig.tight_layout()
 
+def _save_and_show_jitter_trend(fig: Figure, save_path: str | Path | None, show: bool) -> None:
+    """Save and/or show jitter trend plot.
+
+    Args:
+        fig: Matplotlib figure.
+        save_path: Path to save file.
+        show: Whether to display interactively.
+    """
     if save_path is not None:
         fig.savefig(save_path, dpi=300, bbox_inches="tight")
-
     if show:
         plt.show()
-
-    return fig