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

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

@@ -79,13 +79,13 @@ def correct_timestamp_jitter(
 ) -> TimestampCorrection:
     """Correct timestamp jitter using filtering or PLL model.
 
-    : Compensates for clock jitter in logic analyzer
+    Compensates for clock jitter in logic analyzer
     captures (e.g., USB transmission jitter) while preserving phase.
 
     Correction constraints (DAQ-003):
-    - Max correction per sample: ±max_correction_factor × expected_period  # noqa: RUF002, RUF003
-    - Filter cutoff: expected_rate / 10 (removes 10× jitter frequency)  # noqa: RUF002, RUF003
-    - Target reduction: ≥5× for typical USB jitter  # noqa: RUF002, RUF003
+    - Max correction per sample: ±max_correction_factor x expected_period
+    - Filter cutoff: expected_rate / 10 (removes 10x jitter frequency)
+    - Target reduction: >=5x for typical USB jitter
 
     Args:
         timestamps: Original jittery timestamps in seconds
@@ -113,109 +113,149 @@ def correct_timestamp_jitter(
     References:
         DAQ-003: Timestamp Jitter Compensation and Clock Correction
     """
-    if len(timestamps) == 0:
-        raise ValueError("Timestamps array cannot be empty")
-
-    if expected_rate <= 0:
-        raise ValueError("expected_rate must be positive")
-
-    if max_correction_factor <= 0:
-        raise ValueError("max_correction_factor must be positive")
+    # Validate inputs
+    _validate_jitter_correction_inputs(timestamps, expected_rate, max_correction_factor)
 
+    # Handle edge cases
     if len(timestamps) < 3:
-        # Not enough data to filter
-        return TimestampCorrection(
-            corrected_timestamps=timestamps.copy(),
-            original_jitter_rms=0.0,
-            corrected_jitter_rms=0.0,
-            reduction_ratio=1.0,
-            samples_corrected=0,
-            max_correction=0.0,
-        )
+        return _create_no_correction_result(timestamps)
 
     expected_period = 1.0 / expected_rate
     max_correction = max_correction_factor * expected_period
 
     # Calculate original jitter
-    diffs = np.diff(timestamps)
-    original_jitter = diffs - expected_period
-    original_jitter_rms = float(np.sqrt(np.mean(original_jitter**2)))
+    original_jitter_rms = _calculate_original_jitter_rms(timestamps, expected_period)
 
-    # If jitter is negligible (below 1 ns), no correction needed
-    # This avoids correcting floating-point rounding errors in perfect timestamps
+    # Skip correction if jitter is negligible
     if original_jitter_rms < 1e-9:
-        return TimestampCorrection(
-            corrected_timestamps=timestamps.copy(),
-            original_jitter_rms=original_jitter_rms,
-            corrected_jitter_rms=original_jitter_rms,
-            reduction_ratio=1.0,
-            samples_corrected=0,
-            max_correction=0.0,
-        )
+        return _create_negligible_jitter_result(timestamps, original_jitter_rms)
 
-    if method == "lowpass":
-        # Low-pass filter approach
-        # Design Butterworth filter: cutoff at expected_rate / 10
-        cutoff_freq = expected_rate / 10.0
-        nyquist = 0.5 * expected_rate
+    # Apply correction method
+    corrected = _apply_jitter_correction(
+        timestamps, expected_rate, expected_period, max_correction, method
+    )
 
-        # Ensure cutoff is valid
-        if cutoff_freq >= nyquist:
-            cutoff_freq = nyquist * 0.8
+    # Build and return result
+    return _build_jitter_correction_result(
+        timestamps, corrected, expected_period, original_jitter_rms, max_correction
+    )
 
-        # Design 2nd order Butterworth
-        sos = signal.butter(2, cutoff_freq / nyquist, btype="low", output="sos")
 
-        # Filter the timestamps
-        # Need to detrend first to avoid edge effects
-        t_mean = np.mean(timestamps)
-        t_detrended = timestamps - t_mean
+def _validate_jitter_correction_inputs(
+    timestamps: NDArray[np.float64], expected_rate: float, max_correction_factor: float
+) -> None:
+    """Validate jitter correction input parameters."""
+    if len(timestamps) == 0:
+        raise ValueError("Timestamps array cannot be empty")
+    if expected_rate <= 0:
+        raise ValueError("expected_rate must be positive")
+    if max_correction_factor <= 0:
+        raise ValueError("max_correction_factor must be positive")
 
-        # Apply filter
-        filtered = signal.sosfiltfilt(sos, t_detrended)
-        corrected = filtered + t_mean
 
-    else:  # pll
-        # Phase-locked loop model
-        # Simple PLL: track expected phase and correct deviations
-        corrected = np.zeros_like(timestamps)
-        corrected[0] = timestamps[0]
+def _create_no_correction_result(timestamps: NDArray[np.float64]) -> TimestampCorrection:
+    """Create result for insufficient data case."""
+    return TimestampCorrection(
+        corrected_timestamps=timestamps.copy(),
+        original_jitter_rms=0.0,
+        corrected_jitter_rms=0.0,
+        reduction_ratio=1.0,
+        samples_corrected=0,
+        max_correction=0.0,
+    )
 
-        # PLL state
-        phase = 0.0
-        phase_increment = 2 * np.pi * expected_rate
 
-        for i in range(1, len(timestamps)):
-            # Predict next timestamp based on expected rate
-            predicted = corrected[i - 1] + expected_period
+def _calculate_original_jitter_rms(
+    timestamps: NDArray[np.float64], expected_period: float
+) -> float:
+    """Calculate RMS jitter from timestamps."""
+    diffs = np.diff(timestamps)
+    original_jitter = diffs - expected_period
+    return float(np.sqrt(np.mean(original_jitter**2)))
 
-            # Measure phase error
-            actual = timestamps[i]
-            error = actual - predicted
 
-            # Apply correction with limiting
-            correction = np.clip(error * 0.5, -max_correction, max_correction)
-            corrected[i] = predicted + correction
+def _create_negligible_jitter_result(
+    timestamps: NDArray[np.float64], original_jitter_rms: float
+) -> TimestampCorrection:
+    """Create result for negligible jitter case."""
+    return TimestampCorrection(
+        corrected_timestamps=timestamps.copy(),
+        original_jitter_rms=original_jitter_rms,
+        corrected_jitter_rms=original_jitter_rms,
+        reduction_ratio=1.0,
+        samples_corrected=0,
+        max_correction=0.0,
+    )
 
-            # Update phase
-            phase += phase_increment * (corrected[i] - corrected[i - 1])
+
+def _apply_jitter_correction(
+    timestamps: NDArray[np.float64],
+    expected_rate: float,
+    expected_period: float,
+    max_correction: float,
+    method: Literal["lowpass", "pll"],
+) -> NDArray[np.float64]:
+    """Apply jitter correction using selected method."""
+    if method == "lowpass":
+        corrected = _apply_lowpass_correction(timestamps, expected_rate)
+    else:  # pll
+        corrected = _apply_pll_correction(timestamps, expected_period, max_correction)
 
     # Limit corrections to max_correction
     corrections = corrected - timestamps
     exceeded = np.abs(corrections) > max_correction
     corrections[exceeded] = np.sign(corrections[exceeded]) * max_correction
-    corrected = timestamps + corrections
+    return timestamps + corrections
+
+
+def _apply_lowpass_correction(
+    timestamps: NDArray[np.float64], expected_rate: float
+) -> NDArray[np.float64]:
+    """Apply low-pass filter correction."""
+    cutoff_freq = expected_rate / 10.0
+    nyquist = 0.5 * expected_rate
+    if cutoff_freq >= nyquist:
+        cutoff_freq = nyquist * 0.8
+
+    sos = signal.butter(2, cutoff_freq / nyquist, btype="low", output="sos")
+    t_mean: np.floating[Any] = np.mean(timestamps)
+    t_detrended = timestamps - t_mean
+    filtered = signal.sosfiltfilt(sos, t_detrended)
+    result: NDArray[np.float64] = np.asarray(filtered + t_mean, dtype=np.float64)
+    return result
+
+
+def _apply_pll_correction(
+    timestamps: NDArray[np.float64], expected_period: float, max_correction: float
+) -> NDArray[np.float64]:
+    """Apply phase-locked loop correction."""
+    corrected = np.zeros_like(timestamps)
+    corrected[0] = timestamps[0]
+
+    for i in range(1, len(timestamps)):
+        predicted = corrected[i - 1] + expected_period
+        error = timestamps[i] - predicted
+        correction = np.clip(error * 0.5, -max_correction, max_correction)
+        corrected[i] = predicted + correction
+
+    return corrected
 
-    # Calculate corrected jitter
+
+def _build_jitter_correction_result(
+    timestamps: NDArray[np.float64],
+    corrected: NDArray[np.float64],
+    expected_period: float,
+    original_jitter_rms: float,
+    max_correction: float,
+) -> TimestampCorrection:
+    """Build final jitter correction result."""
     corrected_diffs = np.diff(corrected)
     corrected_jitter = corrected_diffs - expected_period
     corrected_jitter_rms = float(np.sqrt(np.mean(corrected_jitter**2)))
 
-    # Calculate metrics
+    corrections = corrected - timestamps
     samples_corrected = int(np.sum(np.abs(corrections) > 1e-12))
     max_correction_applied = float(np.max(np.abs(corrections)))
-
-    # original_jitter_rms is always > 0 here (early return handles negligible jitter)
     reduction_ratio = original_jitter_rms / max(corrected_jitter_rms, 1e-15)
 
     return TimestampCorrection(
@@ -228,6 +268,52 @@ def correct_timestamp_jitter(
     )
 
 
+def _decode_uart_tolerant(
+    data: NDArray[np.uint8],
+    tolerance: ErrorTolerance,
+    baud: float,
+) -> list[DecodedFrame]:
+    """Decode UART frames with error tolerance (simplified implementation)."""
+    frames: list[DecodedFrame] = []
+    pos = 0
+
+    while pos < len(data):
+        try:
+            if pos + 1 >= len(data):
+                break
+
+            frame_data = bytes([data[pos]])
+            timestamp = float(pos) / baud
+
+            # Validate frame (simplified - real decoder checks start/stop bits)
+            is_valid = data[pos] != 0xFF  # Example error condition
+            error_type = "framing" if not is_valid else None
+
+            frames.append(
+                DecodedFrame(
+                    data=frame_data,
+                    timestamp=timestamp,
+                    valid=is_valid,
+                    error_type=error_type,
+                    position=pos,
+                )
+            )
+
+            if not is_valid and tolerance == ErrorTolerance.STRICT:
+                break
+            elif not is_valid and tolerance == ErrorTolerance.TOLERANT:
+                pos += 1  # Skip error frame, resync
+            else:
+                pos += 1  # Permissive: record error, continue
+
+        except Exception:
+            if tolerance == ErrorTolerance.STRICT:
+                raise
+            pos += 1
+
+    return frames
+
+
 def decode_with_error_tolerance(
     data: NDArray[np.uint8],
     protocol: Literal["uart", "spi", "i2c", "can"],
@@ -279,82 +365,18 @@ def decode_with_error_tolerance(
     if protocol not in ("uart", "spi", "i2c", "can"):
         raise ValueError(f"Unsupported protocol: {protocol}")
 
-    frames: list[DecodedFrame] = []
-    pos = 0
-
     # Protocol-specific decode logic
     # This is a simplified implementation showing the error handling pattern
     # Full protocol decoders are in oscura.analyzers.protocols
 
     if protocol == "uart":
-        # UART parameters
         if "baud" not in protocol_params:
             raise ValueError("UART requires 'baud' parameter")
+        return _decode_uart_tolerant(data, tolerance, protocol_params["baud"])
 
-        # Simplified UART frame extraction with error tolerance
-        while pos < len(data):
-            try:
-                # Try to decode frame at current position
-                # This is simplified - real UART decoder would analyze bit timing
-
-                # Check for valid frame (simplified)
-                if pos + 1 >= len(data):
-                    break
-
-                frame_data = bytes([data[pos]])
-                timestamp = float(pos) / protocol_params["baud"]
-
-                # Validate frame (simplified - would check start/stop bits)
-                is_valid = True
-                error_type = None
-
-                # Example: detect framing error (no proper stop bit)
-                if data[pos] == 0xFF:  # Example error condition
-                    is_valid = False
-                    error_type = "framing"
-
-                frames.append(
-                    DecodedFrame(
-                        data=frame_data,
-                        timestamp=timestamp,
-                        valid=is_valid,
-                        error_type=error_type,
-                        position=pos,
-                    )
-                )
-
-                if not is_valid and tolerance == ErrorTolerance.STRICT:
-                    # Strict mode: abort on error
-                    break
-                elif not is_valid and tolerance == ErrorTolerance.TOLERANT:
-                    # Tolerant: skip error frame, resync
-                    # Search for next valid start bit
-                    pos += 1
-                    # In real implementation, would search for start bit pattern
-                else:
-                    # Permissive: record error, continue
-                    pos += 1
-
-            except Exception:
-                if tolerance == ErrorTolerance.STRICT:
-                    raise
-                else:
-                    # Log error and continue
-                    pos += 1
-
-    elif protocol == "spi":
-        # SPI: Re-align on CS edge
-        # Simplified placeholder
-        pass
-
-    elif protocol == "i2c":
-        # I2C: Search for START condition
-        # Simplified placeholder
-        pass
-
-    elif protocol == "can":
-        # CAN: Wait for SOF after error
-        # Simplified placeholder
-        pass
+    elif protocol in ("spi", "i2c", "can"):
+        # SPI/I2C/CAN: Simplified placeholders
+        # Real implementations would have protocol-specific resync logic
+        return []
 
-    return frames
+    return []

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

@@ -113,102 +113,23 @@ def analyze_bit_errors(
     References:
         DAQ-005: Bit Error Pattern Analysis and Capture Diagnostics
     """
-    if len(received) != len(expected):
-        raise ValueError("Received and expected arrays must have same length")
-
-    if len(received) == 0:
-        raise ValueError("Arrays cannot be empty")
+    _validate_inputs(received, expected)
 
-    # Find bit errors (XOR)
     errors = received != expected
     error_positions = np.where(errors)[0]
     error_count = len(error_positions)
     total_bits = len(received)
-
-    # Calculate BER
     bit_error_rate = error_count / total_bits if total_bits > 0 else 0.0
 
     if error_count == 0:
-        # No errors
-        return ErrorAnalysis(
-            bit_error_rate=0.0,
-            error_count=0,
-            total_bits=total_bits,
-            pattern_type=ErrorPattern.RANDOM,
-            mean_error_gap=float(total_bits),
-            error_positions=error_positions,
-            diagnosis="No errors detected - good capture quality",
-            severity="low",
-        )
-
-    # Calculate error gaps
-    if error_count > 1:
-        error_gaps = np.diff(error_positions)
-        mean_gap = float(np.mean(error_gaps))
-    else:
-        mean_gap = float(total_bits)
-
-    # Classify error pattern
-    pattern_type = ErrorPattern.UNKNOWN
-    diagnosis = ""
+        return _create_no_errors_analysis(total_bits, error_positions)
 
-    # Check for burst pattern (errors clustered)
-    if error_count > 1 and mean_gap < burst_threshold:
-        pattern_type = ErrorPattern.BURST
-        diagnosis = "Burst errors detected - likely USB transmission issue"
-
-    # Check for periodic pattern (FFT analysis)
-    # Need at least 10 errors for reliable periodicity detection
-    elif error_count >= 10:
-        # Create binary error signal
-        error_signal = errors.astype(float)
-
-        # Compute FFT to detect periodicity
-        fft = np.fft.rfft(error_signal)
-        fft_mag = np.abs(fft[1:])  # Skip DC component
-
-        if len(fft_mag) > 0:
-            # Check if there's a strong peak relative to mean (not just max)
-            mean_mag = np.mean(fft_mag)
-            max_mag = np.max(fft_mag)
-            peak_ratio = max_mag / (mean_mag + 1e-12)
-
-            # Require strong peak (>10x mean) and exceeds threshold
-            if peak_ratio > 10 and (max_mag / (np.max(fft_mag) + 1e-12)) > periodicity_threshold:
-                pattern_type = ErrorPattern.PERIODIC
-                diagnosis = "Periodic errors detected - likely clock jitter or interference"
-
-    # If not burst or periodic, classify as random
-    if pattern_type == ErrorPattern.UNKNOWN:
-        # Check if errors are uniformly distributed
-        if error_count > 2:
-            # Use coefficient of variation of gaps
-            if error_count > 1:
-                gap_std = float(np.std(error_gaps))
-                gap_cv = gap_std / (mean_gap + 1e-12)
-
-                if gap_cv < 1.0:  # Relatively uniform spacing
-                    pattern_type = ErrorPattern.RANDOM
-                    diagnosis = "Random errors detected - likely EMI or noise"
-                else:
-                    diagnosis = "Mixed error pattern - multiple causes possible"
-            else:
-                pattern_type = ErrorPattern.RANDOM
-                diagnosis = "Single error - insufficient data for classification"
-        else:
-            pattern_type = ErrorPattern.RANDOM
-            diagnosis = "Few errors - likely random EMI or noise"
-
-    # Determine severity based on BER
-    if bit_error_rate > 0.01:
-        severity = "severe"
-        diagnosis += ". SEVERE: Check connections and hardware"
-    elif bit_error_rate > 0.001:
-        severity = "moderate"
-        diagnosis += ". MODERATE: Consider reducing sample rate"
-    else:
-        severity = "low"
-        diagnosis += ". Acceptable error rate"
+    mean_gap = _calculate_mean_gap(error_count, error_positions, total_bits)
+    pattern_type, diagnosis = _classify_error_pattern(
+        errors, error_count, error_positions, mean_gap, burst_threshold, periodicity_threshold
+    )
+    severity = _determine_severity(bit_error_rate)
+    diagnosis = _append_severity_message(diagnosis, severity)
 
     return ErrorAnalysis(
         bit_error_rate=bit_error_rate,
@@ -222,6 +143,117 @@ def analyze_bit_errors(
     )
 
 
+def _validate_inputs(received: NDArray[np.uint8], expected: NDArray[np.uint8]) -> None:
+    """Validate input arrays for error analysis."""
+    if len(received) != len(expected):
+        raise ValueError("Received and expected arrays must have same length")
+    if len(received) == 0:
+        raise ValueError("Arrays cannot be empty")
+
+
+def _create_no_errors_analysis(
+    total_bits: int, error_positions: NDArray[np.int64]
+) -> ErrorAnalysis:
+    """Create ErrorAnalysis for zero errors case."""
+    return ErrorAnalysis(
+        bit_error_rate=0.0,
+        error_count=0,
+        total_bits=total_bits,
+        pattern_type=ErrorPattern.RANDOM,
+        mean_error_gap=float(total_bits),
+        error_positions=error_positions,
+        diagnosis="No errors detected - good capture quality",
+        severity="low",
+    )
+
+
+def _calculate_mean_gap(
+    error_count: int, error_positions: NDArray[np.int64], total_bits: int
+) -> float:
+    """Calculate mean gap between errors."""
+    if error_count > 1:
+        error_gaps = np.diff(error_positions)
+        return float(np.mean(error_gaps))
+    return float(total_bits)
+
+
+def _classify_error_pattern(
+    errors: NDArray[np.bool_],
+    error_count: int,
+    error_positions: NDArray[np.int64],
+    mean_gap: float,
+    burst_threshold: int,
+    periodicity_threshold: float,
+) -> tuple[ErrorPattern, str]:
+    """Classify error pattern type and generate diagnosis."""
+    if error_count > 1 and mean_gap < burst_threshold:
+        return ErrorPattern.BURST, "Burst errors detected - likely USB transmission issue"
+
+    if error_count >= 10:
+        pattern, diagnosis = _check_periodic_pattern(errors, periodicity_threshold)
+        if pattern == ErrorPattern.PERIODIC:
+            return pattern, diagnosis
+
+    return _classify_random_pattern(error_count, error_positions, mean_gap)
+
+
+def _check_periodic_pattern(
+    errors: NDArray[np.bool_], periodicity_threshold: float
+) -> tuple[ErrorPattern, str]:
+    """Check if errors show periodic pattern via FFT."""
+    error_signal = errors.astype(float)
+    fft = np.fft.rfft(error_signal)
+    fft_mag = np.abs(fft[1:])
+
+    if len(fft_mag) > 0:
+        mean_mag = np.mean(fft_mag)
+        max_mag = np.max(fft_mag)
+        peak_ratio = max_mag / (mean_mag + 1e-12)
+
+        if peak_ratio > 10 and (max_mag / (np.max(fft_mag) + 1e-12)) > periodicity_threshold:
+            return (
+                ErrorPattern.PERIODIC,
+                "Periodic errors detected - likely clock jitter or interference",
+            )
+
+    return ErrorPattern.UNKNOWN, ""
+
+
+def _classify_random_pattern(
+    error_count: int, error_positions: NDArray[np.int64], mean_gap: float
+) -> tuple[ErrorPattern, str]:
+    """Classify as random pattern with appropriate diagnosis."""
+    if error_count <= 2:
+        return ErrorPattern.RANDOM, "Few errors - likely random EMI or noise"
+
+    error_gaps = np.diff(error_positions)
+    gap_std = float(np.std(error_gaps))
+    gap_cv = gap_std / (mean_gap + 1e-12)
+
+    if gap_cv < 1.0:
+        return ErrorPattern.RANDOM, "Random errors detected - likely EMI or noise"
+
+    return ErrorPattern.UNKNOWN, "Mixed error pattern - multiple causes possible"
+
+
+def _determine_severity(bit_error_rate: float) -> str:
+    """Determine severity level based on BER."""
+    if bit_error_rate > 0.01:
+        return "severe"
+    if bit_error_rate > 0.001:
+        return "moderate"
+    return "low"
+
+
+def _append_severity_message(diagnosis: str, severity: str) -> str:
+    """Append severity-specific message to diagnosis."""
+    if severity == "severe":
+        return diagnosis + ". SEVERE: Check connections and hardware"
+    if severity == "moderate":
+        return diagnosis + ". MODERATE: Consider reducing sample rate"
+    return diagnosis + ". Acceptable error rate"
+
+
 def generate_error_visualization_data(
     analysis: ErrorAnalysis,
     *,