oscura 0.0.1__py3-none-any.whl → 0.1.1__py3-none-any.whl

oscura/visualization/optimization.py

@@ -0,0 +1,1028 @@
+"""Visualization optimization functions for automatic plot parameter selection.
+
+This module provides intelligent optimization algorithms for plot parameters
+including axis ranges, decimation, grid spacing, dynamic range, and
+interesting region detection.
+
+
+Example:
+    >>> from oscura.visualization.optimization import calculate_optimal_y_range
+    >>> y_min, y_max = calculate_optimal_y_range(signal_data)
+    >>> ax.set_ylim(y_min, y_max)
+
+References:
+    - Wilkinson's tick placement algorithm (1999)
+    - LTTB (Largest Triangle Three Buckets) decimation
+    - Percentile-based outlier detection
+    - Edge detection using Sobel operators
+    - Statistical outlier detection using MAD (Median Absolute Deviation)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+from scipy import signal as sp_signal
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def calculate_optimal_y_range(
+    data: NDArray[np.float64],
+    *,
+    outlier_threshold: float = 3.0,
+    margin_percent: float = 5.0,
+    symmetric: bool = False,
+    clip_warning_threshold: float = 0.01,
+) -> tuple[float, float]:
+    """Calculate optimal Y-axis range with outlier exclusion.
+
+    Uses percentile-based outlier detection and smart margins to ensure
+    data visibility without wasted space. Detects clipping when too many
+    samples are excluded.
+
+    Args:
+        data: Signal data array.
+        outlier_threshold: Number of standard deviations for outlier exclusion (default 3.0).
+        margin_percent: Margin as percentage of data range (default 5%, auto-adjusts).
+        symmetric: If True, use symmetric range ±max for bipolar signals.
+        clip_warning_threshold: Warn if this fraction of samples are clipped (default 1%).
+
+    Returns:
+        Tuple of (y_min, y_max) for axis limits.
+
+    Raises:
+        ValueError: If data is empty or all NaN.
+
+    Example:
+        >>> signal = np.random.randn(1000)
+        >>> y_min, y_max = calculate_optimal_y_range(signal, symmetric=True)
+        >>> # For bipolar signal: y_min ≈ -y_max
+
+    References:
+        VIS-013: Auto Y-Axis Range Optimization
+    """
+    if len(data) == 0:
+        raise ValueError("Data array is empty")
+
+    # Remove NaN values
+    clean_data = data[~np.isnan(data)]
+
+    if len(clean_data) == 0:
+        raise ValueError("Data contains only NaN values")
+
+    # Use percentile-based outlier detection (1st-99th percentile default)
+    # This corresponds to approximately 3-sigma for normal distributions
+    lower_percentile = 0.5
+    upper_percentile = 99.5
+
+    # Calculate robust statistics using percentiles
+    np.percentile(clean_data, lower_percentile)
+    np.percentile(clean_data, upper_percentile)
+
+    # Filter outliers beyond threshold sigma
+    median = np.median(clean_data)
+    mad = np.median(np.abs(clean_data - median))
+    robust_std = 1.4826 * mad  # MAD to std conversion
+
+    if robust_std > 0:
+        z_scores = np.abs(clean_data - median) / robust_std
+        inlier_mask = z_scores <= outlier_threshold
+        filtered_data = clean_data[inlier_mask]
+    else:
+        filtered_data = clean_data
+
+    # Detect clipping
+    clipped_fraction = 1.0 - (len(filtered_data) / len(clean_data))
+    if clipped_fraction > clip_warning_threshold:
+        import warnings
+
+        warnings.warn(
+            f"Clipping detected: {clipped_fraction * 100:.1f}% of samples "
+            f"excluded by range limits (threshold: {clip_warning_threshold * 100:.1f}%)",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # Calculate data range
+    data_min = np.min(filtered_data)
+    data_max = np.max(filtered_data)
+    data_range = data_max - data_min
+
+    # Smart margin selection based on data density
+    if len(filtered_data) > 10000:
+        # Dense data: smaller margin (2%)
+        margin = 0.02
+    elif len(filtered_data) < 100:
+        # Sparse data: larger margin (10%)
+        margin = 0.10
+    else:
+        # Default margin (5%)
+        margin = margin_percent / 100.0
+
+    # Apply symmetric range mode for bipolar signals
+    if symmetric:
+        max_abs = max(abs(data_min), abs(data_max))
+        margin_value = max_abs * margin
+        y_min = -(max_abs + margin_value)
+        y_max = max_abs + margin_value
+    else:
+        margin_value = data_range * margin
+        y_min = data_min - margin_value
+        y_max = data_max + margin_value
+
+    return (float(y_min), float(y_max))
+
+
+def calculate_optimal_x_window(
+    time: NDArray[np.float64],
+    data: NDArray[np.float64],
+    *,
+    target_features: int = 5,
+    samples_per_pixel: float = 2.0,
+    screen_width: int = 1000,
+    activity_threshold: float = 0.1,
+) -> tuple[float, float]:
+    """Calculate optimal X-axis time window with activity detection.
+
+    Intelligently determines time window based on signal activity and features.
+    Detects regions with significant activity and zooms to show N complete features.
+
+    Args:
+        time: Time axis array in seconds.
+        data: Signal data array.
+        target_features: Number of complete features to display (default 5-10).
+        samples_per_pixel: Threshold for decimation (default >2 samples/pixel).
+        screen_width: Screen width in pixels for decimation calculation.
+        activity_threshold: Relative threshold for activity detection (0-1).
+
+    Returns:
+        Tuple of (t_start, t_end) for time window in seconds.
+
+    Raises:
+        ValueError: If arrays are empty or mismatched.
+
+    Example:
+        >>> time = np.linspace(0, 1e-3, 10000)
+        >>> signal = np.sin(2 * np.pi * 1000 * time)
+        >>> t_start, t_end = calculate_optimal_x_window(time, signal, target_features=5)
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+    """
+    if len(time) == 0 or len(data) == 0:
+        raise ValueError("Time or data array is empty")
+
+    if len(time) != len(data):
+        raise ValueError(f"Time and data arrays must match: {len(time)} vs {len(data)}")
+
+    # Detect signal activity using RMS windowing
+    window_size = max(10, len(data) // 100)
+    rms = np.sqrt(np.convolve(data**2, np.ones(window_size) / window_size, mode="same"))
+
+    # Find activity threshold
+    rms_threshold = activity_threshold * np.max(rms)
+    active_regions = rms > rms_threshold
+
+    if not np.any(active_regions):
+        # No significant activity, return full range
+        return (float(time[0]), float(time[-1]))
+
+    # Find first active region
+    active_indices = np.where(active_regions)[0]
+    first_active = active_indices[0]
+
+    # Detect features using autocorrelation for periodic signals
+    # Use a subset for efficiency
+    subset_size = min(5000, len(data) - first_active)
+    subset_start = first_active
+    subset_end = subset_start + subset_size
+
+    if subset_end > len(data):
+        subset_end = len(data)
+        subset_start = max(0, subset_end - subset_size)
+
+    subset = data[subset_start:subset_end]
+
+    # Try to detect periodicity
+    if len(subset) > 20:
+        # Use zero-crossing to detect period
+        mean_val = np.mean(subset)
+        crossings = np.where(np.diff(np.sign(subset - mean_val)))[0]
+
+        if len(crossings) >= 4:
+            # Estimate period from crossings (two crossings per cycle)
+            periods = np.diff(crossings[::2])
+            if len(periods) > 0:
+                median_period = np.median(periods)
+                samples_per_feature = int(median_period * 2)  # Full cycle
+
+                # Calculate window to show target_features
+                total_samples = samples_per_feature * target_features
+                window_start = first_active
+                window_end = min(window_start + total_samples, len(time) - 1)
+
+                return (float(time[window_start]), float(time[window_end]))
+
+    # Fallback: zoom to first N% of active region
+    active_duration = len(active_indices)
+    zoom_samples = min(active_duration, screen_width * int(samples_per_pixel))
+    window_end = min(first_active + zoom_samples, len(time) - 1)
+
+    return (float(time[first_active]), float(time[window_end]))
+
+
+def calculate_grid_spacing(
+    axis_min: float,
+    axis_max: float,
+    *,
+    target_major_ticks: int = 7,
+    log_scale: bool = False,
+    time_axis: bool = False,
+) -> tuple[float, float]:
+    """Calculate optimal grid spacing using nice numbers.
+
+    Implements Wilkinson's tick placement algorithm to generate
+    aesthetically pleasing major and minor grid line spacing.
+
+    Args:
+        axis_min: Minimum axis value.
+        axis_max: Maximum axis value.
+        target_major_ticks: Target number of major gridlines (default 5-10).
+        log_scale: Use logarithmic spacing for log-scale axes.
+        time_axis: Use time-unit alignment (ms, μs, ns).
+
+    Returns:
+        Tuple of (major_spacing, minor_spacing).
+
+    Raises:
+        ValueError: If axis_max <= axis_min.
+
+    Example:
+        >>> major, minor = calculate_grid_spacing(0, 100, target_major_ticks=5)
+        >>> # Returns nice numbers like (20.0, 4.0)
+
+    References:
+        VIS-019: Grid Auto-Spacing
+        Wilkinson (1999): The Grammar of Graphics
+    """
+    if axis_max <= axis_min:
+        raise ValueError(f"Invalid axis range: [{axis_min}, {axis_max}]")
+
+    if log_scale:
+        # Logarithmic spacing: major grids at decade boundaries
+        log_min = np.log10(max(axis_min, 1e-100))
+        log_max = np.log10(axis_max)
+        n_decades = log_max - log_min
+
+        if n_decades < 1:
+            # Less than one decade: use linear spacing
+            major_spacing = _calculate_nice_number((axis_max - axis_min) / target_major_ticks)
+            minor_spacing = major_spacing / 5
+        else:
+            # Major grids at decades, minors at 2, 5
+            major_spacing = 10.0 ** np.ceil(n_decades / target_major_ticks)
+            minor_spacing = major_spacing / 5
+
+        return (float(major_spacing), float(minor_spacing))
+
+    # Linear spacing with nice numbers
+    axis_range = axis_max - axis_min
+    rough_spacing = axis_range / target_major_ticks
+
+    # Find nice number for major spacing
+    major_spacing = _calculate_nice_number(rough_spacing)
+
+    # Minor spacing: 1/5 or 1/2 of major
+    # Use 1/5 for spacings ending in 5 or 10, 1/2 otherwise
+    if major_spacing % 5 == 0 or major_spacing % 10 == 0:
+        minor_spacing = major_spacing / 5
+    else:
+        minor_spacing = major_spacing / 2
+
+    # Time axis alignment
+    if time_axis:
+        # Align to natural time units
+        time_units = [
+            1e-9,
+            2e-9,
+            5e-9,  # ns
+            1e-6,
+            2e-6,
+            5e-6,  # μs
+            1e-3,
+            2e-3,
+            5e-3,  # ms
+            1.0,
+            2.0,
+            5.0,
+        ]  # s
+
+        # Find closest time unit
+        closest_idx = np.argmin(np.abs(np.array(time_units) - major_spacing))
+        major_spacing = time_units[closest_idx]
+        minor_spacing = major_spacing / 5
+
+    # Check if grid would be too dense
+    actual_major_ticks = axis_range / major_spacing
+    if actual_major_ticks > 15:
+        # Disable minor grids (set equal to major)
+        minor_spacing = major_spacing
+
+    return (float(major_spacing), float(minor_spacing))
+
+
+def _calculate_nice_number(value: float) -> float:
+    """Calculate nice number using powers of 10 × (1, 2, 5).  # noqa: RUF002
+
+    Args:
+        value: Input value.
+
+    Returns:
+        Nice number (1, 2, or 5 × 10^n).  # noqa: RUF002
+    """
+    if value <= 0:
+        return 1.0
+
+    # Find exponent
+    exponent = np.floor(np.log10(value))
+    fraction = value / (10**exponent)
+
+    # Round to nice fraction (1, 2, 5)
+    if fraction < 1.5:
+        nice_fraction = 1.0
+    elif fraction < 3.5:
+        nice_fraction = 2.0
+    elif fraction < 7.5:
+        nice_fraction = 5.0
+    else:
+        nice_fraction = 10.0
+
+    return nice_fraction * (10**exponent)  # type: ignore[no-any-return]
+
+
+def optimize_db_range(
+    spectrum: NDArray[np.float64],
+    *,
+    noise_floor_percentile: float = 5.0,
+    peak_threshold_db: float = 10.0,
+    margin_db: float = 10.0,
+    max_dynamic_range_db: float = 100.0,
+) -> tuple[float, float]:
+    """Optimize dB range for spectrum plots with noise floor detection.
+
+    Automatically detects noise floor and calculates optimal dynamic range
+    for maximum information visibility in frequency-domain plots.
+
+    Args:
+        spectrum: Spectrum magnitude array (linear or dB).
+        noise_floor_percentile: Percentile for noise floor estimation (default 5%).
+        peak_threshold_db: Threshold above noise floor for peak detection (default 10 dB).
+        margin_db: Margin below noise floor (default 10 dB).
+        max_dynamic_range_db: Maximum dynamic range to display (default 100 dB).
+
+    Returns:
+        Tuple of (db_min, db_max) for spectrum plot limits.
+
+    Raises:
+        ValueError: If spectrum is empty or all zero.
+
+    Example:
+        >>> spectrum_db = 20 * np.log10(np.abs(fft_result))
+        >>> db_min, db_max = optimize_db_range(spectrum_db)
+        >>> ax.set_ylim(db_min, db_max)
+
+    References:
+        VIS-022: Spectrum dB Range Optimization
+    """
+    if len(spectrum) == 0:
+        raise ValueError("Spectrum array is empty")
+
+    # Convert to dB if needed (check if values are in linear scale)
+    if np.max(spectrum) > 100:
+        # Likely linear, convert to dB
+        spectrum_db = 20 * np.log10(np.maximum(spectrum, 1e-100))
+    else:
+        # Assume already in dB
+        spectrum_db = spectrum
+
+    # Detect noise floor using percentile method
+    noise_floor = np.percentile(spectrum_db, noise_floor_percentile)
+
+    # Find signal peaks using scipy
+    peak_indices, peak_properties = sp_signal.find_peaks(
+        spectrum_db,
+        height=noise_floor + peak_threshold_db,
+        prominence=peak_threshold_db / 2,
+    )
+
+    if len(peak_indices) > 0:
+        peak_max = np.max(peak_properties["peak_heights"])
+    else:
+        # No peaks detected, use maximum value
+        peak_max = np.max(spectrum_db)
+
+    # Calculate dB range
+    db_max = float(peak_max)
+    db_min = float(noise_floor - margin_db)
+
+    # Apply dynamic range compression if too wide
+    dynamic_range = db_max - db_min
+    if dynamic_range > max_dynamic_range_db:
+        db_min = db_max - max_dynamic_range_db
+
+    return (db_min, db_max)
+
+
+def decimate_for_display(
+    time: NDArray[np.float64],
+    data: NDArray[np.float64],
+    *,
+    max_points: int = 2000,
+    method: Literal["lttb", "minmax", "uniform"] = "lttb",
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Decimate signal data for display using LTTB or min-max envelope.
+
+    Intelligently reduces number of points while preserving visual appearance
+    and important features like edges and peaks.
+
+    Args:
+        time: Time axis array.
+        data: Signal data array.
+        max_points: Maximum number of points to retain.
+        method: Decimation method ("lttb", "minmax", "uniform").
+
+    Returns:
+        Tuple of (decimated_time, decimated_data).
+
+    Raises:
+        ValueError: If arrays are empty or method is invalid.
+
+    Example:
+        >>> time_dec, data_dec = decimate_for_display(time, data, max_points=1000)
+        >>> # Reduced from 100k to 1k points while preserving shape
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+        LTTB: Largest Triangle Three Buckets algorithm
+    """
+    if len(time) == 0 or len(data) == 0:
+        raise ValueError("Time or data array is empty")
+
+    if len(time) != len(data):
+        raise ValueError(f"Time and data arrays must match: {len(time)} vs {len(data)}")
+
+    # Don't decimate if already below threshold
+    if len(data) <= max_points:
+        return (time, data)
+
+    # Never decimate very small signals
+    if len(data) < 10:
+        return (time, data)
+
+    if method == "uniform":
+        # Simple uniform stride decimation
+        stride = len(data) // max_points
+        indices = np.arange(0, len(data), stride)
+        return (time[indices], data[indices])
+
+    elif method == "minmax":
+        # Min-max envelope: preserve peaks and valleys
+        return _decimate_minmax(time, data, max_points)
+
+    elif method == "lttb":
+        # Largest Triangle Three Buckets
+        return _decimate_lttb(time, data, max_points)
+
+    else:
+        raise ValueError(f"Invalid decimation method: {method}")
+
+
+def _decimate_minmax(
+    time: NDArray[np.float64],
+    data: NDArray[np.float64],
+    max_points: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Decimate using min-max envelope to preserve peaks/valleys.
+
+    Args:
+        time: Time array.
+        data: Signal data array.
+        max_points: Maximum number of points to retain.
+
+    Returns:
+        Tuple of (decimated_time, decimated_data).
+    """
+    # Calculate bucket size
+    bucket_size = len(data) // (max_points // 2)
+
+    decimated_time = []
+    decimated_data = []
+
+    for i in range(0, len(data), bucket_size):
+        bucket = data[i : i + bucket_size]
+        time_bucket = time[i : i + bucket_size]
+
+        if len(bucket) > 0:
+            # Add min and max from each bucket
+            min_idx = np.argmin(bucket)
+            max_idx = np.argmax(bucket)
+
+            # Add in chronological order
+            if min_idx < max_idx:
+                decimated_time.extend([time_bucket[min_idx], time_bucket[max_idx]])
+                decimated_data.extend([bucket[min_idx], bucket[max_idx]])
+            else:
+                decimated_time.extend([time_bucket[max_idx], time_bucket[min_idx]])
+                decimated_data.extend([bucket[max_idx], bucket[min_idx]])
+
+    return (np.array(decimated_time), np.array(decimated_data))
+
+
+def _decimate_lttb(
+    time: NDArray[np.float64],
+    data: NDArray[np.float64],
+    max_points: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Decimate using Largest Triangle Three Buckets algorithm.
+
+    Preserves visual appearance by selecting points that maximize
+    the area of triangles formed with neighboring buckets.
+
+    Args:
+        time: Time array.
+        data: Signal data array.
+        max_points: Maximum number of points to retain.
+
+    Returns:
+        Tuple of (decimated_time, decimated_data).
+    """
+    if len(data) <= max_points:
+        return (time, data)
+
+    # Always include first and last points
+    sampled_time = [time[0]]
+    sampled_data = [data[0]]
+
+    # Calculate bucket size
+    bucket_size = (len(data) - 2) / (max_points - 2)
+
+    # Previous selected point
+    prev_idx = 0
+
+    for i in range(max_points - 2):
+        # Calculate average point of next bucket (for triangle area calculation)
+        avg_range_start = int((i + 1) * bucket_size) + 1
+        avg_range_end = int((i + 2) * bucket_size) + 1
+        avg_range_end = min(avg_range_end, len(data))
+
+        if avg_range_start < avg_range_end:
+            avg_time = np.mean(time[avg_range_start:avg_range_end])
+            avg_data = np.mean(data[avg_range_start:avg_range_end])
+        else:
+            avg_time = time[-1]
+            avg_data = data[-1]
+
+        # Current bucket range
+        range_start = int(i * bucket_size) + 1
+        range_end = int((i + 1) * bucket_size) + 1
+        range_end = min(range_end, len(data) - 1)
+
+        # Find point in current bucket that forms largest triangle
+        prev_time = time[prev_idx]
+        prev_data = data[prev_idx]
+
+        max_area = -1.0
+        max_idx = range_start
+
+        for idx in range(range_start, range_end):
+            # Calculate triangle area
+            area = abs(
+                (prev_time - avg_time) * (data[idx] - prev_data)
+                - (prev_time - time[idx]) * (avg_data - prev_data)
+            )
+
+            if area > max_area:
+                max_area = area
+                max_idx = idx
+
+        sampled_time.append(time[max_idx])
+        sampled_data.append(data[max_idx])
+        prev_idx = max_idx
+
+    # Always include last point
+    sampled_time.append(time[-1])
+    sampled_data.append(data[-1])
+
+    return (np.array(sampled_time), np.array(sampled_data))
+
+
+@dataclass
+class InterestingRegion:
+    """Represents an interesting region in a signal.
+
+    Attributes:
+        start_idx: Starting sample index
+        end_idx: Ending sample index
+        start_time: Starting time in seconds
+        end_time: Ending time in seconds
+        type: Type of interesting feature
+        significance: Significance score (0-1, higher is more significant)
+        metadata: Additional metadata about the region
+    """
+
+    start_idx: int
+    end_idx: int
+    start_time: float
+    end_time: float
+    type: Literal["edge", "glitch", "anomaly", "pattern_change"]
+    significance: float
+    metadata: dict  # type: ignore[type-arg]
+
+
+def detect_interesting_regions(
+    signal: NDArray[np.float64],
+    sample_rate: float,
+    *,
+    edge_threshold: float | None = None,
+    glitch_sigma: float = 3.0,
+    anomaly_threshold: float = 3.0,
+    min_region_samples: int = 10,
+    max_regions: int = 10,
+) -> list[InterestingRegion]:
+    """Detect interesting regions in a signal for automatic zoom/focus.
+
+    : Automatically detect and zoom to interesting signal
+    regions such as edges, glitches, anomalies, or pattern changes.
+
+    Args:
+        signal: Input signal array
+        sample_rate: Sample rate in Hz
+        edge_threshold: Edge detection threshold (default: auto from signal stddev)
+        glitch_sigma: Sigma threshold for glitch detection (default: 3.0)
+        anomaly_threshold: Threshold for anomaly detection in sigma (default: 3.0)
+        min_region_samples: Minimum samples per region (default: 10)
+        max_regions: Maximum number of regions to return (default: 10)
+
+    Returns:
+        List of InterestingRegion objects, sorted by significance (descending)
+
+    Raises:
+        ValueError: If signal is empty or sample_rate is invalid
+
+    Example:
+        >>> signal = np.sin(2*np.pi*1000*t) + 0.1*np.random.randn(len(t))
+        >>> regions = detect_interesting_regions(signal, 1e6)
+        >>> print(f"Found {len(regions)} interesting regions")
+
+    References:
+        VIS-020: Zoom to Interesting Regions
+        Edge detection: Sobel operator on signal derivative
+        Glitch detection: MAD-based outlier detection
+    """
+    if len(signal) == 0:
+        raise ValueError("Signal cannot be empty")
+    if sample_rate <= 0:
+        raise ValueError("Sample rate must be positive")
+    if min_region_samples < 1:
+        raise ValueError("min_region_samples must be >= 1")
+
+    regions: list[InterestingRegion] = []
+    1.0 / sample_rate
+
+    # 1. Edge detection using first derivative
+    edges = _detect_edges(signal, sample_rate, edge_threshold)
+    regions.extend(edges)
+
+    # 2. Glitch detection using statistical outliers
+    glitches = _detect_glitches(signal, sample_rate, glitch_sigma)
+    regions.extend(glitches)
+
+    # 3. Anomaly detection using MAD
+    anomalies = _detect_anomalies(signal, sample_rate, anomaly_threshold)
+    regions.extend(anomalies)
+
+    # 4. Pattern change detection (simplified using variance changes)
+    pattern_changes = _detect_pattern_changes(signal, sample_rate)
+    regions.extend(pattern_changes)
+
+    # Filter out regions that are too small
+    regions = [r for r in regions if (r.end_idx - r.start_idx) >= min_region_samples]
+
+    # Sort by significance (descending)
+    regions.sort(key=lambda r: r.significance, reverse=True)
+
+    # Return top N regions
+    return regions[:max_regions]
+
+
+def _detect_edges(
+    signal: NDArray[np.float64],
+    sample_rate: float,
+    threshold: float | None,
+) -> list[InterestingRegion]:
+    """Detect edge transitions using first derivative.
+
+    Args:
+        signal: Input signal
+        sample_rate: Sample rate in Hz
+        threshold: Edge threshold (auto if None)
+
+    Returns:
+        List of edge regions
+    """
+    # Calculate first derivative (gradient)
+    gradient = np.gradient(signal)
+
+    # Auto threshold based on signal statistics
+    if threshold is None:
+        threshold = np.std(gradient) * 2.0
+
+    # Find where gradient exceeds threshold
+    edge_mask = np.abs(gradient) > threshold
+
+    # Find continuous edge regions
+    regions: list[InterestingRegion] = []
+    in_edge = False
+    start_idx = 0
+
+    for i, is_edge in enumerate(edge_mask):
+        if is_edge and not in_edge:
+            # Start of edge
+            start_idx = i
+            in_edge = True
+        elif not is_edge and in_edge:
+            # End of edge
+            end_idx = i
+
+            # Calculate significance based on gradient magnitude
+            edge_gradient = gradient[start_idx:end_idx]
+            significance = min(1.0, np.max(np.abs(edge_gradient)) / (threshold * 5))
+
+            time_base = 1.0 / sample_rate
+            regions.append(
+                InterestingRegion(
+                    start_idx=start_idx,
+                    end_idx=end_idx,
+                    start_time=start_idx * time_base,
+                    end_time=end_idx * time_base,
+                    type="edge",
+                    significance=significance,
+                    metadata={
+                        "max_gradient": float(np.max(np.abs(edge_gradient))),
+                        "threshold": threshold,
+                    },
+                )
+            )
+            in_edge = False
+
+    # Handle edge at end of signal
+    if in_edge:
+        end_idx = len(signal)
+        edge_gradient = gradient[start_idx:end_idx]
+        significance = min(1.0, np.max(np.abs(edge_gradient)) / (threshold * 5))
+        time_base = 1.0 / sample_rate
+        regions.append(
+            InterestingRegion(
+                start_idx=start_idx,
+                end_idx=end_idx,
+                start_time=start_idx * time_base,
+                end_time=end_idx * time_base,
+                type="edge",
+                significance=significance,
+                metadata={
+                    "max_gradient": float(np.max(np.abs(edge_gradient))),
+                    "threshold": threshold,
+                },
+            )
+        )
+
+    return regions
+
+
+def _detect_glitches(
+    signal: NDArray[np.float64],
+    sample_rate: float,
+    sigma_threshold: float,
+) -> list[InterestingRegion]:
+    """Detect isolated spikes (glitches) using z-score.
+
+    Args:
+        signal: Input signal
+        sample_rate: Sample rate in Hz
+        sigma_threshold: Sigma threshold for outlier detection
+
+    Returns:
+        List of glitch regions
+    """
+    # Calculate z-scores
+    mean = np.mean(signal)
+    std = np.std(signal)
+
+    if std == 0:
+        return []
+
+    z_scores = np.abs((signal - mean) / std)
+
+    # Find outliers
+    outlier_mask = z_scores > sigma_threshold
+
+    # Find isolated glitches (single sample or very short bursts)
+    regions: list[InterestingRegion] = []
+    time_base = 1.0 / sample_rate
+
+    i = 0
+    while i < len(outlier_mask):
+        if outlier_mask[i]:
+            # Start of potential glitch
+            start_idx = i
+
+            # Find end of glitch (max 5 samples to be considered a glitch)
+            while i < len(outlier_mask) and outlier_mask[i] and (i - start_idx) < 5:
+                i += 1
+
+            end_idx = i
+
+            # Calculate significance based on z-score
+            glitch_z_scores = z_scores[start_idx:end_idx]
+            significance = min(1.0, np.max(glitch_z_scores) / (sigma_threshold * 3))
+
+            regions.append(
+                InterestingRegion(
+                    start_idx=start_idx,
+                    end_idx=end_idx,
+                    start_time=start_idx * time_base,
+                    end_time=end_idx * time_base,
+                    type="glitch",
+                    significance=significance,
+                    metadata={
+                        "max_z_score": float(np.max(glitch_z_scores)),
+                        "threshold_sigma": sigma_threshold,
+                    },
+                )
+            )
+        else:
+            i += 1
+
+    return regions
+
+
+def _detect_anomalies(
+    signal: NDArray[np.float64],
+    sample_rate: float,
+    threshold_sigma: float,
+) -> list[InterestingRegion]:
+    """Detect anomalies using MAD (Median Absolute Deviation).
+
+    Args:
+        signal: Input signal
+        sample_rate: Sample rate in Hz
+        threshold_sigma: Sigma threshold for MAD
+
+    Returns:
+        List of anomaly regions
+    """
+    # Calculate MAD
+    median = np.median(signal)
+    mad = np.median(np.abs(signal - median))
+
+    if mad == 0:
+        return []
+
+    # Modified z-score using MAD (more robust than standard z-score)
+    modified_z_scores = 0.6745 * (signal - median) / mad
+
+    # Find anomalies
+    anomaly_mask = np.abs(modified_z_scores) > threshold_sigma
+
+    # Find continuous anomaly regions
+    regions: list[InterestingRegion] = []
+    in_anomaly = False
+    start_idx = 0
+    time_base = 1.0 / sample_rate
+
+    for i, is_anomaly in enumerate(anomaly_mask):
+        if is_anomaly and not in_anomaly:
+            start_idx = i
+            in_anomaly = True
+        elif not is_anomaly and in_anomaly:
+            end_idx = i
+
+            # Calculate significance
+            anomaly_scores = modified_z_scores[start_idx:end_idx]
+            significance = min(1.0, np.max(np.abs(anomaly_scores)) / (threshold_sigma * 3))
+
+            regions.append(
+                InterestingRegion(
+                    start_idx=start_idx,
+                    end_idx=end_idx,
+                    start_time=start_idx * time_base,
+                    end_time=end_idx * time_base,
+                    type="anomaly",
+                    significance=significance,
+                    metadata={
+                        "max_mad_score": float(np.max(np.abs(anomaly_scores))),
+                        "threshold_sigma": threshold_sigma,
+                    },
+                )
+            )
+            in_anomaly = False
+
+    # Handle anomaly at end
+    if in_anomaly:
+        end_idx = len(signal)
+        anomaly_scores = modified_z_scores[start_idx:end_idx]
+        significance = min(1.0, np.max(np.abs(anomaly_scores)) / (threshold_sigma * 3))
+        regions.append(
+            InterestingRegion(
+                start_idx=start_idx,
+                end_idx=end_idx,
+                start_time=start_idx * time_base,
+                end_time=end_idx * time_base,
+                type="anomaly",
+                significance=significance,
+                metadata={
+                    "max_mad_score": float(np.max(np.abs(anomaly_scores))),
+                    "threshold_sigma": threshold_sigma,
+                },
+            )
+        )
+
+    return regions
+
+
+def _detect_pattern_changes(
+    signal: NDArray[np.float64],
+    sample_rate: float,
+) -> list[InterestingRegion]:
+    """Detect pattern changes using windowed variance analysis.
+
+    Args:
+        signal: Input signal
+        sample_rate: Sample rate in Hz
+
+    Returns:
+        List of pattern change regions
+    """
+    # Use sliding window to detect variance changes
+    window_size = min(100, len(signal) // 10)
+
+    if window_size < 10:
+        return []
+
+    # Calculate windowed variance
+    variances = np.zeros(len(signal) - window_size + 1)
+    for i in range(len(variances)):
+        variances[i] = np.var(signal[i : i + window_size])
+
+    # Detect changes in variance
+    if len(variances) < 2:
+        return []
+
+    variance_gradient = np.gradient(variances)
+    threshold = np.std(variance_gradient) * 2.0
+
+    change_mask = np.abs(variance_gradient) > threshold
+
+    # Find change regions
+    regions: list[InterestingRegion] = []
+    time_base = 1.0 / sample_rate
+
+    for i in range(len(change_mask)):
+        if change_mask[i]:
+            start_idx = i
+            end_idx = min(i + window_size, len(signal))
+
+            # Calculate significance
+            significance = min(1.0, np.abs(variance_gradient[i]) / (threshold * 5))
+
+            regions.append(
+                InterestingRegion(
+                    start_idx=start_idx,
+                    end_idx=end_idx,
+                    start_time=start_idx * time_base,
+                    end_time=end_idx * time_base,
+                    type="pattern_change",
+                    significance=significance,
+                    metadata={
+                        "variance_change": float(variance_gradient[i]),
+                        "threshold": threshold,
+                    },
+                )
+            )
+
+    return regions
+
+
+__all__ = [
+    "InterestingRegion",
+    "calculate_grid_spacing",
+    "calculate_optimal_x_window",
+    "calculate_optimal_y_range",
+    "decimate_for_display",
+    "detect_interesting_regions",
+    "optimize_db_range",
+]