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

oscura/{exploratory → jupyter/exploratory}/legacy.py

@@ -5,7 +5,7 @@ mixed logic families and multi-voltage domains.
 
 
 Example:
-    >>> from oscura.exploratory.legacy import detect_logic_families_multi_channel
+    >>> from oscura.jupyter.exploratory.legacy import detect_logic_families_multi_channel
     >>> families = detect_logic_families_multi_channel(channels)
     >>> for ch, result in families.items():
     ...     print(f"Channel {ch}: {result['family']} (confidence={result['confidence']:.2f})")
@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from oscura.core.types import WaveformTrace
 
 # Logic family specifications per IEEE/JEDEC standards
-LOGIC_FAMILY_SPECS = {
+LOGIC_FAMILY_SPECS: dict[str, dict[str, float | None]] = {
     "TTL": {
         "vil_max": 0.8,
         "vih_min": 2.0,
@@ -152,90 +152,138 @@ def detect_logic_families_multi_channel(
         confidence_thresholds = {"high": 0.9, "medium": 0.7}
 
     # Convert list to dict if needed
-    if isinstance(channels, list):
-        channels = dict(enumerate(channels))
+    channel_dict = dict(enumerate(channels)) if isinstance(channels, list) else channels
 
     results = {}
+    for ch_id, trace in channel_dict.items():
+        voltage_levels = _extract_voltage_levels(trace.data)
+        candidates = _score_all_logic_families(voltage_levels, voltage_tolerance)
+        result = _build_logic_family_result(
+            voltage_levels, candidates, min_edges_for_detection, warn_on_degradation
+        )
+        results[ch_id] = result
 
-    for ch_id, trace in channels.items():
-        data = trace.data
+    return results
 
-        # Extract voltage percentiles
-        p10 = np.percentile(data, 10)
-        np.percentile(data, 50)
-        p90 = np.percentile(data, 90)
 
-        # Estimate low and high levels
-        v_low = p10
-        v_high = p90
-        v_high - v_low
+def _extract_voltage_levels(data: NDArray[np.float64]) -> dict[str, float]:
+    """Extract voltage levels from channel data.
 
-        # Count edges for confidence
-        threshold = (v_low + v_high) / 2
-        edges = np.sum(np.abs(np.diff(data > threshold)))
+    Args:
+        data: Channel voltage data.
 
-        # Score each logic family
-        candidates = []
+    Returns:
+        Dict with v_low, v_high, threshold, edges.
+    """
+    v_low = float(np.percentile(data, 10))
+    v_high = float(np.percentile(data, 90))
+    threshold = (v_low + v_high) / 2
+    edges = int(np.sum(np.abs(np.diff(data > threshold))))
 
-        for family_name, specs in LOGIC_FAMILY_SPECS.items():
-            score = _score_logic_family(v_low, v_high, specs, voltage_tolerance)  # type: ignore[arg-type]
-            if score > 0:
-                candidates.append((family_name, score))
+    return {"v_low": v_low, "v_high": v_high, "threshold": threshold, "edges": edges}
 
-        # Sort by score descending
-        candidates.sort(key=lambda x: x[1], reverse=True)
 
-        if not candidates:
-            # No match found
-            result = LogicFamilyResult(
-                family="UNKNOWN",
-                confidence=0.0,
-                v_low=v_low,
-                v_high=v_high,
-                alternatives=[],
-                degradation_warning="No matching logic family found",
-            )
-        else:
-            best_family, best_score = candidates[0]
-            confidence = min(1.0, best_score)
-
-            # Reduce confidence if insufficient edges
-            if edges < min_edges_for_detection:
-                confidence *= 0.5
-
-            # Check for ambiguity (multiple families close in score)
-            alternatives = [
-                (name, score) for name, score in candidates[1:4] if best_score - score < 0.2
-            ]
-
-            # Check for degradation
-            degradation_warning = None
-            deviation_pct = 0.0
-
-            if warn_on_degradation:
-                specs = LOGIC_FAMILY_SPECS[best_family]
-                if specs["voh_min"] is not None:  # type: ignore[index]
-                    expected_voh = specs["voh_min"]  # type: ignore[index]
-                    if v_high < expected_voh:
-                        deviation_pct = 100 * (expected_voh - v_high) / expected_voh
-                        if deviation_pct > 10:
-                            degradation_warning = (
-                                f"V_high below spec (expected >= {expected_voh:.3f}V)"
-                            )
-
-            result = LogicFamilyResult(
-                family=best_family,
-                confidence=confidence,
-                v_low=v_low,
-                v_high=v_high,
-                alternatives=alternatives,
-                degradation_warning=degradation_warning,
-                deviation_pct=deviation_pct,
-            )
+def _score_all_logic_families(
+    voltage_levels: dict[str, float], tolerance: float
+) -> list[tuple[str, float]]:
+    """Score all logic families against measured voltage levels.
 
-        results[ch_id] = result
+    Args:
+        voltage_levels: Dict with v_low and v_high.
+        tolerance: Voltage tolerance for matching.
 
-    return results
+    Returns:
+        List of (family_name, score) tuples sorted by score.
+    """
+    candidates = []
+    for family_name, specs in LOGIC_FAMILY_SPECS.items():
+        score = _score_logic_family(
+            voltage_levels["v_low"], voltage_levels["v_high"], specs, tolerance
+        )
+        if score > 0:
+            candidates.append((family_name, score))
+
+    candidates.sort(key=lambda x: x[1], reverse=True)
+    return candidates
+
+
+def _build_logic_family_result(
+    voltage_levels: dict[str, float],
+    candidates: list[tuple[str, float]],
+    min_edges: int,
+    warn_on_degradation: bool,
+) -> LogicFamilyResult:
+    """Build LogicFamilyResult from voltage data and candidates.
+
+    Args:
+        voltage_levels: Dict with v_low, v_high, edges.
+        candidates: Sorted list of (family, score) tuples.
+        min_edges: Minimum edges for reliable detection.
+        warn_on_degradation: Check for signal degradation.
+
+    Returns:
+        LogicFamilyResult with classification.
+    """
+    v_low, v_high, edges = (
+        voltage_levels["v_low"],
+        voltage_levels["v_high"],
+        voltage_levels["edges"],
+    )
+
+    if not candidates:
+        return LogicFamilyResult(
+            family="UNKNOWN",
+            confidence=0.0,
+            v_low=v_low,
+            v_high=v_high,
+            alternatives=[],
+            degradation_warning="No matching logic family found",
+        )
+
+    best_family, best_score = candidates[0]
+    confidence = min(1.0, best_score)
+    if edges < min_edges:
+        confidence *= 0.5
+
+    alternatives = [(n, s) for n, s in candidates[1:4] if best_score - s < 0.2]
+    degradation_warning, deviation_pct = _check_degradation(
+        best_family, v_high, warn_on_degradation
+    )
+
+    return LogicFamilyResult(
+        family=best_family,
+        confidence=confidence,
+        v_low=v_low,
+        v_high=v_high,
+        alternatives=alternatives,
+        degradation_warning=degradation_warning,
+        deviation_pct=deviation_pct,
+    )
+
+
+def _check_degradation(family: str, v_high: float, check: bool) -> tuple[str | None, float]:
+    """Check for signal degradation against spec.
+
+    Args:
+        family: Logic family name.
+        v_high: Measured high voltage.
+        check: Whether to perform check.
+
+    Returns:
+        Tuple of (warning_message, deviation_percent).
+    """
+    if not check:
+        return None, 0.0
+
+    specs = LOGIC_FAMILY_SPECS[family]
+    expected_voh = specs["voh_min"]
+
+    if expected_voh is not None and v_high < expected_voh:
+        deviation_pct = 100 * (expected_voh - v_high) / expected_voh
+        if deviation_pct > 10:
+            return f"V_high below spec (expected >= {expected_voh:.3f}V)", deviation_pct
+
+    return None, 0.0
 
 
 def _score_logic_family(
@@ -309,6 +357,104 @@ class CrossCorrelationResult:
     normalized_signal2: NDArray[np.float64] | None = None
 
 
+def _prepare_signals_for_correlation(
+    data1: NDArray[np.float64], data2: NDArray[np.float64]
+) -> tuple[NDArray[np.float64], NDArray[np.float64], int]:
+    """Prepare signals for correlation by normalizing and aligning.
+
+    Args:
+        data1: First signal data.
+        data2: Second signal data.
+
+    Returns:
+        Tuple of (norm1, norm2_corrected, min_len).
+    """
+    norm1 = _normalize_to_logic_levels(data1)
+    norm2 = _normalize_to_logic_levels(data2)
+    dc_offset = np.mean(norm1) - np.mean(norm2)
+    norm2_corrected = norm2 + dc_offset
+    min_len = min(len(norm1), len(norm2_corrected))
+    return norm1[:min_len], norm2_corrected[:min_len], min_len
+
+
+def _compute_correlation_and_lag(
+    norm1: NDArray[np.float64], norm2: NDArray[np.float64]
+) -> tuple[float, int]:
+    """Compute correlation coefficient and lag.
+
+    Args:
+        norm1: Normalized first signal.
+        norm2: Normalized second signal.
+
+    Returns:
+        Tuple of (correlation, lag_samples).
+    """
+    correlation = np.corrcoef(norm1, norm2)[0, 1]
+    xcorr = np.correlate(norm1 - np.mean(norm1), norm2 - np.mean(norm2), mode="full")
+    lag_samples = xcorr.argmax() - (len(norm1) - 1)
+    return float(correlation), int(lag_samples)
+
+
+def _compute_reference_offset(
+    data1: NDArray[np.float64], data2: NDArray[np.float64], correlation: float
+) -> tuple[float, float]:
+    """Compute reference voltage offset and confidence.
+
+    Args:
+        data1: First signal data.
+        data2: Second signal data.
+        correlation: Correlation coefficient.
+
+    Returns:
+        Tuple of (ref_offset_mv, confidence).
+    """
+    v1_min: float = float(np.min(data1))
+    v2_min: float = float(np.min(data2))
+    ref_offset_mv: float = (v2_min - v1_min) * 1000
+    confidence: float = abs(correlation) * (1 - min(abs(ref_offset_mv) / 1000, 1.0))
+    return float(ref_offset_mv), float(confidence)
+
+
+def _detect_reference_drift(
+    data1: NDArray[np.float64],
+    data2: NDArray[np.float64],
+    sample_rate: float,
+    drift_window_ms: float,
+    min_len: int,
+) -> tuple[bool, float | None]:
+    """Detect time-varying reference drift.
+
+    Args:
+        data1: First signal data.
+        data2: Second signal data.
+        sample_rate: Sample rate in Hz.
+        drift_window_ms: Window size in ms.
+        min_len: Minimum length of signals.
+
+    Returns:
+        Tuple of (drift_detected, drift_rate).
+    """
+    window_samples = int(drift_window_ms * 1e-3 * sample_rate)
+    n_windows = min_len // window_samples
+
+    if n_windows < 2:
+        return False, None
+
+    offsets = [
+        np.mean(data1[i * window_samples : (i + 1) * window_samples])
+        - np.mean(data2[i * window_samples : (i + 1) * window_samples])
+        for i in range(n_windows)
+    ]
+
+    offset_change = abs(offsets[-1] - offsets[0])
+    drift_rate_val = offset_change / (n_windows * drift_window_ms)
+
+    if drift_rate_val > 0.1:
+        return True, float(drift_rate_val)
+
+    return False, None
+
+
 def cross_correlate_multi_reference(
     signal1: WaveformTrace,
     signal2: WaveformTrace,
@@ -341,82 +487,33 @@ def cross_correlate_multi_reference(
     References:
         LEGACY-002: Multi-Reference Voltage Signal Correlation
     """
-    data1 = signal1.data
-    data2 = signal2.data
+    # Setup: normalize and align signals
+    norm1, norm2_corrected, min_len = _prepare_signals_for_correlation(signal1.data, signal2.data)
 
-    # Normalize each signal to [0, 1]
-    norm1 = _normalize_to_logic_levels(data1)
-    norm2 = _normalize_to_logic_levels(data2)
-
-    # Estimate DC offset between normalized signals
-    dc_offset = np.mean(norm1) - np.mean(norm2)
+    # Processing: compute correlation
+    correlation, lag_samples = _compute_correlation_and_lag(norm1, norm2_corrected)
+    ref_offset_mv, confidence = _compute_reference_offset(signal1.data, signal2.data, correlation)
 
-    # Apply offset correction
-    norm2_corrected = norm2 + dc_offset
-
-    # Compute cross-correlation
-    min_len = min(len(norm1), len(norm2_corrected))
-    norm1 = norm1[:min_len]
-    norm2_corrected = norm2_corrected[:min_len]
-
-    correlation = np.corrcoef(norm1, norm2_corrected)[0, 1]
-
-    # Find lag using cross-correlation
-    xcorr = np.correlate(
-        norm1 - np.mean(norm1), norm2_corrected - np.mean(norm2_corrected), mode="full"
+    # Formatting: detect drift if requested
+    drift_result = (
+        _detect_reference_drift(
+            signal1.data, signal2.data, signal1.metadata.sample_rate, drift_window_ms, min_len
+        )
+        if detect_drift
+        else (False, None)
     )
-    lag_samples = xcorr.argmax() - (len(norm1) - 1)
-
-    # Convert lag to nanoseconds
-    sample_rate = signal1.metadata.sample_rate
-    lag_ns = lag_samples / sample_rate * 1e9
-
-    # Estimate reference voltage offset
-    # Reference offset is how much signal2's ground differs from signal1's ground
-    v1_min = np.min(data1)
-    v2_min = np.min(data2)
-
-    # Reference offset is difference in ground levels (signal2 relative to signal1)
-    ref_offset_mv = (v2_min - v1_min) * 1000
 
-    # Confidence calculation
-    offset_uncertainty_mv = abs(ref_offset_mv) * 0.1  # 10% uncertainty
-    confidence = abs(correlation) * (1 - min(abs(ref_offset_mv) / 1000, 1.0))
-
-    # Drift detection
-    drift_detected = False
-    drift_rate = None
-
-    if detect_drift:
-        # Calculate offset in windows
-        window_samples = int(drift_window_ms * 1e-3 * sample_rate)
-        n_windows = min_len // window_samples
-
-        if n_windows >= 2:
-            offsets = []
-            for i in range(n_windows):
-                start = i * window_samples
-                end = start + window_samples
-                win_offset = np.mean(data1[start:end]) - np.mean(data2[start:end])
-                offsets.append(win_offset)
-
-            # Check for drift
-            offset_change = abs(offsets[-1] - offsets[0])
-            drift_rate_val = offset_change / (n_windows * drift_window_ms)
-
-            if drift_rate_val > 0.1:  # V/ms threshold
-                drift_detected = True
-                drift_rate = drift_rate_val
+    lag_ns = lag_samples / signal1.metadata.sample_rate * 1e9
 
     return CrossCorrelationResult(
         correlation=float(correlation),
         confidence=float(confidence),
         ref_offset_mv=float(ref_offset_mv),
-        offset_uncertainty_mv=float(offset_uncertainty_mv),
+        offset_uncertainty_mv=float(abs(ref_offset_mv) * 0.1),
         lag_samples=int(lag_samples),
         lag_ns=float(lag_ns),
-        drift_detected=drift_detected,
-        drift_rate=drift_rate,
+        drift_detected=drift_result[0],
+        drift_rate=drift_result[1],
         normalized_signal1=norm1,
         normalized_signal2=norm2_corrected,
     )
@@ -511,36 +608,95 @@ def assess_signal_quality(
     if logic_family not in LOGIC_FAMILY_SPECS:
         logic_family = "TTL"  # Default fallback
 
-    specs = LOGIC_FAMILY_SPECS[logic_family]
+    specs_dict: dict[str, float | None] = dict(LOGIC_FAMILY_SPECS[logic_family])
     data = signal.data
     sample_rate = signal.metadata.sample_rate
-    n_samples = len(data)
-
-    # Threshold for high/low classification
-    threshold = (specs["vil_max"] + specs["vih_min"]) / 2  # type: ignore[index]
 
-    # Classify samples
+    # Classify samples and check violations
+    vil_max = specs_dict["vil_max"]
+    vih_min = specs_dict["vih_min"]
+    assert vil_max is not None and vih_min is not None
+    threshold = (vil_max + vih_min) / 2
     is_high = data > threshold
-    is_low = ~is_high
+    violations, voh_violations, vol_violations = _check_voltage_violations(
+        data, is_high, specs_dict, sample_rate
+    )
 
-    # Count violations
+    # Calculate margins and status
     high_samples = data[is_high]
-    low_samples = data[is_low]
+    low_samples = data[~is_high]
+    min_margin_mv = _calculate_voltage_margins(high_samples, low_samples, specs_dict)
+    status = _determine_quality_status(min_margin_mv)
+
+    # Calculate violation rates
+    n_high = len(high_samples)
+    n_low = len(low_samples)
+    voh_rate = voh_violations / n_high if n_high > 0 else 0.0
+    vol_rate = vol_violations / n_low if n_low > 0 else 0.0
+
+    # Aging analysis
+    aging_result = None
+    if check_aging and len(data) > 1000:
+        aging_result = _analyze_aging(
+            data,
+            high_samples,
+            specs_dict,
+            sample_rate,
+            time_window_s,
+            voh_violations,
+            vol_violations,
+        )
+
+    return SignalQualityResult(
+        status=status,
+        violation_count=voh_violations + vol_violations,
+        total_samples=len(data),
+        min_margin_mv=min_margin_mv,
+        violations=violations,
+        voh_violations=voh_violations,
+        vol_violations=vol_violations,
+        voh_rate=voh_rate,
+        vol_rate=vol_rate,
+        failure_diagnosis=aging_result.get("diagnosis") if aging_result else None,
+        time_to_failure_s=aging_result.get("time_to_failure") if aging_result else None,
+        drift_rate_mv_per_s=aging_result.get("drift_rate") if aging_result else None,
+    )
+
+
+def _check_voltage_violations(
+    data: NDArray[np.float64],
+    is_high: NDArray[np.bool_],
+    specs: dict[str, float | None],
+    sample_rate: float,
+) -> tuple[list[dict[str, Any]], int, int]:
+    """Check for VOH and VOL violations.
 
-    voh_min = specs["voh_min"]  # type: ignore[index]
-    vol_max = specs["vol_max"]  # type: ignore[index]
+    Args:
+        data: Signal data.
+        is_high: Boolean mask for high samples.
+        specs: Logic family specifications.
+        sample_rate: Sample rate in Hz.
 
+    Returns:
+        Tuple of (violations list, voh_violation_count, vol_violation_count).
+    """
+    high_samples = data[is_high]
+    low_samples = data[~is_high]
+
+    voh_min = specs["voh_min"]
+    vol_max = specs["vol_max"]
+
+    violations = []
     voh_violations = 0
     vol_violations = 0
-    violations = []
 
-    # Check VOH violations (high samples below spec)
+    # Check VOH violations
     if voh_min is not None and len(high_samples) > 0:
         voh_mask = high_samples < voh_min
-        voh_violations = np.sum(voh_mask)
+        voh_violations = int(np.sum(voh_mask))
         if voh_violations > 0:
             violation_indices = np.where(is_high)[0][voh_mask]
-            for idx in violation_indices[:10]:  # First 10 violations
+            for idx in violation_indices[:10]:
                 violations.append(
                     {
                         "timestamp_us": idx / sample_rate * 1e6,
@@ -550,12 +706,12 @@ def assess_signal_quality(
                     }
                 )
 
-    # Check VOL violations (low samples above spec)
+    # Check VOL violations
     if vol_max is not None and len(low_samples) > 0:
         vol_mask = low_samples > vol_max
-        vol_violations = np.sum(vol_mask)
+        vol_violations = int(np.sum(vol_mask))
         if vol_violations > 0:
-            violation_indices = np.where(is_low)[0][vol_mask]
+            violation_indices = np.where(~is_high)[0][vol_mask]
             for idx in violation_indices[:10]:
                 violations.append(
                     {
@@ -566,79 +722,113 @@ def assess_signal_quality(
                     }
                 )
 
-    total_violations = voh_violations + vol_violations
+    return violations, voh_violations, vol_violations
+
+
+def _calculate_voltage_margins(
+    high_samples: NDArray[np.float64],
+    low_samples: NDArray[np.float64],
+    specs: dict[str, float | None],
+) -> float:
+    """Calculate minimum voltage margin to spec.
+
+    Args:
+        high_samples: High-level samples.
+        low_samples: Low-level samples.
+        specs: Logic family specifications.
 
-    # Calculate margins
-    margins = []
+    Returns:
+        Minimum margin in mV.
+    """
+    voh_min = specs["voh_min"]
+    vol_max = specs["vol_max"]
+
+    margins: list[float] = []
     if len(high_samples) > 0 and voh_min is not None:
-        margins.extend((high_samples - voh_min) * 1000)  # Convert to mV
+        margins.extend((high_samples - voh_min) * 1000)
     if len(low_samples) > 0 and vol_max is not None:
         margins.extend((vol_max - low_samples) * 1000)
 
-    min_margin_mv = min(margins) if margins else 0.0
+    return min(margins) if margins else 0.0
+
+
+def _determine_quality_status(min_margin_mv: float) -> Literal["OK", "WARNING", "CRITICAL"]:
+    """Determine quality status from voltage margin.
 
-    # Determine status
+    Args:
+        min_margin_mv: Minimum voltage margin in mV.
+
+    Returns:
+        Quality status.
+    """
     if min_margin_mv < 100:
-        status: Literal["OK", "WARNING", "CRITICAL"] = "CRITICAL"
+        return "CRITICAL"
     elif min_margin_mv < 200:
-        status = "WARNING"
+        return "WARNING"
     else:
-        status = "OK"
+        return "OK"
 
-    # Calculate rates
-    n_high = len(high_samples)
-    n_low = len(low_samples)
-    voh_rate = voh_violations / n_high if n_high > 0 else 0.0
-    vol_rate = vol_violations / n_low if n_low > 0 else 0.0
 
-    # Aging analysis
-    failure_diagnosis = None
-    time_to_failure_s = None
-    drift_rate_mv_per_s = None
-
-    if check_aging and n_samples > 1000:
-        # Calculate drift over time
-        window_samples = int(time_window_s * sample_rate)
-        n_windows = n_samples // window_samples
-
-        if n_windows >= 2:
-            window_means = [
-                np.mean(data[i * window_samples : (i + 1) * window_samples])
-                for i in range(n_windows)
-            ]
-
-            drift = window_means[-1] - window_means[0]
-            drift_rate_mv_per_s = drift * 1000 / (n_windows * time_window_s)
-
-            if abs(drift_rate_mv_per_s) > 0.1:  # Significant drift
-                # Estimate time to failure
-                if voh_min is not None and drift_rate_mv_per_s < 0:
-                    current_margin = np.mean(high_samples) - voh_min
-                    if current_margin > 0:
-                        time_to_failure_s = current_margin * 1000 / abs(drift_rate_mv_per_s)
-
-                # Diagnose failure mode
-                if voh_violations > vol_violations:
-                    failure_diagnosis = "Degraded output driver (weak high)"
-                elif vol_violations > voh_violations:
-                    failure_diagnosis = "Degraded output driver (weak low)"
-                else:
-                    failure_diagnosis = "General signal degradation"
+def _analyze_aging(
+    data: NDArray[np.float64],
+    high_samples: NDArray[np.float64],
+    specs: dict[str, float | None],
+    sample_rate: float,
+    time_window_s: float,
+    voh_violations: int,
+    vol_violations: int,
+) -> dict[str, Any] | None:
+    """Analyze signal for aging and degradation.
 
-    return SignalQualityResult(
-        status=status,
-        violation_count=total_violations,
-        total_samples=n_samples,
-        min_margin_mv=min_margin_mv,
-        violations=violations,
-        voh_violations=voh_violations,
-        vol_violations=vol_violations,
-        voh_rate=voh_rate,
-        vol_rate=vol_rate,
-        failure_diagnosis=failure_diagnosis,
-        time_to_failure_s=time_to_failure_s,
-        drift_rate_mv_per_s=drift_rate_mv_per_s,
-    )
+    Args:
+        data: Full signal data.
+        high_samples: High-level samples.
+        specs: Logic family specifications.
+        sample_rate: Sample rate in Hz.
+        time_window_s: Window size for drift analysis.
+        voh_violations: Count of VOH violations.
+        vol_violations: Count of VOL violations.
+
+    Returns:
+        Dict with diagnosis, time_to_failure, and drift_rate, or None.
+    """
+    window_samples = int(time_window_s * sample_rate)
+    n_windows = len(data) // window_samples
+
+    if n_windows < 2:
+        return None
+
+    window_means = [
+        np.mean(data[i * window_samples : (i + 1) * window_samples]) for i in range(n_windows)
+    ]
+
+    drift = window_means[-1] - window_means[0]
+    drift_rate_mv_per_s = drift * 1000 / (n_windows * time_window_s)
+
+    if abs(drift_rate_mv_per_s) <= 0.1:
+        return None
+
+    # Estimate time to failure
+    time_to_failure = None
+    voh_min = specs["voh_min"]
+    if voh_min is not None and drift_rate_mv_per_s < 0:
+        current_margin = np.mean(high_samples) - voh_min
+        if current_margin > 0:
+            time_to_failure = current_margin * 1000 / abs(drift_rate_mv_per_s)
+
+    # Diagnose failure mode
+    if voh_violations > vol_violations:
+        diagnosis = "Degraded output driver (weak high)"
+    elif vol_violations > voh_violations:
+        diagnosis = "Degraded output driver (weak low)"
+    else:
+        diagnosis = "General signal degradation"
+
+    return {
+        "diagnosis": diagnosis,
+        "time_to_failure": time_to_failure,
+        "drift_rate": drift_rate_mv_per_s,
+    }
 
 
 @dataclass
@@ -773,49 +963,81 @@ def _is_bimodal(data: NDArray[np.float64], bins: int = 50) -> bool:
     hist, bin_edges = np.histogram(data, bins=bins)
     centers = (bin_edges[:-1] + bin_edges[1:]) / 2
 
-    # Find peaks (including edge bins for perfect bimodal signals)
+    # Find peaks in histogram
+    peaks = _find_histogram_peaks(hist, centers)
+
+    # Too many peaks suggests analog signal
+    if len(peaks) >= 4:
+        return False
+
+    # Check if distribution is bimodal
+    if len(peaks) == 2 or len(peaks) == 3:
+        return _is_bimodal_distribution(data, peaks)
+
+    return False
+
+
+def _find_histogram_peaks(
+    hist: NDArray[np.int64], centers: NDArray[np.float64]
+) -> list[tuple[int, int, float]]:
+    """Find peaks in histogram.
+
+    Args:
+        hist: Histogram counts.
+        centers: Bin centers.
+
+    Returns:
+        List of (index, count, center) tuples.
+    """
     threshold = 0.1 * np.max(hist)
     peaks = []
 
     # Check first bin (only needs to be > right neighbor)
     if len(hist) > 1 and hist[0] > hist[1] and hist[0] > threshold:
-        peaks.append((0, hist[0], centers[0]))
+        peaks.append((0, int(hist[0]), float(centers[0])))
 
     # Check middle bins (need to be > both neighbors)
     for i in range(1, len(hist) - 1):
         if hist[i] > hist[i - 1] and hist[i] > hist[i + 1] and hist[i] > threshold:
-            peaks.append((i, hist[i], centers[i]))
+            peaks.append((i, int(hist[i]), float(centers[i])))
 
     # Check last bin (only needs to be > left neighbor)
     if len(hist) > 1 and hist[-1] > hist[-2] and hist[-1] > threshold:
-        peaks.append((len(hist) - 1, hist[-1], centers[-1]))
+        peaks.append((len(hist) - 1, int(hist[-1]), float(centers[-1])))
 
-    # Too many peaks suggests analog signal (e.g., sine wave)
-    if len(peaks) >= 4:
-        return False
+    return peaks
 
-    # Bimodal if exactly 2-3 significant peaks that are well-separated
-    if len(peaks) == 2 or len(peaks) == 3:
-        peaks.sort(key=lambda x: x[1], reverse=True)
 
-        # Check if peaks are well-separated (digital signals have peaks at extremes)
-        v_min, v_max = np.min(data), np.max(data)
-        v_range = v_max - v_min
-        if v_range == 0:
-            return False
+def _is_bimodal_distribution(
+    data: NDArray[np.float64], peaks: list[tuple[int, int, float]]
+) -> bool:
+    """Check if peaks indicate bimodal distribution.
 
-        # Normalize peak positions
-        peak_positions = [(p[2] - v_min) / v_range for p in peaks[:2]]
+    Args:
+        data: Signal data.
+        peaks: List of (index, count, center) tuples.
 
-        # Digital signals have one peak < 0.4 and one peak > 0.6
-        has_low_peak = any(p < 0.4 for p in peak_positions)
-        has_high_peak = any(p > 0.6 for p in peak_positions)
+    Returns:
+        True if distribution is bimodal.
+    """
+    # Sort peaks by count (descending)
+    peaks.sort(key=lambda x: x[1], reverse=True)
+
+    # Check if peaks are well-separated
+    v_min, v_max = np.min(data), np.max(data)
+    v_range = v_max - v_min
+    if v_range == 0:
+        return False
 
-        # Second peak should be significant
-        if has_low_peak and has_high_peak and peaks[1][1] > 0.3 * peaks[0][1]:
-            return True
+    # Normalize peak positions
+    peak_positions = [(p[2] - v_min) / v_range for p in peaks[:2]]
 
-    return False
+    # Digital signals have one peak < 0.4 and one peak > 0.6
+    has_low_peak = any(p < 0.4 for p in peak_positions)
+    has_high_peak = any(p > 0.6 for p in peak_positions)
+
+    # Second peak should be significant
+    return has_low_peak and has_high_peak and peaks[1][1] > 0.3 * peaks[0][1]
 
 
 __all__ = [