oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/{streaming → utils/streaming}/chunked.py

@@ -8,12 +8,12 @@ accumulator pattern for rolling statistics.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 from scipy import signal
 
-from ..core.types import WaveformTrace
+from oscura.core.types import WaveformTrace
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Generator
@@ -69,57 +69,99 @@ def load_trace_chunks(
     References:
         API-003: Streaming/Generator API for Large Files
     """
-    file_path = Path(file_path)
+    full_trace = _load_full_trace(file_path, loader)
+    chunk_samples, num_chunks = _compute_chunk_parameters(len(full_trace.data), chunk_size, overlap)
+    yield from _generate_chunks(full_trace, chunk_samples, overlap, num_chunks, progress_callback)
+
+
+def _load_full_trace(
+    file_path: str | Path, loader: Callable[[str | Path], WaveformTrace] | None
+) -> WaveformTrace:
+    """Load full trace metadata.
+
+    Args:
+        file_path: Path to trace file.
+        loader: Optional custom loader.
+
+    Returns:
+        WaveformTrace object.
 
-    # Import loader here to avoid circular dependency
-    from ..loaders import load
+    Raises:
+        ValueError: If failed to load trace metadata.
+        TypeError: If loaded object is not WaveformTrace.
+    """
+    from oscura.loaders import load
 
-    # Use provided loader or default
+    file_path = Path(file_path)
     load_func = loader if loader is not None else load
 
-    # Load full trace metadata to get total size
-    # For memory-mapped files, this doesn't load data
     try:
-        full_trace = load_func(file_path)
+        loaded_trace = load_func(file_path)
     except Exception as e:
         raise ValueError(f"Failed to load trace metadata: {e}") from e
 
-    total_samples = len(full_trace.data)  # type: ignore[union-attr]
-    chunk_samples = int(chunk_size) if chunk_size < 1e6 else int(chunk_size / 8)
+    if not isinstance(loaded_trace, WaveformTrace):
+        raise TypeError(f"Expected WaveformTrace, got {type(loaded_trace)}")
+
+    return loaded_trace
+
 
-    # Calculate number of chunks
+def _compute_chunk_parameters(
+    total_samples: int, chunk_size: int | float, overlap: int
+) -> tuple[int, int]:
+    """Compute chunk size and number of chunks.
+
+    Args:
+        total_samples: Total number of samples.
+        chunk_size: Size specification.
+        overlap: Overlap samples.
+
+    Returns:
+        Tuple of (chunk_samples, num_chunks).
+    """
+    chunk_samples = int(chunk_size) if chunk_size < 1e6 else int(chunk_size / 8)
     num_chunks = (total_samples - overlap) // (chunk_samples - overlap)
     if (total_samples - overlap) % (chunk_samples - overlap) != 0:
         num_chunks += 1
+    return chunk_samples, num_chunks
+
+
+def _generate_chunks(
+    full_trace: WaveformTrace,
+    chunk_samples: int,
+    overlap: int,
+    num_chunks: int,
+    progress_callback: Callable[[int, int], None] | None,
+) -> Generator[WaveformTrace, None, None]:
+    """Generate trace chunks.
+
+    Args:
+        full_trace: Full trace object.
+        chunk_samples: Samples per chunk.
+        overlap: Overlap samples.
+        num_chunks: Total number of chunks.
+        progress_callback: Optional progress callback.
 
-    # Yield chunks
+    Yields:
+        WaveformTrace chunks.
+    """
+    total_samples = len(full_trace.data)
     chunk_num = 0
     start_idx = 0
 
     while start_idx < total_samples:
         end_idx = min(start_idx + chunk_samples, total_samples)
+        chunk_data = full_trace.data[start_idx:end_idx]
+        chunk_trace = WaveformTrace(data=chunk_data, metadata=full_trace.metadata)
 
-        # Extract chunk
-        chunk_data = full_trace.data[start_idx:end_idx]  # type: ignore[union-attr]
-
-        # Create chunk trace with same metadata
-        # Cast needed for mypy: slicing a floating array returns a floating array
-        chunk_trace = WaveformTrace(
-            data=cast("NDArray[np.floating[Any]]", chunk_data),
-            metadata=full_trace.metadata,
-        )
-
-        # Call progress callback if provided
         if progress_callback is not None:
             progress_callback(chunk_num, num_chunks)
 
         yield chunk_trace
 
-        # Move to next chunk, accounting for overlap
         start_idx = end_idx - overlap
         chunk_num += 1
 
-        # Break if we've reached the end
         if end_idx >= total_samples:
             break
 
@@ -347,6 +389,121 @@ class StreamingAnalyzer:
         self._hist_edges = None
 
 
+def _prepare_spectrogram_params(
+    n: int, nperseg: int, noverlap: int | None, overlap: int, chunk_size: int
+) -> tuple[int, int]:
+    """Prepare spectrogram parameters and validate inputs.
+
+    Args:
+        n: Signal length.
+        nperseg: Segment length for STFT.
+        noverlap: Overlap between STFT segments.
+        overlap: Overlap between chunks.
+        chunk_size: Chunk size.
+
+    Returns:
+        Tuple of (noverlap, overlap).
+    """
+    if noverlap is None:
+        noverlap = nperseg // 2
+
+    # Auto-adjust overlap if not specified to ensure continuity
+    if overlap == 0:
+        overlap = 2 * nperseg
+
+    return noverlap, overlap
+
+
+def _compute_single_chunk_spectrogram(
+    data: NDArray[np.float64],
+    sample_rate: float,
+    window: str,
+    nperseg: int,
+    noverlap: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Compute spectrogram for single chunk that fits in memory.
+
+    Args:
+        data: Input signal.
+        sample_rate: Sample rate in Hz.
+        window: Window function name.
+        nperseg: Segment length for STFT.
+        noverlap: Overlap between STFT segments.
+
+    Returns:
+        (times, frequencies, Sxx_db) tuple.
+    """
+    freq, times, Sxx = signal.spectrogram(
+        data,
+        fs=sample_rate,
+        window=window,
+        nperseg=nperseg,
+        noverlap=noverlap,
+        scaling="spectrum",
+    )
+    Sxx = np.maximum(Sxx, 1e-20)
+    Sxx_db = 10 * np.log10(Sxx)
+    return times, freq, Sxx_db
+
+
+def _process_spectrogram_chunk(
+    data: NDArray[np.float64],
+    chunk_start: int,
+    chunk_end: int,
+    overlap: int,
+    n: int,
+    sample_rate: float,
+    window: str,
+    nperseg: int,
+    noverlap: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Process single chunk of spectrogram.
+
+    Args:
+        data: Full signal array.
+        chunk_start: Chunk start index.
+        chunk_end: Chunk end index.
+        overlap: Overlap samples.
+        n: Total signal length.
+        sample_rate: Sample rate in Hz.
+        window: Window function.
+        nperseg: Segment length.
+        noverlap: Overlap between segments.
+
+    Returns:
+        (freq, times_adjusted, Sxx_chunk) for this chunk.
+    """
+    extended_start = max(0, chunk_start - overlap)
+    extended_end = min(n, chunk_end + overlap)
+
+    chunk_data = data[extended_start:extended_end]
+
+    freq, times_chunk, Sxx_chunk = signal.spectrogram(
+        chunk_data,
+        fs=sample_rate,
+        window=window,
+        nperseg=nperseg,
+        noverlap=noverlap,
+        scaling="spectrum",
+    )
+
+    # Adjust time axis and trim overlap
+    time_offset = extended_start / sample_rate
+    times_chunk_adjusted = times_chunk + time_offset
+
+    valid_time_start = chunk_start / sample_rate
+    valid_time_end = chunk_end / sample_rate
+
+    valid_mask = (times_chunk_adjusted >= valid_time_start) & (
+        times_chunk_adjusted < valid_time_end
+    )
+
+    Sxx_chunk = Sxx_chunk[:, valid_mask]
+    times_chunk_adjusted = times_chunk_adjusted[valid_mask]
+
+    return freq, times_chunk_adjusted, Sxx_chunk
+
+
 def chunked_spectrogram(
     data: NDArray[np.float64],
     sample_rate: float,
@@ -394,31 +551,14 @@ def chunked_spectrogram(
     """
     n = len(data)
 
-    # Handle empty input
     if n == 0:
         return np.array([]), np.array([]), np.array([]).reshape(0, 0)
 
-    if noverlap is None:
-        noverlap = nperseg // 2
-
-    # Auto-adjust overlap if not specified to ensure continuity
-    if overlap == 0:
-        overlap = 2 * nperseg
+    noverlap, overlap = _prepare_spectrogram_params(n, nperseg, noverlap, overlap, chunk_size)
 
-    # If data fits in one chunk, use scipy directly
+    # Single chunk optimization
     if n <= chunk_size:
-        freq, times, Sxx = signal.spectrogram(
-            data,
-            fs=sample_rate,
-            window=window,
-            nperseg=nperseg,
-            noverlap=noverlap,
-            scaling="spectrum",
-        )
-        # Convert to dB
-        Sxx = np.maximum(Sxx, 1e-20)
-        Sxx_db = 10 * np.log10(Sxx)
-        return times, freq, Sxx_db
+        return _compute_single_chunk_spectrogram(data, sample_rate, window, nperseg, noverlap)
 
     # Process chunks
     chunks_stft = []
@@ -426,61 +566,133 @@ def chunked_spectrogram(
     chunk_start = 0
 
     while chunk_start < n:
-        # Determine chunk boundaries with overlap
         chunk_end = min(chunk_start + chunk_size, n)
 
-        # Extract chunk with overlap extension on both sides
-        extended_start = max(0, chunk_start - overlap)
-        extended_end = min(n, chunk_end + overlap)
-
-        chunk_data = data[extended_start:extended_end]
-
-        # Compute spectrogram for chunk
-        freq, times_chunk, Sxx_chunk = signal.spectrogram(
-            chunk_data,
-            fs=sample_rate,
-            window=window,
-            nperseg=nperseg,
-            noverlap=noverlap,
-            scaling="spectrum",
-        )
-
-        # Adjust time axis for chunk position
-        time_offset = extended_start / sample_rate
-        times_chunk_adjusted = times_chunk + time_offset
-
-        # Trim overlap regions to avoid duplication
-        valid_time_start = chunk_start / sample_rate
-        valid_time_end = chunk_end / sample_rate
-
-        valid_mask = (times_chunk_adjusted >= valid_time_start) & (
-            times_chunk_adjusted < valid_time_end
+        freq, times_adjusted, Sxx_chunk = _process_spectrogram_chunk(
+            data, chunk_start, chunk_end, overlap, n, sample_rate, window, nperseg, noverlap
         )
 
-        if np.any(valid_mask):
-            Sxx_chunk = Sxx_chunk[:, valid_mask]
-            times_chunk_adjusted = times_chunk_adjusted[valid_mask]
-
+        if Sxx_chunk.shape[1] > 0:
             chunks_stft.append(Sxx_chunk)
-            chunks_times.append(times_chunk_adjusted)
+            chunks_times.append(times_adjusted)
 
-        # Move to next chunk
         chunk_start = chunk_end
 
-    # Concatenate all chunks
     if len(chunks_stft) == 0:
         raise ValueError("No valid chunks produced")
 
     Sxx = np.concatenate(chunks_stft, axis=1)
     times = np.concatenate(chunks_times)
 
-    # Convert to dB
     Sxx = np.maximum(Sxx, 1e-20)
-    Sxx_db = 10 * np.log10(Sxx)
+    Sxx_db: NDArray[np.float64] = np.asarray(10 * np.log10(Sxx), dtype=np.float64)
 
     return times, freq, Sxx_db
 
 
+def _compute_single_chunk_fft(
+    data: NDArray[np.float64],
+    sample_rate: float,
+    window: str,
+    nfft: int | None,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Compute FFT for signal that fits in single chunk.
+
+    Args:
+        data: Input signal.
+        sample_rate: Sample rate in Hz.
+        window: Window function name.
+        nfft: FFT length.
+
+    Returns:
+        Tuple of (frequencies, magnitude_db).
+    """
+    from oscura.utils.windowing import get_window
+
+    n = len(data)
+    nfft = nfft if nfft is not None else int(2 ** np.ceil(np.log2(n)))
+
+    w = get_window(window, n)
+    data_windowed = data * w
+    spectrum = np.fft.rfft(data_windowed, n=nfft)
+    freq = np.fft.rfftfreq(nfft, d=1.0 / sample_rate)
+
+    window_gain = np.sum(w) / n
+    magnitude = np.abs(spectrum) / (n * window_gain)
+    magnitude = np.maximum(magnitude, 1e-20)
+    magnitude_db = 20 * np.log10(magnitude)
+
+    return freq, magnitude_db
+
+
+def _setup_chunked_fft_params(
+    chunk_size: int, overlap: float, nfft_in: int | None, window: str, sample_rate: float
+) -> tuple[int, int, NDArray[np.float64], float, NDArray[np.float64]]:
+    """Setup parameters for chunked FFT processing.
+
+    Args:
+        chunk_size: Chunk size.
+        overlap: Overlap percentage.
+        nfft: FFT length.
+        window: Window function name.
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        Tuple of (hop, nfft, w, window_gain, freq).
+    """
+    from oscura.utils.windowing import get_window
+
+    overlap_samples = int(chunk_size * overlap / 100.0)
+    hop = chunk_size - overlap_samples
+    nfft = nfft_in if nfft_in is not None else int(2 ** np.ceil(np.log2(chunk_size)))
+
+    w = get_window(window, chunk_size)
+    window_gain_raw = np.sum(w) / chunk_size
+    window_gain: float = float(window_gain_raw)
+    freq: NDArray[np.float64] = np.asarray(
+        np.fft.rfftfreq(nfft, d=1.0 / sample_rate), dtype=np.float64
+    )
+
+    return hop, nfft, w, window_gain, freq
+
+
+def _process_fft_segment(
+    data: NDArray[np.float64],
+    start: int,
+    chunk_size: int,
+    n: int,
+    w: NDArray[np.float64],
+    window_gain: float,
+    nfft: int,
+) -> NDArray[np.float64]:
+    """Process single FFT segment.
+
+    Args:
+        data: Input signal.
+        start: Segment start index.
+        chunk_size: Chunk size.
+        n: Total signal length.
+        w: Window function.
+        window_gain: Window gain.
+        nfft: FFT length.
+
+    Returns:
+        Magnitude spectrum for segment.
+    """
+    end = min(start + chunk_size, n)
+
+    if end - start < chunk_size:
+        segment = np.zeros(chunk_size)
+        segment[: end - start] = data[start:end]
+    else:
+        segment = data[start:end]
+
+    segment = segment - np.mean(segment)
+    segment_windowed = segment * w
+    spectrum = np.fft.rfft(segment_windowed, n=nfft)
+    return np.abs(spectrum) / (chunk_size * window_gain)
+
+
 def chunked_fft(
     data: NDArray[np.float64],
     sample_rate: float,
@@ -519,84 +731,31 @@ def chunked_fft(
         MEM-006: Chunked FFT requirement
         Welch's method for spectral estimation
     """
-    from ..utils.windowing import get_window
-
     n = len(data)
 
-    # Handle empty input
+    # Setup: handle empty or single-chunk signals
     if n == 0:
         return np.array([]), np.array([])
 
-    # If data fits in one chunk, compute single FFT
     if n <= chunk_size:
-        if nfft is None:
-            nfft = int(2 ** np.ceil(np.log2(n)))
-
-        # Apply window
-        w = get_window(window, n)
-        data_windowed = data * w
-
-        # Compute FFT
-        spectrum = np.fft.rfft(data_windowed, n=nfft)
-
-        # Frequency axis
-        freq = np.fft.rfftfreq(nfft, d=1.0 / sample_rate)
-
-        # Magnitude in dB (normalized by window gain)
-        window_gain = np.sum(w) / n
-        magnitude = np.abs(spectrum) / (n * window_gain)
-        magnitude = np.maximum(magnitude, 1e-20)
-        magnitude_db = 20 * np.log10(magnitude)
+        return _compute_single_chunk_fft(data, sample_rate, window, nfft)
 
-        return freq, magnitude_db
+    # Processing: setup parameters and process segments
+    hop, nfft, w, window_gain, freq = _setup_chunked_fft_params(
+        chunk_size, overlap, nfft, window, sample_rate
+    )
 
-    # Calculate overlap
     overlap_samples = int(chunk_size * overlap / 100.0)
-    hop = chunk_size - overlap_samples
-
-    # Determine number of segments
     num_segments = max(1, (n - overlap_samples) // hop)
-
-    if nfft is None:
-        nfft = int(2 ** np.ceil(np.log2(chunk_size)))
-
-    # Prepare window
-    w = get_window(window, chunk_size)
-    window_gain = np.sum(w) / chunk_size
-
-    # Accumulate magnitude spectra
-    freq = np.fft.rfftfreq(nfft, d=1.0 / sample_rate)
     magnitude_sum = np.zeros(len(freq))
 
     for i in range(num_segments):
         start = i * hop
-        end = min(start + chunk_size, n)
-
-        # Extract segment
-        if end - start < chunk_size:
-            # Last segment: pad with zeros
-            segment = np.zeros(chunk_size)
-            segment[: end - start] = data[start:end]
-        else:
-            segment = data[start:end]
-
-        # Detrend (remove mean)
-        segment = segment - np.mean(segment)
-
-        # Window
-        segment_windowed = segment * w
-
-        # FFT
-        spectrum = np.fft.rfft(segment_windowed, n=nfft)
-
-        # Accumulate magnitude
-        magnitude = np.abs(spectrum) / (chunk_size * window_gain)
+        magnitude = _process_fft_segment(data, start, chunk_size, n, w, window_gain, nfft)
         magnitude_sum += magnitude
 
-    # Average
+    # Result building: average and convert to dB
     magnitude_avg = magnitude_sum / num_segments
-
-    # Convert to dB
     magnitude_avg = np.maximum(magnitude_avg, 1e-20)
     magnitude_db = 20 * np.log10(magnitude_avg)
 

oscura/{streaming → utils/streaming}/progressive.py

@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
-from ..quality.scoring import assess_data_quality
+from oscura.validation.quality.scoring import assess_data_quality
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray

oscura/{streaming → utils/streaming}/realtime.py

@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
-from ..core.types import TraceMetadata, WaveformTrace
+from oscura.core.types import TraceMetadata, WaveformTrace
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -335,7 +335,8 @@ class SimulatedSource(RealtimeSource):
         ) % (2 * np.pi)
 
         # Cast to the expected return type
-        return signal.astype(np.float64)  # type: ignore[return-value,no-any-return]
+        result: NDArray[np.floating[Any]] = signal.astype(np.float64)
+        return result
 
     def start(self) -> None:
         """Start acquisition."""

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

@@ -5,35 +5,35 @@ triggering, pattern triggering, pulse width triggering, glitch detection,
 runt pulse detection, and window/zone triggering.
 
 Example:
-    >>> from oscura.triggering import EdgeTrigger, find_triggers
+    >>> from oscura.utils.triggering import EdgeTrigger, find_triggers
     >>> trigger = EdgeTrigger(level=1.5, edge="rising")
     >>> events = trigger.find_events(trace)
     >>> # Or use convenience function
     >>> events = find_triggers(trace, "edge", level=1.5, edge="rising")
 """
 
-from oscura.triggering.base import (
+from oscura.utils.triggering.base import (
     Trigger,
     TriggerEvent,
     find_triggers,
 )
-from oscura.triggering.edge import (
+from oscura.utils.triggering.edge import (
     EdgeTrigger,
     find_all_edges,
     find_falling_edges,
     find_rising_edges,
 )
-from oscura.triggering.pattern import (
+from oscura.utils.triggering.pattern import (
     PatternTrigger,
     find_pattern,
 )
-from oscura.triggering.pulse import (
+from oscura.utils.triggering.pulse import (
     PulseWidthTrigger,
     find_glitches,
     find_pulses,
     find_runt_pulses,
 )
-from oscura.triggering.window import (
+from oscura.utils.triggering.window import (
     WindowTrigger,
     ZoneTrigger,
     check_limits,

oscura/{triggering → utils/triggering}/base.py

@@ -134,9 +134,9 @@ def find_triggers(
         >>> events = find_triggers(trace, "pulse_width", min_width=1e-6, max_width=2e-6)
         >>> events = find_triggers(trace, "glitch", max_width=50e-9)
     """
-    from oscura.triggering.edge import EdgeTrigger
-    from oscura.triggering.pulse import PulseWidthTrigger
-    from oscura.triggering.window import WindowTrigger
+    from oscura.utils.triggering.edge import EdgeTrigger
+    from oscura.utils.triggering.pulse import PulseWidthTrigger
+    from oscura.utils.triggering.window import WindowTrigger
 
     if trigger_type == "edge":
         trigger = EdgeTrigger(
@@ -145,7 +145,7 @@ def find_triggers(
             hysteresis=kwargs.get("hysteresis", 0.0),
         )
     elif trigger_type == "pattern":
-        from oscura.triggering.pattern import PatternTrigger
+        from oscura.utils.triggering.pattern import PatternTrigger
 
         trigger = PatternTrigger(  # type: ignore[assignment]
             pattern=kwargs.get("pattern", []),
@@ -159,7 +159,7 @@ def find_triggers(
             max_width=kwargs.get("max_width"),
         )
     elif trigger_type == "glitch":
-        from oscura.triggering.pulse import GlitchTrigger
+        from oscura.utils.triggering.pulse import GlitchTrigger
 
         trigger = GlitchTrigger(  # type: ignore[assignment]
             level=kwargs.get("level", 0.0),
@@ -167,7 +167,7 @@ def find_triggers(
             polarity=kwargs.get("polarity", "either"),
         )
     elif trigger_type == "runt":
-        from oscura.triggering.pulse import RuntTrigger
+        from oscura.utils.triggering.pulse import RuntTrigger
 
         trigger = RuntTrigger(  # type: ignore[assignment]
             low_threshold=kwargs.get("low_threshold", 0.0),

oscura/{triggering → utils/triggering}/edge.py

@@ -4,7 +4,7 @@ Provides edge detection with configurable thresholds, hysteresis,
 and edge polarity (rising, falling, or both).
 
 Example:
-    >>> from oscura.triggering.edge import EdgeTrigger, find_rising_edges
+    >>> from oscura.utils.triggering.edge import EdgeTrigger, find_rising_edges
     >>> # Object-oriented approach
     >>> trigger = EdgeTrigger(level=1.5, edge="rising", hysteresis=0.1)
     >>> events = trigger.find_events(trace)
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Literal
 import numpy as np
 
 from oscura.core.types import DigitalTrace, WaveformTrace
-from oscura.triggering.base import (
+from oscura.utils.triggering.base import (
     Trigger,
     TriggerEvent,
     TriggerType,