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

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

@@ -5,7 +5,7 @@ functions for pass/fail testing against known-good waveforms.
 
 
 Example:
-    >>> from oscura.comparison import create_golden, compare_to_golden
+    >>> from oscura.utils.comparison import create_golden, compare_to_golden
     >>> golden = create_golden(reference_trace)
     >>> result = compare_to_golden(measured_trace, golden)
 
@@ -301,8 +301,7 @@ def compare_to_golden(
 ) -> GoldenComparisonResult:
     """Compare a trace to a golden reference.
 
-    Tests if the measured trace falls within the tolerance bounds
-    of the golden reference.
+    Tests if the measured trace falls within the tolerance bounds.
 
     Args:
         trace: Measured trace to compare.
@@ -315,73 +314,107 @@ def compare_to_golden(
 
     Example:
         >>> result = compare_to_golden(measured, golden)
-        >>> if result.passed:
-        ...     print("PASS")
+        >>> if result.passed: print("PASS")
     """
+    measured, reference, upper, lower = _prepare_data(trace, golden, interpolate)
+
+    if align and len(measured) > 10:
+        measured = _align_signals(measured, reference)
+
+    violations = _find_violations(measured, upper, lower)
+    deviation = measured - reference
+    margin = _compute_margin(measured, upper, lower)
+    margin_pct = (margin / golden.tolerance * 100) if golden.tolerance > 0 else None
+
+    statistics = _compute_statistics(measured, reference, deviation)
+
+    return GoldenComparisonResult(
+        passed=violations["count"] == 0,
+        num_violations=violations["count"],
+        violation_rate=violations["rate"],
+        max_deviation=float(np.max(np.abs(deviation))),
+        rms_deviation=float(np.sqrt(np.mean(deviation**2))),
+        upper_violations=violations["upper"] if len(violations["upper"]) > 0 else None,
+        lower_violations=violations["lower"] if len(violations["lower"]) > 0 else None,
+        margin=margin,
+        margin_percentage=margin_pct,
+        statistics=statistics,
+    )
+
+
+def _prepare_data(
+    trace: WaveformTrace, golden: GoldenReference, interpolate: bool
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Prepare and align data arrays."""
     measured = trace.data.astype(np.float64)
-    reference = golden.data.copy()
-    upper = golden.upper_bound.copy()
-    lower = golden.lower_bound.copy()
+    reference, upper, lower = (
+        golden.data.copy(),
+        golden.upper_bound.copy(),
+        golden.lower_bound.copy(),
+    )
 
-    # Handle length mismatch
     if len(measured) != len(reference):
         if interpolate:
-            # Interpolate measured to match reference length
-            x_measured = np.linspace(0, 1, len(measured))
-            x_reference = np.linspace(0, 1, len(reference))
+            x_measured, x_reference = (
+                np.linspace(0, 1, len(measured)),
+                np.linspace(0, 1, len(reference)),
+            )
             measured = np.interp(x_reference, x_measured, measured)
         else:
-            # Truncate to shorter length
             min_len = min(len(measured), len(reference))
-            measured = measured[:min_len]
-            reference = reference[:min_len]
-            upper = upper[:min_len]
-            lower = lower[:min_len]
+            measured, reference, upper, lower = (
+                measured[:min_len],
+                reference[:min_len],
+                upper[:min_len],
+                lower[:min_len],
+            )
 
-    # Optionally align by cross-correlation
-    if align and len(measured) > 10:
-        from scipy import signal as sp_signal
+    return measured, reference, upper, lower
 
-        corr = sp_signal.correlate(measured, reference, mode="same")
-        shift = len(measured) // 2 - np.argmax(corr)
-        if abs(shift) < len(measured) // 4:  # Only shift if reasonable
-            measured = np.roll(measured, -shift)
 
-    # Find violations
-    upper_viol = np.where(measured > upper)[0]
-    lower_viol = np.where(measured < lower)[0]
-    all_violations = np.union1d(upper_viol, lower_viol)
+def _align_signals(
+    measured: NDArray[np.float64], reference: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    """Align signals using cross-correlation."""
+    from scipy import signal as sp_signal
 
-    num_violations = len(all_violations)
-    violation_rate = num_violations / len(measured) if len(measured) > 0 else 0.0
+    corr = sp_signal.correlate(measured, reference, mode="same")
+    shift = len(measured) // 2 - np.argmax(corr)
+    return np.roll(measured, -shift) if abs(shift) < len(measured) // 4 else measured
 
-    # Compute deviation statistics
-    deviation = measured - reference
-    max_deviation = float(np.max(np.abs(deviation)))
-    rms_deviation = float(np.sqrt(np.mean(deviation**2)))
 
-    # Compute margin
-    upper_margin = float(np.min(upper - measured))
-    lower_margin = float(np.min(measured - lower))
-    margin = min(upper_margin, lower_margin)
+def _find_violations(
+    measured: NDArray[np.float64], upper: NDArray[np.float64], lower: NDArray[np.float64]
+) -> dict[str, Any]:
+    """Find tolerance violations."""
+    upper_viol, lower_viol = np.where(measured > upper)[0], np.where(measured < lower)[0]
+    all_violations = np.union1d(upper_viol, lower_viol)
+    return {
+        "upper": upper_viol,
+        "lower": lower_viol,
+        "count": len(all_violations),
+        "rate": len(all_violations) / len(measured) if len(measured) > 0 else 0.0,
+    }
 
-    # Margin as percentage of tolerance
-    margin_pct = (margin / golden.tolerance * 100) if golden.tolerance > 0 else None
 
-    # Additional statistics
-    # Handle constant data (zero std) for correlation calculation
-    measured_std = np.std(measured)
-    reference_std = np.std(reference)
+def _compute_margin(
+    measured: NDArray[np.float64], upper: NDArray[np.float64], lower: NDArray[np.float64]
+) -> float:
+    """Compute minimum margin to tolerance bounds."""
+    return min(float(np.min(upper - measured)), float(np.min(measured - lower)))
+
+
+def _compute_statistics(
+    measured: NDArray[np.float64], reference: NDArray[np.float64], deviation: NDArray[np.float64]
+) -> dict[str, float]:
+    """Compute deviation and correlation statistics."""
+    measured_std, reference_std = np.std(measured), np.std(reference)
     if measured_std == 0 or reference_std == 0:
-        # For constant data, correlation is undefined (NaN) or 1.0 if both are equal
-        if np.allclose(measured, reference):
-            correlation = 1.0
-        else:
-            correlation = float("nan")
+        correlation = 1.0 if np.allclose(measured, reference) else float("nan")
     else:
         correlation = float(np.corrcoef(measured, reference)[0, 1])
 
-    statistics = {
+    return {
         "mean_deviation": float(np.mean(deviation)),
         "std_deviation": float(np.std(deviation)),
         "max_positive_deviation": float(np.max(deviation)),
@@ -389,19 +422,6 @@ def compare_to_golden(
         "correlation": correlation,
     }
 
-    return GoldenComparisonResult(
-        passed=num_violations == 0,
-        num_violations=num_violations,
-        violation_rate=violation_rate,
-        max_deviation=max_deviation,
-        rms_deviation=rms_deviation,
-        upper_violations=upper_viol if len(upper_viol) > 0 else None,
-        lower_violations=lower_viol if len(lower_viol) > 0 else None,
-        margin=margin,
-        margin_percentage=margin_pct,
-        statistics=statistics,
-    )
-
 
 def batch_compare_to_golden(
     traces: list[WaveformTrace],

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

@@ -5,7 +5,7 @@ bounds, pass/fail determination, and margin analysis.
 
 
 Example:
-    >>> from oscura.comparison import check_limits, margin_analysis
+    >>> from oscura.utils.comparison import check_limits, margin_analysis
     >>> result = check_limits(trace, upper=1.5, lower=-0.5)
     >>> margins = margin_analysis(trace, limits)
 """
@@ -188,74 +188,35 @@ def check_limits(
         >>> if not result.passed:
         ...     print(f"{result.num_violations} violations found")
     """
-    # Get data
-    if isinstance(trace, WaveformTrace):
-        data = trace.data.astype(np.float64)
-    else:
-        data = np.asarray(trace, dtype=np.float64)
+    # Extract data array
+    data = _extract_data_array(trace)
 
-    # Create or use limits
-    if limits is None:
-        if upper is None and lower is None:
-            raise ValueError("Must specify limits or upper/lower bounds")
-        limits = LimitSpec(upper=upper, lower=lower)
+    # Get or create limit specification
+    limits = _get_or_create_limits(limits, upper, lower)
 
-    # Handle relative limits
-    actual_upper = limits.upper
-    actual_lower = limits.lower
-    if limits.mode == "relative" and reference is not None:
-        if actual_upper is not None:
-            actual_upper = reference + actual_upper
-        if actual_lower is not None:
-            actual_lower = reference + actual_lower
+    # Apply relative mode adjustment if needed
+    actual_upper, actual_lower = _apply_relative_limits(limits, reference)
 
-    # Find violations
-    upper_viol = np.array([], dtype=np.int64)
-    lower_viol = np.array([], dtype=np.int64)
+    # Find violations in data
+    upper_viol, lower_viol = _find_violations(data, actual_upper, actual_lower)
 
-    if actual_upper is not None:
-        upper_viol = np.where(data > actual_upper)[0]
-    if actual_lower is not None:
-        lower_viol = np.where(data < actual_lower)[0]
+    # Compute violation statistics
+    num_violations, violation_rate = _compute_violation_stats(upper_viol, lower_viol, len(data))
 
-    # Combine violations
-    all_violations = np.union1d(upper_viol, lower_viol)
-    num_violations = len(all_violations)
-    violation_rate = num_violations / len(data) if len(data) > 0 else 0.0
-
-    # Compute statistics
+    # Compute data range statistics
     max_val = float(np.max(data))
     min_val = float(np.min(data))
 
-    # Compute margins
-    upper_margin = None
-    lower_margin = None
-    if actual_upper is not None:
-        upper_margin = float(actual_upper - max_val)
-    if actual_lower is not None:
-        lower_margin = float(min_val - actual_lower)
+    # Compute margins to limits
+    upper_margin, lower_margin = _compute_limit_margins(
+        actual_upper, actual_lower, max_val, min_val
+    )
 
     # Compute margin percentage
-    margin_pct = None
-    if actual_upper is not None and actual_lower is not None:
-        limit_range = actual_upper - actual_lower
-        if limit_range > 0:
-            min_margin = min(
-                upper_margin if upper_margin is not None else float("inf"),
-                lower_margin if lower_margin is not None else float("inf"),
-            )
-            margin_pct = (min_margin / limit_range) * 100.0
+    margin_pct = _compute_margin_pct(actual_upper, actual_lower, upper_margin, lower_margin)
 
-    # Check guardband
-    within_guardband = False
-    if num_violations == 0:
-        # Check if within guardband
-        if limits.upper_guardband > 0 and upper_margin is not None:
-            if upper_margin < limits.upper_guardband:
-                within_guardband = True
-        if limits.lower_guardband > 0 and lower_margin is not None:
-            if lower_margin < limits.lower_guardband:
-                within_guardband = True
+    # Check guardband status
+    within_guardband = _check_guardband_status(num_violations, limits, upper_margin, lower_margin)
 
     return LimitTestResult(
         passed=num_violations == 0,
@@ -321,16 +282,238 @@ def margin_analysis(
         >>> margins = margin_analysis(trace, limits)
         >>> print(f"Margin: {margins.margin_percentage:.1f}%")
     """
-    # Get data
+    # Extract data array
+    data = _extract_data_array(trace)
+    max_val = float(np.max(data))
+    min_val = float(np.min(data))
+
+    # Calculate margins to limits
+    upper_margin, lower_margin = _calculate_margins(limits, max_val, min_val)
+
+    # Determine critical limit and minimum margin
+    min_margin, critical_limit = _find_critical_limit(upper_margin, lower_margin)
+
+    # Calculate margin as percentage of limit range
+    margin_pct = _calculate_margin_percentage(limits, upper_margin, lower_margin, min_margin)
+
+    # Determine pass/warning/fail status
+    margin_status, warning = _determine_margin_status(min_margin, margin_pct, warning_threshold_pct)
+
+    return MarginAnalysis(
+        upper_margin=upper_margin,
+        lower_margin=lower_margin,
+        min_margin=min_margin,
+        margin_percentage=margin_pct,
+        critical_limit=critical_limit,
+        warning=warning,
+        margin_status=margin_status,
+    )
+
+
+def _get_or_create_limits(
+    limits: LimitSpec | None, upper: float | None, lower: float | None
+) -> LimitSpec:
+    """Get existing limits or create from upper/lower bounds.
+
+    Args:
+        limits: Existing LimitSpec or None.
+        upper: Upper limit value.
+        lower: Lower limit value.
+
+    Returns:
+        LimitSpec instance.
+
+    Raises:
+        ValueError: If no limits specified.
+    """
+    if limits is None:
+        if upper is None and lower is None:
+            raise ValueError("Must specify limits or upper/lower bounds")
+        limits = LimitSpec(upper=upper, lower=lower)
+    return limits
+
+
+def _apply_relative_limits(
+    limits: LimitSpec, reference: float | None
+) -> tuple[float | None, float | None]:
+    """Apply relative mode adjustment to limits.
+
+    Args:
+        limits: Limit specification.
+        reference: Reference value for relative limits.
+
+    Returns:
+        Tuple of (actual_upper, actual_lower).
+    """
+    actual_upper = limits.upper
+    actual_lower = limits.lower
+
+    if limits.mode == "relative" and reference is not None:
+        if actual_upper is not None:
+            actual_upper = reference + actual_upper
+        if actual_lower is not None:
+            actual_lower = reference + actual_lower
+
+    return (actual_upper, actual_lower)
+
+
+def _find_violations(
+    data: NDArray[np.float64], actual_upper: float | None, actual_lower: float | None
+) -> tuple[NDArray[np.int64], NDArray[np.int64]]:
+    """Find samples violating upper and lower limits.
+
+    Args:
+        data: Data array to check.
+        actual_upper: Upper limit (None if no upper limit).
+        actual_lower: Lower limit (None if no lower limit).
+
+    Returns:
+        Tuple of (upper_violations, lower_violations) index arrays.
+    """
+    upper_viol = np.array([], dtype=np.int64)
+    lower_viol = np.array([], dtype=np.int64)
+
+    if actual_upper is not None:
+        upper_viol = np.where(data > actual_upper)[0]
+    if actual_lower is not None:
+        lower_viol = np.where(data < actual_lower)[0]
+
+    return (upper_viol, lower_viol)
+
+
+def _compute_violation_stats(
+    upper_viol: NDArray[np.int64], lower_viol: NDArray[np.int64], data_length: int
+) -> tuple[int, float]:
+    """Compute violation count and rate.
+
+    Args:
+        upper_viol: Upper limit violations.
+        lower_viol: Lower limit violations.
+        data_length: Total number of samples.
+
+    Returns:
+        Tuple of (num_violations, violation_rate).
+    """
+    all_violations = np.union1d(upper_viol, lower_viol)
+    num_violations = len(all_violations)
+    violation_rate = num_violations / data_length if data_length > 0 else 0.0
+    return (num_violations, violation_rate)
+
+
+def _compute_limit_margins(
+    actual_upper: float | None, actual_lower: float | None, max_val: float, min_val: float
+) -> tuple[float | None, float | None]:
+    """Compute margins to upper and lower limits.
+
+    Args:
+        actual_upper: Upper limit.
+        actual_lower: Lower limit.
+        max_val: Maximum value in data.
+        min_val: Minimum value in data.
+
+    Returns:
+        Tuple of (upper_margin, lower_margin).
+    """
+    upper_margin = None
+    lower_margin = None
+
+    if actual_upper is not None:
+        upper_margin = float(actual_upper - max_val)
+    if actual_lower is not None:
+        lower_margin = float(min_val - actual_lower)
+
+    return (upper_margin, lower_margin)
+
+
+def _compute_margin_pct(
+    actual_upper: float | None,
+    actual_lower: float | None,
+    upper_margin: float | None,
+    lower_margin: float | None,
+) -> float | None:
+    """Compute margin as percentage of limit range.
+
+    Args:
+        actual_upper: Upper limit.
+        actual_lower: Lower limit.
+        upper_margin: Margin to upper limit.
+        lower_margin: Margin to lower limit.
+
+    Returns:
+        Margin percentage or None if cannot compute.
+    """
+    if actual_upper is not None and actual_lower is not None:
+        limit_range = actual_upper - actual_lower
+        if limit_range > 0:
+            min_margin = min(
+                upper_margin if upper_margin is not None else float("inf"),
+                lower_margin if lower_margin is not None else float("inf"),
+            )
+            return (min_margin / limit_range) * 100.0
+    return None
+
+
+def _check_guardband_status(
+    num_violations: int,
+    limits: LimitSpec,
+    upper_margin: float | None,
+    lower_margin: float | None,
+) -> bool:
+    """Check if data is within guardband region.
+
+    Args:
+        num_violations: Number of limit violations.
+        limits: Limit specification with guardbands.
+        upper_margin: Margin to upper limit.
+        lower_margin: Margin to lower limit.
+
+    Returns:
+        True if within guardband but outside tight limits.
+    """
+    if num_violations > 0:
+        return False
+
+    within_guardband = False
+
+    if limits.upper_guardband > 0 and upper_margin is not None:
+        if upper_margin < limits.upper_guardband:
+            within_guardband = True
+
+    if limits.lower_guardband > 0 and lower_margin is not None:
+        if lower_margin < limits.lower_guardband:
+            within_guardband = True
+
+    return within_guardband
+
+
+def _extract_data_array(trace: WaveformTrace | NDArray[np.floating[Any]]) -> NDArray[np.float64]:
+    """Extract numpy array from trace or array input.
+
+    Args:
+        trace: WaveformTrace object or numpy array.
+
+    Returns:
+        Data as float64 numpy array.
+    """
     if isinstance(trace, WaveformTrace):
-        data = trace.data.astype(np.float64)
+        return trace.data.astype(np.float64)
     else:
-        data = np.asarray(trace, dtype=np.float64)
+        return np.asarray(trace, dtype=np.float64)
 
-    max_val = float(np.max(data))
-    min_val = float(np.min(data))
 
-    # Compute margins
+def _calculate_margins(
+    limits: LimitSpec, max_val: float, min_val: float
+) -> tuple[float | None, float | None]:
+    """Calculate margin to upper and lower limits.
+
+    Args:
+        limits: Specification limits.
+        max_val: Maximum value in data.
+        min_val: Minimum value in data.
+
+    Returns:
+        Tuple of (upper_margin, lower_margin). None if limit not defined.
+    """
     upper_margin = None
     lower_margin = None
 
@@ -339,8 +522,25 @@ def margin_analysis(
     if limits.lower is not None:
         lower_margin = min_val - limits.lower
 
-    # Determine minimum margin and critical limit
-    margins = []
+    return (upper_margin, lower_margin)
+
+
+def _find_critical_limit(
+    upper_margin: float | None, lower_margin: float | None
+) -> tuple[float, Literal["upper", "lower", "both", "none"]]:
+    """Find minimum margin and identify critical limit.
+
+    Args:
+        upper_margin: Margin to upper limit (None if no upper limit).
+        lower_margin: Margin to lower limit (None if no lower limit).
+
+    Returns:
+        Tuple of (minimum_margin, critical_limit_name).
+
+    Raises:
+        AnalysisError: If no limits defined.
+    """
+    margins: list[tuple[str, float]] = []
     if upper_margin is not None:
         margins.append(("upper", upper_margin))
     if lower_margin is not None:
@@ -353,39 +553,63 @@ def margin_analysis(
     min_margin_tuple = min(margins, key=lambda x: x[1])
     min_margin = min_margin_tuple[1]
 
-    # Determine critical limit
+    # Determine critical limit (both if equal margins)
     if len(margins) == 2 and abs(margins[0][1] - margins[1][1]) < 1e-10:
         critical_limit: Literal["upper", "lower", "both", "none"] = "both"
     else:
         critical_limit = min_margin_tuple[0]  # type: ignore[assignment]
 
-    # Compute margin percentage
-    margin_pct = 0.0
+    return (min_margin, critical_limit)
+
+
+def _calculate_margin_percentage(
+    limits: LimitSpec,
+    upper_margin: float | None,
+    lower_margin: float | None,
+    min_margin: float,
+) -> float:
+    """Calculate margin as percentage of limit range.
+
+    Args:
+        limits: Specification limits.
+        upper_margin: Margin to upper limit.
+        lower_margin: Margin to lower limit.
+        min_margin: Minimum of upper/lower margins.
+
+    Returns:
+        Margin percentage (0-100+).
+    """
+    # Prefer range-based percentage if both limits defined
     if limits.upper is not None and limits.lower is not None:
         limit_range = limits.upper - limits.lower
         if limit_range > 0:
-            margin_pct = (min_margin / limit_range) * 100.0
-    elif limits.upper is not None and upper_margin is not None:
-        margin_pct = (upper_margin / abs(limits.upper)) * 100.0 if limits.upper != 0 else 0
+            return (min_margin / limit_range) * 100.0
+
+    # Single limit: use absolute value
+    if limits.upper is not None and upper_margin is not None:
+        return (upper_margin / abs(limits.upper)) * 100.0 if limits.upper != 0 else 0.0
     elif limits.lower is not None and lower_margin is not None:
-        margin_pct = (lower_margin / abs(limits.lower)) * 100.0 if limits.lower != 0 else 0
+        return (lower_margin / abs(limits.lower)) * 100.0 if limits.lower != 0 else 0.0
+
+    return 0.0
+
+
+def _determine_margin_status(
+    min_margin: float, margin_pct: float, warning_threshold_pct: float
+) -> tuple[Literal["pass", "warning", "fail"], bool]:
+    """Determine margin status (pass/warning/fail).
+
+    Args:
+        min_margin: Minimum margin value.
+        margin_pct: Margin as percentage.
+        warning_threshold_pct: Warning threshold percentage.
 
-    # Determine status
-    warning = False
+    Returns:
+        Tuple of (status, warning_flag).
+    """
     if min_margin < 0:
-        margin_status: Literal["pass", "warning", "fail"] = "fail"
+        return ("fail", False)
     elif margin_pct < warning_threshold_pct:
-        margin_status = "warning"
-        warning = True
+        return ("warning", True)
     else:
-        margin_status = "pass"
-
-    return MarginAnalysis(
-        upper_margin=upper_margin,
-        lower_margin=lower_margin,
-        min_margin=min_margin,
-        margin_percentage=margin_pct,
-        critical_limit=critical_limit,
-        warning=warning,
-        margin_status=margin_status,
-    )
+        return ("pass", False)