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

oscura/{search → utils/search}/__init__.py

@@ -5,9 +5,9 @@ This module enables efficient pattern matching, anomaly detection, and
 context extraction for debugging and analysis workflows.
 """
 
-from oscura.search.anomaly import find_anomalies
-from oscura.search.context import extract_context
-from oscura.search.pattern import find_pattern
+from oscura.utils.search.anomaly import find_anomalies
+from oscura.utils.search.context import extract_context
+from oscura.utils.search.pattern import find_pattern
 
 __all__ = [
     "extract_context",

oscura/{search → utils/search}/anomaly.py

@@ -94,36 +94,33 @@ def find_anomalies(
     if anomaly_type not in valid_types:
         raise ValueError(f"Invalid anomaly_type '{anomaly_type}'. Must be one of: {valid_types}")
 
-    anomalies: list[dict[str, Any]] = []
+    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":
-        anomalies = _detect_glitches(
-            trace,
-            threshold=threshold,
-            min_width=min_width,
-            max_width=max_width,
-            sample_rate=sample_rate,
-            context_samples=context_samples,
+        return _detect_glitches(
+            trace, threshold, min_width, max_width, sample_rate, context_samples
         )
 
-    elif anomaly_type == "timing":
+    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)
 
-        anomalies = _detect_timing_violations(
-            trace,
-            sample_rate=sample_rate,
-            min_width=min_width,
-            max_width=max_width,
-            context_samples=context_samples,
-        )
-
-    elif anomaly_type == "protocol":
-        # Protocol error detection would integrate with protocol decoders
-        # For now, return empty list with note
-        anomalies = []
-
-    return anomalies
+    # Protocol error detection would integrate with protocol decoders
+    return []
 
 
 def _detect_glitches(
@@ -134,70 +131,175 @@ def _detect_glitches(
     sample_rate: float | None,
     context_samples: int,
 ) -> list[dict[str, Any]]:
-    """Detect voltage glitches using derivative method."""
-    glitches: 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.
 
-    # Auto-threshold if not provided
-    threshold_value: float
-    if threshold is None:
-        # Use 3 sigma as default threshold
-        threshold_value = float(3 * np.std(trace))
-    else:
-        threshold_value = threshold
+    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
-    derivative = np.diff(trace)
-    abs_derivative = np.abs(derivative)
+    abs_derivative = np.abs(np.diff(trace))
 
-    # Find points where derivative exceeds threshold
-    glitch_candidates = np.where(abs_derivative > threshold_value)[0]
+    # 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 glitches
+        return []
 
     # Group consecutive points into glitch events
-    glitch_groups = []
-    current_group = [glitch_candidates[0]]
+    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 glitch_candidates[1:]:
+    for idx in indices[1:]:
         if idx == current_group[-1] + 1:
-            current_group.append(idx)
+            current_group.append(int(idx))
         else:
-            glitch_groups.append(current_group)
-            current_group = [idx]
+            groups.append(current_group)
+            current_group = [int(idx)]
 
     if current_group:
-        glitch_groups.append(current_group)
+        groups.append(current_group)
+
+    return groups
+
+
+def _compute_baseline(trace: NDArray[np.float64]) -> float:
+    """Compute baseline value using median.
 
-    # Compute baseline once for all glitches (performance optimization)
-    # For very large arrays (>1M samples), use percentile approximation
+    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
-        baseline = float(np.percentile(trace, 50, method="linear"))
-    else:
-        baseline = float(np.median(trace))
+        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]] = []
 
-    # Filter by width if specified
     for group in glitch_groups:
         start_idx = group[0]
         end_idx = group[-1] + 1
         duration_samples = end_idx - start_idx
 
         # Check width constraints
-        if sample_rate is not None:
-            duration_seconds = duration_samples / sample_rate
-
-            if min_width is not None and duration_seconds < min_width:
-                continue
-            if max_width is not None and duration_seconds > max_width:
-                continue
+        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 (baseline computed once above)
+        # Compute amplitude deviation
         amplitude = np.max(np.abs(trace[start_idx:end_idx] - baseline))
 
         # Severity: normalized amplitude
@@ -218,6 +320,34 @@ def _detect_glitches(
     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,

oscura/utils/search/context.py

@@ -0,0 +1,294 @@
+"""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,
+    }