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

oscura/analyzers/waveform/spectral.py

@@ -17,6 +17,7 @@ References:
 
 from __future__ import annotations
 
+import threading
 from functools import lru_cache
 from typing import TYPE_CHECKING, Any, Literal
 
@@ -24,15 +25,17 @@ import numpy as np
 from scipy import signal as sp_signal
 
 from oscura.core.exceptions import AnalysisError, InsufficientDataError
+from oscura.core.measurement_result import make_inapplicable, make_measurement
 from oscura.utils.windowing import get_window
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
-    from oscura.core.types import WaveformTrace
+    from oscura.core.types import MeasurementResult, WaveformTrace
 
-# Global FFT cache statistics
+# Global FFT cache statistics (thread-safe)
 _fft_cache_stats = {"hits": 0, "misses": 0, "size": 128}
+_fft_cache_lock = threading.Lock()
 
 
 def get_fft_cache_stats() -> dict[str, int]:
@@ -45,7 +48,8 @@ def get_fft_cache_stats() -> dict[str, int]:
         >>> stats = get_fft_cache_stats()
         >>> print(f"Cache hit rate: {stats['hits'] / (stats['hits'] + stats['misses']):.1%}")
     """
-    return _fft_cache_stats.copy()
+    with _fft_cache_lock:
+        return _fft_cache_stats.copy()
 
 
 def clear_fft_cache() -> None:
@@ -57,8 +61,9 @@ def clear_fft_cache() -> None:
         >>> clear_fft_cache()  # Clear cached FFT results
     """
     _compute_fft_cached.cache_clear()
-    _fft_cache_stats["hits"] = 0
-    _fft_cache_stats["misses"] = 0
+    with _fft_cache_lock:
+        _fft_cache_stats["hits"] = 0
+        _fft_cache_stats["misses"] = 0
 
 
 def configure_fft_cache(size: int) -> None:
@@ -71,11 +76,12 @@ def configure_fft_cache(size: int) -> None:
         >>> configure_fft_cache(256)  # Increase cache size for better hit rate
     """
     global _compute_fft_cached
-    _fft_cache_stats["size"] = size
-    # Recreate cache with new size
-    _compute_fft_cached = lru_cache(maxsize=size)(_compute_fft_impl)
-    _fft_cache_stats["hits"] = 0
-    _fft_cache_stats["misses"] = 0
+    with _fft_cache_lock:
+        _fft_cache_stats["size"] = size
+        # Recreate cache with new size
+        _compute_fft_cached = lru_cache(maxsize=size)(_compute_fft_impl)
+        _fft_cache_stats["hits"] = 0
+        _fft_cache_stats["misses"] = 0
 
 
 def _compute_fft_impl(
@@ -269,7 +275,8 @@ def _fft_cached_path(
     freq, magnitude_db, phase = _compute_fft_cached(
         data_bytes, n, window, nfft_computed, detrend, sample_rate
     )
-    _fft_cache_stats["hits"] += 1
+    with _fft_cache_lock:
+        _fft_cache_stats["hits"] += 1
 
     if return_phase:
         return freq, magnitude_db, phase
@@ -301,7 +308,8 @@ def _fft_direct_path(
     Returns:
         FFT results (with or without phase).
     """
-    _fft_cache_stats["misses"] += 1
+    with _fft_cache_lock:
+        _fft_cache_stats["misses"] += 1
 
     w = get_window(window, n)
     data_windowed = data_processed * w
@@ -645,7 +653,7 @@ def thd(
     window: str = "hann",
     nfft: int | None = None,
     return_db: bool = True,
-) -> float:
+) -> MeasurementResult:
     """Compute Total Harmonic Distortion per IEEE 1241-2010.
 
     THD is defined as the ratio of RMS harmonic power to fundamental amplitude:
@@ -659,17 +667,15 @@ def thd(
         window: Window function for FFT.
         nfft: FFT length. If None, uses data length (no zero-padding) to
             preserve coherent sampling per IEEE 1241-2010.
-        return_db: If True, return in dB. If False, return percentage.
+        return_db: Ignored (always returns percentage, with dB in metadata if needed).
 
     Returns:
-        THD in dB (if return_db=True) or percentage (if return_db=False).
-        Always non-negative in percentage form.
+        MeasurementResult with THD as percentage, or inapplicable if cannot compute.
 
     Example:
-        >>> thd_db = thd(trace)
-        >>> thd_pct = thd(trace, return_db=False)
-        >>> print(f"THD: {thd_db:.1f} dB ({thd_pct:.2f}%)")
-        >>> assert thd_pct >= 0, "THD percentage must be non-negative"
+        >>> result = thd(trace)
+        >>> if result["applicable"]:
+        ...     print(f"THD: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.2
@@ -688,13 +694,13 @@ def thd(
     _fund_idx, fund_freq, fund_mag = _find_fundamental(freq, magnitude)
 
     if fund_mag == 0 or fund_freq == 0:
-        return np.nan
+        return make_inapplicable("%", "No fundamental frequency detected")
 
     # Find harmonic frequencies (2*f0, 3*f0, ..., n*f0)
     harmonic_indices = _find_harmonic_indices(freq, fund_freq, n_harmonics)
 
     if len(harmonic_indices) == 0:
-        return 0.0 if not return_db else -np.inf
+        return make_measurement(0.0, "%")
 
     # Compute total harmonic power: sum of squared magnitudes
     harmonic_power = sum(magnitude[i] ** 2 for i in harmonic_indices)
@@ -710,13 +716,11 @@ def thd(
             f"Fundamental: {fund_mag:.6f}, Harmonic power: {harmonic_power:.6f}"
         )
 
-    if return_db:
-        if thd_ratio <= 0:
-            return -np.inf
-        return float(20 * np.log10(thd_ratio))
-    else:
-        # Return as percentage
-        return float(thd_ratio * 100)
+    if thd_ratio <= 0:
+        return make_measurement(0.0, "%")
+
+    # Return as percentage (0-100)
+    return make_measurement(float(thd_ratio * 100), "%")
 
 
 def snr(
@@ -725,7 +729,7 @@ def snr(
     n_harmonics: int = 10,
     window: str = "hann",
     nfft: int | None = None,
-) -> float:
+) -> MeasurementResult:
     """Compute Signal-to-Noise Ratio.
 
     SNR is the ratio of signal power to noise power, excluding harmonics.
@@ -738,11 +742,12 @@ def snr(
             preserve coherent sampling per IEEE 1241-2010.
 
     Returns:
-        SNR in dB.
+        MeasurementResult with SNR in dB, or inapplicable if cannot compute.
 
     Example:
-        >>> snr_db = snr(trace)
-        >>> print(f"SNR: {snr_db:.1f} dB")
+        >>> result = snr(trace)
+        >>> if result["applicable"]:
+        ...     print(f"SNR: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.1
@@ -754,7 +759,7 @@ def snr(
     fund_idx, fund_freq, fund_mag = _find_fundamental(freq, magnitude)
 
     if fund_mag == 0 or fund_freq == 0:
-        return np.nan
+        return make_inapplicable("dB", "No fundamental frequency detected")
 
     harmonic_indices = _find_harmonic_indices(freq, fund_freq, n_harmonics)
     exclude_indices = _build_exclusion_set(fund_idx, harmonic_indices, len(magnitude))
@@ -763,9 +768,9 @@ def snr(
     noise_power = _compute_noise_power(magnitude, exclude_indices)
 
     if noise_power <= 0:
-        return np.inf
+        return make_inapplicable("dB", "No noise detected (perfect signal)")
 
-    return float(10 * np.log10(signal_power / noise_power))
+    return make_measurement(float(10 * np.log10(signal_power / noise_power)), "dB")
 
 
 def _compute_magnitude_spectrum(
@@ -856,7 +861,7 @@ def sinad(
     *,
     window: str = "hann",
     nfft: int | None = None,
-) -> float:
+) -> MeasurementResult:
     """Compute Signal-to-Noise and Distortion ratio.
 
     SINAD is the ratio of signal power to noise plus distortion power.
@@ -868,11 +873,12 @@ def sinad(
             preserve coherent sampling per IEEE 1241-2010.
 
     Returns:
-        SINAD in dB.
+        MeasurementResult with SINAD in dB, or inapplicable if cannot compute.
 
     Example:
-        >>> sinad_db = sinad(trace)
-        >>> print(f"SINAD: {sinad_db:.1f} dB")
+        >>> result = sinad(trace)
+        >>> if result["applicable"]:
+        ...     print(f"SINAD: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.3
@@ -889,7 +895,7 @@ def sinad(
     fund_idx, _fund_freq, fund_mag = _find_fundamental(freq, magnitude)
 
     if fund_mag == 0:
-        return np.nan
+        return make_inapplicable("dB", "No fundamental frequency detected")
 
     # Signal power: use 3-bin window around fundamental to capture spectral leakage
     signal_power = 0.0
@@ -905,10 +911,10 @@ def sinad(
     nad_power = total_power - signal_power
 
     if nad_power <= 0:
-        return np.inf
+        return make_inapplicable("dB", "No noise/distortion detected (perfect signal)")
 
     sinad_ratio = signal_power / nad_power
-    return float(10 * np.log10(sinad_ratio))
+    return make_measurement(float(10 * np.log10(sinad_ratio)), "dB")
 
 
 def enob(
@@ -916,7 +922,7 @@ def enob(
     *,
     window: str = "hann",
     nfft: int | None = None,
-) -> float:
+) -> MeasurementResult:
     """Compute Effective Number of Bits from SINAD.
 
     ENOB = (SINAD - 1.76) / 6.02
@@ -927,21 +933,26 @@ def enob(
         nfft: FFT length.
 
     Returns:
-        ENOB in bits, or np.nan if SINAD is invalid.
+        MeasurementResult with ENOB in bits, or inapplicable if SINAD is invalid.
 
     Example:
-        >>> bits = enob(trace)
-        >>> print(f"ENOB: {bits:.2f} bits")
+        >>> result = enob(trace)
+        >>> if result["applicable"]:
+        ...     print(f"ENOB: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.4
     """
-    sinad_db = sinad(trace, window=window, nfft=nfft)
+    sinad_result = sinad(trace, window=window, nfft=nfft)
+
+    if not sinad_result["applicable"] or sinad_result["value"] is None:
+        return make_inapplicable("", "SINAD unavailable")
 
-    if np.isnan(sinad_db) or sinad_db <= 0:
-        return np.nan
+    sinad_db = sinad_result["value"]
+    if sinad_db <= 0:
+        return make_inapplicable("", "SINAD too low (≤0 dB)")
 
-    return float((sinad_db - 1.76) / 6.02)
+    return make_measurement(float((sinad_db - 1.76) / 6.02), "")
 
 
 def sfdr(
@@ -949,7 +960,7 @@ def sfdr(
     *,
     window: str = "hann",
     nfft: int | None = None,
-) -> float:
+) -> MeasurementResult:
     """Compute Spurious-Free Dynamic Range.
 
     SFDR is the ratio of fundamental to largest spurious component.
@@ -961,11 +972,13 @@ def sfdr(
             preserve coherent sampling per IEEE 1241-2010.
 
     Returns:
-        SFDR in dBc (dB relative to carrier/fundamental).
+        MeasurementResult with SFDR in dBc (dB relative to carrier/fundamental),
+        or inapplicable if cannot compute.
 
     Example:
-        >>> sfdr_db = sfdr(trace)
-        >>> print(f"SFDR: {sfdr_db:.1f} dBc")
+        >>> result = sfdr(trace)
+        >>> if result["applicable"]:
+        ...     print(f"SFDR: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.5
@@ -982,7 +995,7 @@ def sfdr(
     fund_idx, _fund_freq, fund_mag = _find_fundamental(freq, magnitude)
 
     if fund_mag == 0:
-        return np.nan
+        return make_inapplicable("dB", "No fundamental frequency detected")
 
     # Create mask for spurs (exclude fundamental and DC)
     spur_mask = np.ones(len(magnitude), dtype=bool)
@@ -1001,15 +1014,15 @@ def sfdr(
     # Find largest spur
     spur_magnitudes = magnitude[spur_mask]
     if len(spur_magnitudes) == 0:
-        return np.inf
+        return make_inapplicable("dB", "No spurs detected (clean spectrum)")
 
     max_spur = np.max(spur_magnitudes)
 
     if max_spur <= 0:
-        return np.inf
+        return make_inapplicable("dB", "No valid spurs detected")
 
     sfdr_ratio = fund_mag / max_spur
-    return float(20 * np.log10(sfdr_ratio))
+    return make_measurement(float(20 * np.log10(sfdr_ratio)), "dB")
 
 
 def hilbert_transform(
@@ -1029,7 +1042,7 @@ def hilbert_transform(
 
     Example:
         >>> envelope, phase, inst_freq = hilbert_transform(trace)
-        >>> plt.plot(trace.time_vector, envelope)
+        >>> plt.plot(trace.time, envelope)
 
     References:
         Oppenheim, A. V. & Schafer, R. W. (2009). Discrete-Time
@@ -1086,7 +1099,7 @@ def cwt(
 
     Example:
         >>> scales, freqs, coef = cwt(trace, wavelet="morlet")
-        >>> plt.pcolormesh(trace.time_vector, freqs, np.abs(coef))
+        >>> plt.pcolormesh(trace.time, freqs, np.abs(coef))
         >>> plt.ylabel("Frequency (Hz)")
 
     References:
@@ -2204,16 +2217,17 @@ def measure(
     """Compute multiple spectral measurements with consistent format.
 
     Unified function for computing spectral quality metrics following IEEE 1241-2010.
-    Matches the API pattern of oscura.analyzers.waveform.measurements.measure().
+    Returns MeasurementResult format with applicability tracking.
 
     Args:
         trace: Input waveform trace.
         parameters: List of measurement names to compute. If None, compute all.
             Valid names: thd, snr, sinad, enob, sfdr, dominant_freq
-        include_units: If True, return {value, unit} dicts. If False, return flat values.
+        include_units: If True, return MeasurementResult format. If False, return flat values.
 
     Returns:
-        Dictionary mapping measurement names to values (with units if requested).
+        Dictionary mapping measurement names to MeasurementResults (if include_units=True)
+        or raw values (if include_units=False).
 
     Raises:
         InsufficientDataError: If trace is too short for analysis.
@@ -2222,26 +2236,26 @@ def measure(
     Example:
         >>> from oscura.analyzers.waveform.spectral import measure
         >>> results = measure(trace)
-        >>> print(f"THD: {results['thd']['value']}{results['thd']['unit']}")
-        >>> print(f"SNR: {results['snr']['value']} {results['snr']['unit']}")
+        >>> if results['thd']['applicable']:
+        ...     print(f"THD: {results['thd']['display']}")
 
         >>> # Get specific measurements only
         >>> results = measure(trace, parameters=["thd", "snr"])
 
-        >>> # Get flat values without units
+        >>> # Get flat values (legacy compatibility)
         >>> results = measure(trace, include_units=False)
-        >>> thd_value = results["thd"]  # Just the float
+        >>> thd_value = results["thd"]  # float or np.nan
 
     References:
         IEEE 1241-2010: ADC Terminology and Test Methods
     """
-    # Define all available spectral measurements with units
+    # Define all available spectral measurements
     all_measurements = {
-        "thd": (thd, "%"),
-        "snr": (snr, "dB"),
-        "sinad": (sinad, "dB"),
-        "enob": (enob, "bits"),
-        "sfdr": (sfdr, "dB"),
+        "thd": thd,
+        "snr": snr,
+        "sinad": sinad,
+        "enob": enob,
+        "sfdr": sfdr,
     }
 
     # Select requested measurements or all
@@ -2252,16 +2266,26 @@ def measure(
 
     results: dict[str, Any] = {}
 
-    for name, (func, unit) in selected.items():
+    for name, func in selected.items():
         try:
-            value = func(trace)  # type: ignore[operator]
-        except Exception:
-            value = np.nan
+            measurement_result = func(trace)  # type: ignore[operator]
 
-        if include_units:
-            results[name] = {"value": value, "unit": unit}
-        else:
-            results[name] = value
+            if include_units:
+                # Return full MeasurementResult
+                results[name] = measurement_result
+            else:
+                # Legacy mode: extract raw value (NaN if inapplicable)
+                if measurement_result["applicable"]:
+                    results[name] = measurement_result["value"]
+                else:
+                    results[name] = np.nan
+
+        except Exception:
+            # On error, create inapplicable result
+            if include_units:
+                results[name] = make_inapplicable("", "Measurement failed")
+            else:
+                results[name] = np.nan
 
     # Add dominant frequency if requested or if computing all
     if parameters is None or "dominant_freq" in parameters:
@@ -2272,19 +2296,93 @@ def measure(
             dominant_freq_value = float(freq[dominant_idx])
 
             if include_units:
-                results["dominant_freq"] = {"value": dominant_freq_value, "unit": "Hz"}
+                results["dominant_freq"] = make_measurement(dominant_freq_value, "Hz")
             else:
                 results["dominant_freq"] = dominant_freq_value
         except Exception:
             if include_units:
-                results["dominant_freq"] = {"value": np.nan, "unit": "Hz"}
+                results["dominant_freq"] = make_inapplicable("Hz", "FFT failed")
             else:
                 results["dominant_freq"] = np.nan
 
     return results
 
 
+class SpectralAnalyzer:
+    """Spectral analysis class wrapping functional APIs.
+
+    Provides object-oriented interface to spectral analysis functions
+    for compatibility with legacy code and workflows.
+
+    Example:
+        >>> analyzer = SpectralAnalyzer()
+        >>> freqs, mags = analyzer.fft(data, sample_rate)
+        >>> thd_value = analyzer.thd(trace)
+    """
+
+    def fft(
+        self,
+        data: NDArray[np.floating[Any]],
+        sample_rate: float,
+        *,
+        window: str = "hann",
+        nfft: int | None = None,
+        detrend: Literal["none", "mean", "linear"] = "mean",
+        return_phase: bool = False,
+    ) -> (
+        tuple[NDArray[np.float64], NDArray[np.float64]]
+        | tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]
+    ):
+        """Compute FFT of signal data.
+
+        Args:
+            data: Input signal data
+            sample_rate: Sample rate in Hz
+            window: Window function name (default "hann")
+            nfft: FFT size (power of 2), auto-computed if None
+            detrend: Detrend method ('none', 'mean', or 'linear')
+            return_phase: If True, also return phase spectrum
+
+        Returns:
+            Tuple of (frequencies, magnitudes_db) or (frequencies, magnitudes_db, phase)
+        """
+        from oscura.core.types import TraceMetadata, WaveformTrace
+
+        # Convert to WaveformTrace for functional API
+        trace = WaveformTrace(data=data, metadata=TraceMetadata(sample_rate=sample_rate))
+
+        # Call functional API (always returns dB)
+        return fft(trace, window=window, nfft=nfft, detrend=detrend, return_phase=return_phase)
+
+    def thd(self, trace: WaveformTrace, fundamental_freq: float | None = None) -> MeasurementResult:
+        """Compute Total Harmonic Distortion."""
+        return thd(trace)
+
+    def snr(self, trace: WaveformTrace, fundamental_freq: float | None = None) -> MeasurementResult:
+        """Compute Signal-to-Noise Ratio."""
+        return snr(trace)
+
+    def sinad(
+        self, trace: WaveformTrace, fundamental_freq: float | None = None
+    ) -> MeasurementResult:
+        """Compute SINAD (Signal-to-Noise-And-Distortion)."""
+        return sinad(trace)
+
+    def enob(
+        self, trace: WaveformTrace, fundamental_freq: float | None = None
+    ) -> MeasurementResult:
+        """Compute Effective Number of Bits."""
+        return enob(trace)
+
+    def sfdr(
+        self, trace: WaveformTrace, fundamental_freq: float | None = None
+    ) -> MeasurementResult:
+        """Compute Spurious-Free Dynamic Range."""
+        return sfdr(trace)
+
+
 __all__ = [
+    "SpectralAnalyzer",
     "bartlett_psd",
     "clear_fft_cache",
     "configure_fft_cache",

oscura/api/dsl/commands.py

@@ -147,18 +147,27 @@ def cmd_plot(trace: Any, **options: Any) -> None:
         OscuraError: If plotting fails
     """
     try:
-        from oscura.visualization import plot
+        import matplotlib.pyplot as plt
+
+        from oscura.visualization import plot_waveform
 
         title = options.get("title", "Trace Plot")
         annotate = options.get("annotate")
 
-        plot.plot_trace(trace, title=title)
+        fig, ax = plt.subplots()
+        plot_waveform(ax, trace)
+        ax.set_title(title)
 
         if annotate:
-            plot.add_annotation(annotate)
-
-        # Import matplotlib.pyplot for show()
-        import matplotlib.pyplot as plt
+            ax.text(
+                0.5,
+                0.95,
+                annotate,
+                transform=ax.transAxes,
+                ha="center",
+                va="top",
+                bbox={"boxstyle": "round", "facecolor": "wheat"},
+            )
 
         plt.show()