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

oscura/utils/progressive.py

@@ -0,0 +1,352 @@
+"""Progressive resolution analysis for memory-constrained scenarios.
+
+This module provides multi-pass analysis capabilities: preview first,
+then zoom into regions of interest for detailed analysis.
+
+
+Example:
+    >>> from oscura.utils.progressive import create_preview, analyze_roi
+    >>> preview = create_preview(trace, downsample_factor=10)
+    >>> # User inspects preview, selects ROI
+    >>> roi_result = analyze_roi(trace, start_time=0.001, end_time=0.002)
+
+References:
+    Multi-resolution analysis techniques
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+    from oscura.core.types import WaveformTrace
+
+
+@dataclass
+class PreviewResult:
+    """Result of preview analysis.
+
+
+    Attributes:
+        downsampled_data: Downsampled waveform data.
+        downsample_factor: Downsampling factor applied.
+        original_length: Length of original signal.
+        preview_length: Length of preview signal.
+        sample_rate: Sample rate of preview (original / factor).
+        time_vector: Time axis for preview.
+        basic_stats: Basic statistics from preview.
+    """
+
+    downsampled_data: NDArray[np.float64]
+    downsample_factor: int
+    original_length: int
+    preview_length: int
+    sample_rate: float
+    time_vector: NDArray[np.float64]
+    basic_stats: dict[str, float]
+
+
+@dataclass
+class ROISelection:
+    """Region of interest selection.
+
+
+    Attributes:
+        start_time: Start time in seconds.
+        end_time: End time in seconds.
+        start_index: Start sample index in original signal.
+        end_index: End sample index in original signal.
+        duration: Duration in seconds.
+        num_samples: Number of samples in ROI.
+    """
+
+    start_time: float
+    end_time: float
+    start_index: int
+    end_index: int
+    duration: float
+    num_samples: int
+
+
+def create_preview(
+    trace: WaveformTrace,
+    *,
+    downsample_factor: int | None = None,
+    max_samples: int = 10_000,
+    apply_antialiasing: bool = True,
+) -> PreviewResult:
+    """Create downsampled preview of waveform for quick inspection.
+
+
+    Args:
+        trace: Input waveform trace.
+        downsample_factor: Downsampling factor (auto-computed if None).
+        max_samples: Target maximum samples in preview.
+        apply_antialiasing: Apply anti-aliasing lowpass filter before decimation.
+
+    Returns:
+        PreviewResult with downsampled data and metadata.
+
+    Example:
+        >>> preview = create_preview(large_trace, downsample_factor=10)
+        >>> print(f"Preview: {preview.preview_length} samples (factor {preview.downsample_factor}x)")
+        >>> # Inspect preview.basic_stats
+    """
+    from scipy import signal as sp_signal
+
+    data = trace.data
+    original_length = len(data)
+    sample_rate = trace.metadata.sample_rate
+
+    # Auto-compute downsample factor
+    if downsample_factor is None:
+        downsample_factor = max(1, original_length // max_samples)
+        # Round to nearest power of 2 for efficiency
+        downsample_factor = 2 ** int(np.ceil(np.log2(downsample_factor)))
+        downsample_factor = max(1, downsample_factor)
+
+    # Apply anti-aliasing filter if requested
+    if apply_antialiasing and downsample_factor > 1:
+        # Lowpass filter at Nyquist frequency of downsampled rate
+        nyquist_freq = (sample_rate / downsample_factor) / 2
+        sos = sp_signal.butter(8, nyquist_freq, btype="low", fs=sample_rate, output="sos")
+        filtered = sp_signal.sosfilt(sos, data)
+        downsampled = filtered[::downsample_factor]
+    else:
+        # Simple decimation without filtering
+        downsampled = data[::downsample_factor]
+
+    preview_length = len(downsampled)
+    preview_sample_rate = sample_rate / downsample_factor
+
+    # Create time vector
+    time_vector = np.arange(preview_length) / preview_sample_rate
+
+    # Compute basic statistics
+    basic_stats = {
+        "mean": float(np.mean(downsampled)),
+        "std": float(np.std(downsampled)),
+        "min": float(np.min(downsampled)),
+        "max": float(np.max(downsampled)),
+        "rms": float(np.sqrt(np.mean(downsampled**2))),
+        "peak_to_peak": float(np.ptp(downsampled)),
+    }
+
+    return PreviewResult(
+        downsampled_data=downsampled,
+        downsample_factor=downsample_factor,
+        original_length=original_length,
+        preview_length=preview_length,
+        sample_rate=preview_sample_rate,
+        time_vector=time_vector,
+        basic_stats=basic_stats,
+    )
+
+
+def select_roi(
+    trace: WaveformTrace,
+    start_time: float,
+    end_time: float,
+) -> ROISelection:
+    """Create ROI selection from time range.
+
+
+    Args:
+        trace: Input waveform trace.
+        start_time: Start time in seconds.
+        end_time: End time in seconds.
+
+    Returns:
+        ROISelection with sample indices and metadata.
+
+    Raises:
+        ValueError: If time range is invalid.
+
+    Example:
+        >>> roi = select_roi(trace, start_time=0.001, end_time=0.002)
+        >>> print(f"ROI: {roi.num_samples} samples ({roi.duration*1e6:.1f} µs)")
+    """
+    sample_rate = trace.metadata.sample_rate
+    total_length = len(trace.data)
+    total_duration = total_length / sample_rate
+
+    # Validate time range
+    if start_time < 0 or end_time > total_duration:
+        raise ValueError(
+            f"Time range [{start_time}, {end_time}] outside signal duration [0, {total_duration}]"
+        )
+    if start_time >= end_time:
+        raise ValueError(f"start_time ({start_time}) must be < end_time ({end_time})")
+
+    # Convert to sample indices
+    start_index = int(start_time * sample_rate)
+    end_index = int(end_time * sample_rate)
+
+    # Clamp to valid range
+    start_index = max(0, min(start_index, total_length - 1))
+    end_index = max(start_index + 1, min(end_index, total_length))
+
+    duration = end_time - start_time
+    num_samples = end_index - start_index
+
+    return ROISelection(
+        start_time=start_time,
+        end_time=end_time,
+        start_index=start_index,
+        end_index=end_index,
+        duration=duration,
+        num_samples=num_samples,
+    )
+
+
+def analyze_roi(
+    trace: WaveformTrace,
+    roi: ROISelection,
+    *,
+    analysis_func: Callable[[WaveformTrace], Any],
+    **analysis_kwargs: Any,
+) -> Any:
+    """Analyze region of interest with high resolution.
+
+
+    Args:
+        trace: Input waveform trace.
+        roi: ROI selection.
+        analysis_func: Analysis function to apply to ROI.
+        **analysis_kwargs: Additional arguments for analysis function.
+
+    Returns:
+        Result of analysis function on ROI.
+
+    Example:
+        >>> from oscura.analyzers.waveform.spectral import fft
+        >>> roi = select_roi(trace, 0.001, 0.002)
+        >>> freq, mag = analyze_roi(trace, roi, analysis_func=fft, window='hann')
+    """
+    from oscura.core.types import TraceMetadata, WaveformTrace
+
+    # Extract ROI data
+    roi_data = trace.data[roi.start_index : roi.end_index]
+
+    # Create new trace for ROI with only standard metadata fields
+    roi_trace = WaveformTrace(
+        data=roi_data,
+        metadata=TraceMetadata(
+            sample_rate=trace.metadata.sample_rate,
+            vertical_scale=trace.metadata.vertical_scale,
+            vertical_offset=trace.metadata.vertical_offset,
+            acquisition_time=trace.metadata.acquisition_time,
+            trigger_info=trace.metadata.trigger_info,
+            source_file=trace.metadata.source_file,
+            channel_name=getattr(trace.metadata, "channel_name", None),
+        ),
+    )
+
+    # Apply analysis function
+    return analysis_func(roi_trace, **analysis_kwargs)
+
+
+def progressive_analysis(
+    trace: WaveformTrace,
+    *,
+    analysis_func: Callable[[WaveformTrace], Any],
+    downsample_factor: int = 10,
+    roi_selector: Callable[[PreviewResult], ROISelection] | None = None,
+    **analysis_kwargs: Any,
+) -> tuple[PreviewResult, Any]:
+    """Perform progressive multi-pass analysis.
+
+
+    Workflow:
+    1. Create downsampled preview
+    2. User/algorithm selects ROI from preview
+    3. Perform high-resolution analysis on ROI only
+
+    Args:
+        trace: Input waveform trace.
+        analysis_func: Analysis function to apply.
+        downsample_factor: Downsampling factor for preview.
+        roi_selector: Function to select ROI from preview (if None, analyzes full trace).
+        **analysis_kwargs: Additional arguments for analysis function.
+
+    Returns:
+        Tuple of (preview_result, analysis_result).
+
+    Example:
+        >>> def select_peak_region(preview):
+        ...     # Find region with highest amplitude
+        ...     peak_idx = np.argmax(np.abs(preview.downsampled_data))
+        ...     start_time = max(0, (peak_idx - 500) / preview.sample_rate)
+        ...     end_time = min(preview.preview_length / preview.sample_rate,
+        ...                    (peak_idx + 500) / preview.sample_rate)
+        ...     return select_roi(trace, start_time, end_time)
+        >>>
+        >>> from oscura.analyzers.waveform.spectral import fft
+        >>> preview, result = progressive_analysis(
+        ...     trace,
+        ...     analysis_func=fft,
+        ...     downsample_factor=10,
+        ...     roi_selector=select_peak_region
+        ... )
+    """
+    # Pass 1: Create preview
+    preview = create_preview(trace, downsample_factor=downsample_factor)
+
+    # Pass 2: Select ROI
+    if roi_selector is not None:
+        roi = roi_selector(preview)
+        # Pass 3: Analyze ROI
+        result = analyze_roi(trace, roi, analysis_func=analysis_func, **analysis_kwargs)
+    else:
+        # No ROI selection, analyze full trace
+        result = analysis_func(trace, **analysis_kwargs)
+
+    return preview, result
+
+
+def estimate_optimal_preview_factor(
+    trace_length: int,
+    *,
+    target_memory: int = 100_000_000,  # 100 MB
+    bytes_per_sample: int = 8,
+) -> int:
+    """Estimate optimal downsampling factor for preview.
+
+    Args:
+        trace_length: Number of samples in original trace.
+        target_memory: Target memory for preview (bytes).
+        bytes_per_sample: Bytes per sample (8 for float64).
+
+    Returns:
+        Recommended downsampling factor.
+
+    Example:
+        >>> factor = estimate_optimal_preview_factor(1_000_000_000)  # 1B samples
+        >>> print(f"Downsample by {factor}x for preview")
+    """
+    # Calculate required factor to fit in target memory
+    current_memory = trace_length * bytes_per_sample
+    factor = max(1, int(np.ceil(current_memory / target_memory)))
+
+    # Round to power of 2
+    factor = 2 ** int(np.ceil(np.log2(factor)))
+
+    return factor  # type: ignore[no-any-return]
+
+
+__all__ = [
+    "PreviewResult",
+    "ROISelection",
+    "analyze_roi",
+    "create_preview",
+    "estimate_optimal_preview_factor",
+    "progressive_analysis",
+    "select_roi",
+]

oscura/utils/windowing.py

@@ -0,0 +1,362 @@
+"""Window function support for spectral analysis.
+
+This module provides standard window functions for FFT and spectral
+analysis, implementing the requirements for windowed spectral estimation.
+
+
+Example:
+    >>> from oscura.utils.windowing import get_window, WINDOW_FUNCTIONS
+    >>> window = get_window("hann", 1024)
+    >>> print(f"Available windows: {list(WINDOW_FUNCTIONS.keys())}")
+
+References:
+    Harris, F. J. (1978). "On the use of windows for harmonic analysis
+    with the discrete Fourier transform." Proceedings of the IEEE, 66(1).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+# Type alias for window function (using string annotation for TYPE_CHECKING compatibility)
+WindowFunction = Callable[[int], "NDArray[np.float64]"]
+
+
+def rectangular(n: int) -> NDArray[np.float64]:
+    """Rectangular (boxcar) window.
+
+    No tapering applied - all samples weighted equally.
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients (all ones).
+
+    Example:
+        >>> w = rectangular(64)
+        >>> assert np.all(w == 1.0)
+    """
+    return np.ones(n, dtype=np.float64)
+
+
+def hann(n: int) -> NDArray[np.float64]:
+    """Hann (raised cosine) window.
+
+    Also known as Hanning window. Provides good frequency resolution
+    with moderate sidelobe suppression.
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = hann(64)
+        >>> assert w[0] == w[-1]  # Symmetric
+
+    References:
+        IEEE Std 1057-2017 Section 4.4.2
+    """
+    return np.hanning(n).astype(np.float64)
+
+
+def hamming(n: int) -> NDArray[np.float64]:
+    """Hamming window.
+
+    Similar to Hann but with reduced first sidelobe at cost of
+    slower rolloff.
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = hamming(64)
+        >>> assert w[32] > w[0]  # Peak in center
+    """
+    return np.hamming(n).astype(np.float64)
+
+
+def blackman(n: int) -> NDArray[np.float64]:
+    """Blackman window.
+
+    Three-term cosine window with excellent sidelobe suppression
+    (-58 dB first sidelobe).
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = blackman(64)
+        >>> assert w[32] > w[0]
+    """
+    return np.blackman(n).astype(np.float64)
+
+
+def kaiser(n: int, beta: float = 8.6) -> NDArray[np.float64]:
+    """Kaiser window with configurable shape parameter.
+
+    Provides adjustable tradeoff between main lobe width and
+    sidelobe attenuation.
+
+    Args:
+        n: Window length in samples.
+        beta: Shape parameter (default 8.6 for ~60 dB sidelobe attenuation).
+            - beta=0: Rectangular
+            - beta=5: ~30 dB sidelobe attenuation
+            - beta=8.6: ~60 dB sidelobe attenuation
+            - beta=14: ~90 dB sidelobe attenuation
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = kaiser(64, beta=10)
+        >>> assert 0 < w[0] < w[32]
+    """
+    return np.kaiser(n, beta).astype(np.float64)
+
+
+def flattop(n: int) -> NDArray[np.float64]:
+    """Flat-top window for accurate amplitude measurements.
+
+    Provides minimal scalloping loss (<0.01 dB) at cost of
+    wider main lobe. Best for amplitude accuracy when frequency
+    resolution is not critical.
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = flattop(64)
+        >>> # Flat-top has characteristic near-zero values at edges
+
+    References:
+        D'Antona, G. & Ferrero, A. (2006). "Digital Signal Processing
+        for Measurement Systems."
+    """
+    # Flat-top coefficients per HP/Agilent standard
+    a0 = 0.21557895
+    a1 = 0.41663158
+    a2 = 0.277263158
+    a3 = 0.083578947
+    a4 = 0.006947368
+
+    k = np.arange(n, dtype=np.float64)
+    w = (
+        a0
+        - a1 * np.cos(2 * np.pi * k / (n - 1))
+        + a2 * np.cos(4 * np.pi * k / (n - 1))
+        - a3 * np.cos(6 * np.pi * k / (n - 1))
+        + a4 * np.cos(8 * np.pi * k / (n - 1))
+    )
+    return np.asarray(w, dtype=np.float64)
+
+
+def bartlett(n: int) -> NDArray[np.float64]:
+    """Bartlett (triangular) window.
+
+    Linear taper from zero at edges to maximum at center.
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = bartlett(64)
+        >>> assert w[32] == 1.0  # Maximum at center
+    """
+    return np.bartlett(n).astype(np.float64)
+
+
+def blackman_harris(n: int) -> NDArray[np.float64]:
+    """Blackman-Harris window (4-term).
+
+    Four-term cosine window with excellent sidelobe suppression
+    (-92 dB first sidelobe).
+
+    Args:
+        n: Window length in samples.
+
+    Returns:
+        Window coefficients.
+
+    Example:
+        >>> w = blackman_harris(64)
+        >>> assert w[32] > w[0]
+    """
+    a0 = 0.35875
+    a1 = 0.48829
+    a2 = 0.14128
+    a3 = 0.01168
+
+    k = np.arange(n, dtype=np.float64)
+    w = (
+        a0
+        - a1 * np.cos(2 * np.pi * k / (n - 1))
+        + a2 * np.cos(4 * np.pi * k / (n - 1))
+        - a3 * np.cos(6 * np.pi * k / (n - 1))
+    )
+    return np.asarray(w, dtype=np.float64)
+
+
+# Window function registry
+WINDOW_FUNCTIONS: dict[str, WindowFunction] = {
+    "rectangular": rectangular,
+    "boxcar": rectangular,
+    "rect": rectangular,
+    "hann": hann,
+    "hanning": hann,
+    "hamming": hamming,
+    "blackman": blackman,
+    "kaiser": lambda n: kaiser(n, beta=8.6),
+    "flattop": flattop,
+    "flat_top": flattop,
+    "bartlett": bartlett,
+    "triangular": bartlett,
+    "blackman_harris": blackman_harris,
+    "blackmanharris": blackman_harris,
+}
+
+
+# Type for window names
+WindowName = Literal[
+    "rectangular",
+    "boxcar",
+    "rect",
+    "hann",
+    "hanning",
+    "hamming",
+    "blackman",
+    "kaiser",
+    "flattop",
+    "flat_top",
+    "bartlett",
+    "triangular",
+    "blackman_harris",
+    "blackmanharris",
+]
+
+
+def get_window(
+    window: str | WindowFunction | NDArray[np.floating[Any]],
+    n: int,
+    *,
+    beta: float | None = None,
+) -> NDArray[np.float64]:
+    """Get window coefficients by name or callable.
+
+    Args:
+        window: Window specification. Can be:
+            - A string name from WINDOW_FUNCTIONS
+            - A callable that takes length and returns coefficients
+            - A pre-computed array of coefficients
+        n: Window length in samples.
+        beta: Optional beta parameter for Kaiser window.
+
+    Returns:
+        Window coefficients array of length n.
+
+    Raises:
+        ValueError: If window name is unknown.
+
+    Example:
+        >>> w = get_window("hann", 1024)
+        >>> w = get_window("kaiser", 1024, beta=10)
+        >>> w = get_window(np.hamming, 1024)
+    """
+    if isinstance(window, np.ndarray):
+        if len(window) != n:
+            raise ValueError(f"Window array length {len(window)} != requested {n}")
+        return window.astype(np.float64)
+
+    if callable(window) and not isinstance(window, str):
+        return np.asarray(window(n), dtype=np.float64)
+
+    window_name = window.lower()
+
+    if window_name == "kaiser" and beta is not None:
+        return kaiser(n, beta)
+
+    if window_name not in WINDOW_FUNCTIONS:
+        available = ", ".join(sorted(set(WINDOW_FUNCTIONS.keys())))
+        raise ValueError(f"Unknown window: {window}. Available: {available}")
+
+    return WINDOW_FUNCTIONS[window_name](n)
+
+
+def window_properties(window: str | NDArray[np.floating[Any]], n: int = 1024) -> dict[str, Any]:
+    """Compute window properties for analysis.
+
+    Args:
+        window: Window name or coefficients.
+        n: Window length for named windows.
+
+    Returns:
+        Dictionary with window properties:
+            - coherent_gain: Sum of window / length
+            - noise_bandwidth: Normalized equivalent noise bandwidth
+            - scalloping_loss: Peak amplitude error in dB
+
+    Example:
+        >>> props = window_properties("hann")
+        >>> print(f"ENBW: {props['noise_bandwidth']:.3f}")
+    """
+    if isinstance(window, str):
+        w = get_window(window, n)
+    else:
+        w = np.asarray(window, dtype=np.float64)
+        n = len(w)
+
+    # Coherent gain (DC gain)
+    coherent_gain = np.sum(w) / n
+
+    # Noise equivalent bandwidth
+    # ENBW = N * sum(w^2) / (sum(w))^2
+    noise_bandwidth = n * np.sum(w**2) / np.sum(w) ** 2
+
+    # Scalloping loss (worst-case amplitude error at bin edge)
+    # Approximate by evaluating window at half-bin offset
+    k = np.arange(n)
+    w_shifted = w * np.exp(2j * np.pi * 0.5 * k / n)
+    scalloping_loss = 20 * np.log10(np.abs(np.sum(w_shifted)) / np.abs(np.sum(w)))
+
+    return {
+        "coherent_gain": float(coherent_gain),
+        "noise_bandwidth": float(noise_bandwidth),
+        "scalloping_loss": float(scalloping_loss),
+        "length": n,
+    }
+
+
+__all__ = [
+    "WINDOW_FUNCTIONS",
+    "bartlett",
+    "blackman",
+    "blackman_harris",
+    "flattop",
+    "get_window",
+    "hamming",
+    "hann",
+    "kaiser",
+    "rectangular",
+    "window_properties",
+]