oscura 0.8.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

oscura/utils/search/anomaly.py

@@ -1,424 +0,0 @@
-"""Anomaly detection in signal traces.
-
-This module provides automated detection of glitches, timing violations,
-and protocol errors with context extraction for debugging.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-import numpy as np
-from numpy.typing import NDArray
-
-
-def find_anomalies(
-    trace: NDArray[np.float64],
-    anomaly_type: str = "glitch",
-    *,
-    threshold: float | None = None,
-    min_width: float | None = None,
-    max_width: float | None = None,
-    sample_rate: float | None = None,
-    context_samples: int = 100,
-    **kwargs: Any,
-) -> list[dict[str, Any]]:
-    """Find glitches, timing violations, or protocol errors in traces.
-
-    Anomaly detection with context extraction.
-    Integrates with QUAL-005 glitch detection for signal quality analysis.
-
-    Args:
-        trace: Input signal trace
-        anomaly_type: Type of anomaly to detect:
-            - 'glitch': Short-duration voltage spikes/dips
-            - 'timing': Edge timing violations (requires sample_rate)
-            - 'protocol': Protocol-level errors (requires decoded data)
-        threshold: Detection threshold. Meaning depends on anomaly_type:
-            - glitch: Voltage deviation from expected level
-            - timing: Timing violation threshold in seconds
-        min_width: Minimum anomaly width in seconds (requires sample_rate)
-        max_width: Maximum anomaly width in seconds (requires sample_rate)
-        sample_rate: Sample rate in Hz (required for timing analysis)
-        context_samples: Number of samples to include before/after anomaly
-            for context extraction (default: 100)
-        **kwargs: Additional type-specific parameters
-
-    Returns:
-        List of anomaly dictionaries, each containing:
-        - index: Sample index where anomaly occurs
-        - type: Anomaly type
-        - severity: Severity score (0-1, higher is worse)
-        - duration: Duration in samples
-        - amplitude: Amplitude deviation (for glitches)
-        - context: ±context_samples around anomaly
-        - description: Human-readable description
-
-    Raises:
-        ValueError: If invalid anomaly_type or missing required parameters
-
-    Examples:
-        >>> # Detect voltage glitches
-        >>> trace = np.array([0, 0, 0, 0.8, 0, 0, 0])  # Spike at index 3
-        >>> anomalies = find_anomalies(
-        ...     trace,
-        ...     anomaly_type='glitch',
-        ...     threshold=0.5,
-        ...     sample_rate=1e6
-        ... )
-        >>> print(f"Found {len(anomalies)} glitches")
-
-        >>> # Detect timing violations
-        >>> anomalies = find_anomalies(
-        ...     trace,
-        ...     anomaly_type='timing',
-        ...     min_width=10e-9,  # 10 ns minimum
-        ...     max_width=100e-9,  # 100 ns maximum
-        ...     sample_rate=1e9
-        ... )
-
-    Notes:
-        - Glitch detection uses derivative and threshold methods
-        - Timing detection requires sample_rate for width calculations
-        - Context extraction handles edge cases at trace boundaries
-        - Integrates with QUAL-005 for comprehensive signal quality analysis
-
-    References:
-        SRCH-002: Anomaly Search
-        QUAL-005: Glitch Detection
-    """
-    if trace.size == 0:
-        return []
-
-    valid_types = {"glitch", "timing", "protocol"}
-    if anomaly_type not in valid_types:
-        raise ValueError(f"Invalid anomaly_type '{anomaly_type}'. Must be one of: {valid_types}")
-
-    return _dispatch_anomaly_detection(
-        trace, anomaly_type, threshold, min_width, max_width, sample_rate, context_samples
-    )
-
-
-def _dispatch_anomaly_detection(
-    trace: NDArray[np.float64],
-    anomaly_type: str,
-    threshold: float | None,
-    min_width: float | None,
-    max_width: float | None,
-    sample_rate: float | None,
-    context_samples: int,
-) -> list[dict[str, Any]]:
-    """Dispatch to appropriate anomaly detection method."""
-    if anomaly_type == "glitch":
-        return _detect_glitches(
-            trace, threshold, min_width, max_width, sample_rate, context_samples
-        )
-
-    if anomaly_type == "timing":
-        if sample_rate is None:
-            raise ValueError("sample_rate required for timing anomaly detection")
-        return _detect_timing_violations(trace, sample_rate, min_width, max_width, context_samples)
-
-    # Protocol error detection would integrate with protocol decoders
-    return []
-
-
-def _detect_glitches(
-    trace: NDArray[np.float64],
-    threshold: float | None,
-    min_width: float | None,
-    max_width: float | None,
-    sample_rate: float | None,
-    context_samples: int,
-) -> list[dict[str, Any]]:
-    """Detect voltage glitches using derivative method.
-
-    Uses median absolute deviation (MAD) for robust auto-thresholding,
-    groups consecutive derivative spikes, and filters by duration.
-
-    Example:
-        >>> trace = np.array([1.0, 1.0, 5.0, 1.0, 1.0])  # Glitch at index 2
-        >>> glitches = _detect_glitches(trace, None, None, None, 1000.0, 5)
-        >>> len(glitches) > 0
-        True
-    """
-    if len(trace) < 2:
-        return []
-
-    # Compute derivative to find rapid changes
-    abs_derivative = np.abs(np.diff(trace))
-
-    # Determine threshold
-    threshold_value = _compute_glitch_threshold(threshold, abs_derivative)
-
-    # Find glitch candidate points
-    glitch_candidates = np.where(abs_derivative > threshold_value)[0]
-    if len(glitch_candidates) == 0:
-        return []
-
-    # Group consecutive points into glitch events
-    glitch_groups = _group_consecutive_indices(glitch_candidates)
-
-    # Compute baseline once for performance
-    baseline = _compute_baseline(trace)
-
-    # Convert groups to glitch dictionaries
-    return _build_glitch_results(
-        glitch_groups,
-        trace,
-        baseline,
-        threshold_value,
-        min_width,
-        max_width,
-        sample_rate,
-        context_samples,
-    )
-
-
-def _compute_glitch_threshold(
-    threshold: float | None, abs_derivative: NDArray[np.float64]
-) -> float:
-    """Compute threshold for glitch detection using MAD.
-
-    Args:
-        threshold: User-provided threshold, or None for auto-threshold.
-        abs_derivative: Absolute derivative of signal.
-
-    Returns:
-        Threshold value for glitch detection.
-    """
-    if threshold is not None:
-        return threshold
-
-    # Use median absolute deviation (MAD) for robust auto-thresholding
-    median_deriv = np.median(abs_derivative)
-    mad = np.median(np.abs(abs_derivative - median_deriv))
-
-    # Convert MAD to equivalent std (1.4826 is the constant for normal distribution)
-    if mad > 0:
-        return float(median_deriv + 3 * 1.4826 * mad)
-
-    # Fallback: use 75th percentile to avoid catching glitches in threshold
-    p75 = np.percentile(abs_derivative, 75)
-    if p75 > 0:
-        return float(p75)
-
-    # Last resort: use any non-zero derivative
-    return 0.0
-
-
-def _group_consecutive_indices(indices: NDArray[np.int64]) -> list[list[int]]:
-    """Group consecutive indices into separate lists.
-
-    Args:
-        indices: Sorted array of indices.
-
-    Returns:
-        List of groups, where each group contains consecutive indices.
-
-    Example:
-        >>> indices = np.array([1, 2, 3, 7, 8, 10])
-        >>> _group_consecutive_indices(indices)
-        [[1, 2, 3], [7, 8], [10]]
-    """
-    if len(indices) == 0:
-        return []
-
-    groups = []
-    current_group = [int(indices[0])]
-
-    for idx in indices[1:]:
-        if idx == current_group[-1] + 1:
-            current_group.append(int(idx))
-        else:
-            groups.append(current_group)
-            current_group = [int(idx)]
-
-    if current_group:
-        groups.append(current_group)
-
-    return groups
-
-
-def _compute_baseline(trace: NDArray[np.float64]) -> float:
-    """Compute baseline value using median.
-
-    For very large arrays (>1M samples), uses percentile approximation
-    for performance.
-
-    Args:
-        trace: Signal trace.
-
-    Returns:
-        Baseline value (median).
-    """
-    if len(trace) > 1_000_000:
-        # Fast approximation: 50th percentile with linear interpolation
-        return float(np.percentile(trace, 50, method="linear"))
-    return float(np.median(trace))
-
-
-def _build_glitch_results(
-    glitch_groups: list[list[int]],
-    trace: NDArray[np.float64],
-    baseline: float,
-    threshold_value: float,
-    min_width: float | None,
-    max_width: float | None,
-    sample_rate: float | None,
-    context_samples: int,
-) -> list[dict[str, Any]]:
-    """Build glitch result dictionaries from detected groups.
-
-    Args:
-        glitch_groups: Groups of consecutive glitch indices.
-        trace: Original signal trace.
-        baseline: Signal baseline value.
-        threshold_value: Detection threshold.
-        min_width: Minimum glitch duration (seconds), or None.
-        max_width: Maximum glitch duration (seconds), or None.
-        sample_rate: Sample rate (Hz), or None.
-        context_samples: Number of context samples to include.
-
-    Returns:
-        List of glitch dictionaries with metadata.
-    """
-    glitches: list[dict[str, Any]] = []
-
-    for group in glitch_groups:
-        start_idx = group[0]
-        end_idx = group[-1] + 1
-        duration_samples = end_idx - start_idx
-
-        # Check width constraints
-        if not _check_width_constraints(duration_samples, min_width, max_width, sample_rate):
-            continue
-
-        # Extract context
-        ctx_start = max(0, start_idx - context_samples)
-        ctx_end = min(len(trace), end_idx + context_samples)
-        context = trace[ctx_start:ctx_end].copy()
-
-        # Compute amplitude deviation
-        amplitude = np.max(np.abs(trace[start_idx:end_idx] - baseline))
-
-        # Severity: normalized amplitude
-        severity = min(1.0, amplitude / (threshold_value * 3))
-
-        glitches.append(
-            {
-                "index": start_idx,
-                "type": "glitch",
-                "severity": float(severity),
-                "duration": duration_samples,
-                "amplitude": float(amplitude),
-                "context": context,
-                "description": f"Glitch at sample {start_idx}, amplitude {amplitude:.3g}",
-            }
-        )
-
-    return glitches
-
-
-def _check_width_constraints(
-    duration_samples: int,
-    min_width: float | None,
-    max_width: float | None,
-    sample_rate: float | None,
-) -> bool:
-    """Check if glitch duration meets width constraints.
-
-    Args:
-        duration_samples: Glitch duration in samples.
-        min_width: Minimum duration (seconds), or None.
-        max_width: Maximum duration (seconds), or None.
-        sample_rate: Sample rate (Hz), or None.
-
-    Returns:
-        True if glitch meets constraints, False otherwise.
-    """
-    if sample_rate is None:
-        return True
-
-    duration_seconds = duration_samples / sample_rate
-
-    if min_width is not None and duration_seconds < min_width:
-        return False
-
-    return not (max_width is not None and duration_seconds > max_width)
-
-
-def _detect_timing_violations(
-    trace: NDArray[np.float64],
-    sample_rate: float,
-    min_width: float | None,
-    max_width: float | None,
-    context_samples: int,
-) -> list[dict[str, Any]]:
-    """Detect timing violations (pulse width violations)."""
-    violations = []
-
-    # Simple threshold for digital signal
-    threshold = (np.max(trace) + np.min(trace)) / 2
-    digital = (trace >= threshold).astype(int)
-
-    # Find edges
-    edges = np.diff(digital)
-    rising_edges = np.where(edges == 1)[0]
-    falling_edges = np.where(edges == -1)[0]
-
-    # Measure pulse widths
-    for rise in rising_edges:
-        # Find next falling edge
-        next_fall = falling_edges[falling_edges > rise]
-        if len(next_fall) == 0:
-            continue
-
-        fall = next_fall[0]
-        pulse_width_samples = fall - rise
-        pulse_width_seconds = pulse_width_samples / sample_rate
-
-        # Check violations
-        violated = False
-        violation_type = ""
-
-        if min_width is not None and pulse_width_seconds < min_width:
-            violated = True
-            violation_type = "too_short"
-
-        if max_width is not None and pulse_width_seconds > max_width:
-            violated = True
-            violation_type = "too_long"
-
-        if violated:
-            # Extract context
-            ctx_start = max(0, rise - context_samples)
-            ctx_end = min(len(trace), fall + context_samples)
-            context = trace[ctx_start:ctx_end].copy()
-
-            # Severity based on deviation
-            if min_width is not None:
-                deviation = abs(pulse_width_seconds - min_width) / min_width
-            elif max_width is not None:
-                deviation = abs(pulse_width_seconds - max_width) / max_width
-            else:
-                deviation = 0.0
-
-            severity = min(1.0, deviation)
-
-            violations.append(
-                {
-                    "index": rise,
-                    "type": f"timing_{violation_type}",
-                    "severity": float(severity),
-                    "duration": pulse_width_samples,
-                    "amplitude": float(pulse_width_seconds),
-                    "context": context,
-                    "description": (
-                        f"Timing violation at sample {rise}: "
-                        f"pulse width {pulse_width_seconds * 1e9:.1f} ns ({violation_type})"
-                    ),
-                }
-            )
-
-    return violations

oscura/utils/search/context.py

@@ -1,294 +0,0 @@
-"""Context extraction around points of interest.
-
-
-This module provides efficient extraction of signal context around
-events, maintaining original time references for debugging workflows.
-"""
-
-from typing import Any
-
-import numpy as np
-from numpy.typing import NDArray
-
-
-def extract_context(
-    trace: NDArray[np.float64],
-    index: int | list[int] | NDArray[np.int_],
-    *,
-    before: int = 100,
-    after: int = 100,
-    sample_rate: float | None = None,
-    include_metadata: bool = True,
-) -> dict[str, Any] | list[dict[str, Any]]:
-    """Extract signal context around a point of interest.
-
-    : Context extraction with time reference preservation.
-    Supports batch extraction for multiple indices and optional protocol data.
-
-    Args:
-        trace: Input signal trace
-        index: Sample index or list of indices to extract context around.
-            Can be int, list of ints, or numpy array.
-        before: Number of samples to include before index (default: 100)
-        after: Number of samples to include after index (default: 100)
-        sample_rate: Optional sample rate in Hz for time calculations
-        include_metadata: Include metadata dict with context info (default: True)
-
-    Returns:
-        If index is scalar: Single context dictionary
-        If index is list/array: List of context dictionaries
-
-        Each context dictionary contains:
-        - data: Extracted sub-trace array
-        - start_index: Starting index in original trace
-        - end_index: Ending index in original trace
-        - center_index: Center index (original query index)
-        - time_reference: Time offset if sample_rate provided
-        - length: Number of samples in context
-
-    Raises:
-        ValueError: If index is out of bounds
-        ValueError: If before or after are negative
-
-    Examples:
-        >>> # Extract context around a glitch
-        >>> trace = np.random.randn(1000)
-        >>> glitch_index = 500
-        >>> context = extract_context(
-        ...     trace,
-        ...     glitch_index,
-        ...     before=50,
-        ...     after=50,
-        ...     sample_rate=1e6
-        ... )
-        >>> print(f"Context length: {len(context['data'])}")
-        >>> print(f"Time reference: {context['time_reference']*1e6:.2f} µs")
-
-        >>> # Batch extraction for multiple events
-        >>> event_indices = [100, 200, 300]
-        >>> contexts = extract_context(
-        ...     trace,
-        ...     event_indices,
-        ...     before=25,
-        ...     after=25
-        ... )
-        >>> print(f"Extracted {len(contexts)} contexts")
-
-    Notes:
-        - Handles edge cases at trace boundaries automatically
-        - Context may be shorter than before+after at boundaries
-        - Time reference is relative to start of extracted context
-        - Original trace is not modified
-
-    References:
-        SRCH-003: Context Extraction
-    """
-    # Phase 1: Input validation
-    _validate_context_params(before, after, trace)
-
-    # Phase 2: Normalize indices
-    indices, return_single = _normalize_indices(index, trace)
-
-    # Phase 3: Extract contexts
-    contexts = [
-        _extract_single_context(trace, idx, before, after, sample_rate, include_metadata)
-        for idx in indices
-    ]
-
-    # Return single context or list
-    return contexts[0] if return_single else contexts
-
-
-def _validate_context_params(before: int, after: int, trace: NDArray[np.float64]) -> None:
-    """Validate context extraction parameters.
-
-    Args:
-        before: Samples before index.
-        after: Samples after index.
-        trace: Input trace.
-
-    Raises:
-        ValueError: If parameters are invalid.
-
-    Example:
-        >>> trace = np.array([1.0, 2.0, 3.0])
-        >>> _validate_context_params(10, 10, trace)
-        >>> _validate_context_params(-1, 10, trace)
-        Traceback (most recent call last):
-        ValueError: before and after must be non-negative
-    """
-    if before < 0 or after < 0:
-        raise ValueError("before and after must be non-negative")
-
-    if trace.size == 0:
-        raise ValueError("Trace cannot be empty")
-
-
-def _normalize_indices(
-    index: int | list[int] | NDArray[np.int_], trace: NDArray[np.float64]
-) -> tuple[list[int], bool]:
-    """Normalize index input to list of integers.
-
-    Args:
-        index: Input index (int, list, or array).
-        trace: Trace to validate against.
-
-    Returns:
-        Tuple of (normalized_indices, return_single_flag).
-
-    Raises:
-        ValueError: If any index is out of bounds.
-
-    Example:
-        >>> trace = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
-        >>> _normalize_indices(2, trace)
-        ([2], True)
-        >>> _normalize_indices([1, 3], trace)
-        ([1, 3], False)
-    """
-    # Handle single index vs multiple indices
-    if isinstance(index, int | np.integer):
-        indices = [int(index)]
-        return_single = True
-    else:
-        indices = [int(i) for i in index]
-        return_single = False
-
-    # Validate indices
-    for idx in indices:
-        if idx < 0 or idx >= len(trace):
-            raise ValueError(f"Index {idx} out of bounds for trace of length {len(trace)}")
-
-    return indices, return_single
-
-
-def _extract_single_context(
-    trace: NDArray[np.float64],
-    idx: int,
-    before: int,
-    after: int,
-    sample_rate: float | None,
-    include_metadata: bool,
-) -> dict[str, Any]:
-    """Extract context for a single index.
-
-    Args:
-        trace: Input signal trace.
-        idx: Center index to extract around.
-        before: Samples before index.
-        after: Samples after index.
-        sample_rate: Optional sample rate.
-        include_metadata: Include metadata dict.
-
-    Returns:
-        Context dictionary with extracted data and metadata.
-
-    Example:
-        >>> trace = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
-        >>> ctx = _extract_single_context(trace, 2, 1, 1, None, False)
-        >>> ctx['data']
-        array([2., 3., 4.])
-    """
-    # Calculate window bounds with boundary handling
-    start_idx, end_idx = _calculate_window_bounds(idx, before, after, len(trace))
-
-    # Extract data
-    data = trace[start_idx:end_idx].copy()
-
-    # Build context dictionary
-    context: dict[str, Any] = {
-        "data": data,
-        "start_index": start_idx,
-        "end_index": end_idx,
-        "center_index": idx,
-        "length": len(data),
-    }
-
-    # Add time information if requested
-    if sample_rate is not None:
-        _add_time_information(context, start_idx, sample_rate, len(data))
-
-    # Add metadata if requested
-    if include_metadata:
-        _add_boundary_metadata(context, idx, start_idx, end_idx, len(trace))
-
-    return context
-
-
-def _calculate_window_bounds(idx: int, before: int, after: int, trace_len: int) -> tuple[int, int]:
-    """Calculate window boundaries with edge handling.
-
-    Args:
-        idx: Center index.
-        before: Samples before center.
-        after: Samples after center.
-        trace_len: Length of trace.
-
-    Returns:
-        Tuple of (start_idx, end_idx).
-
-    Example:
-        >>> _calculate_window_bounds(50, 10, 10, 100)
-        (40, 61)
-        >>> _calculate_window_bounds(5, 10, 10, 100)
-        (0, 16)
-    """
-    start_idx = max(0, idx - before)
-    end_idx = min(trace_len, idx + after + 1)
-    return start_idx, end_idx
-
-
-def _add_time_information(
-    context: dict[str, Any], start_idx: int, sample_rate: float, data_len: int
-) -> None:
-    """Add time reference information to context.
-
-    Args:
-        context: Context dictionary to update.
-        start_idx: Start index in original trace.
-        sample_rate: Sample rate in Hz.
-        data_len: Length of extracted data.
-
-    Example:
-        >>> ctx = {}
-        >>> _add_time_information(ctx, 100, 1e6, 50)
-        >>> ctx['time_reference']
-        0.0001
-        >>> ctx['sample_rate']
-        1000000.0
-    """
-    time_offset = start_idx / sample_rate
-    context["time_reference"] = time_offset
-    context["sample_rate"] = sample_rate
-
-    # Time array for the context
-    dt = 1.0 / sample_rate
-    context["time_array"] = np.arange(data_len) * dt + time_offset
-
-
-def _add_boundary_metadata(
-    context: dict[str, Any], idx: int, start_idx: int, end_idx: int, trace_len: int
-) -> None:
-    """Add boundary metadata to context.
-
-    Args:
-        context: Context dictionary to update.
-        idx: Center index.
-        start_idx: Window start index.
-        end_idx: Window end index.
-        trace_len: Total trace length.
-
-    Example:
-        >>> ctx = {}
-        >>> _add_boundary_metadata(ctx, 5, 0, 11, 100)
-        >>> ctx['metadata']['at_start_boundary']
-        True
-        >>> ctx['metadata']['samples_before']
-        5
-    """
-    context["metadata"] = {
-        "samples_before": idx - start_idx,
-        "samples_after": end_idx - idx - 1,
-        "at_start_boundary": start_idx == 0,
-        "at_end_boundary": end_idx == trace_len,
-    }