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

oscura/analyzers/waveform/spectral.py

@@ -24,12 +24,13 @@ 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
 _fft_cache_stats = {"hits": 0, "misses": 0, "size": 128}
@@ -645,10 +646,13 @@ def thd(
     window: str = "hann",
     nfft: int | None = None,
     return_db: bool = True,
-) -> float:
-    """Compute Total Harmonic Distortion.
+) -> MeasurementResult:
+    """Compute Total Harmonic Distortion per IEEE 1241-2010.
 
-    THD is the ratio of harmonic power to fundamental power.
+    THD is defined as the ratio of RMS harmonic power to fundamental amplitude:
+        THD = sqrt(sum(A_harmonics^2)) / A_fundamental
+
+    where harmonics are the 2nd, 3rd, ..., nth harmonic frequencies.
 
     Args:
         trace: Input waveform trace.
@@ -656,15 +660,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 or percentage.
+        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}%)")
+        >>> result = thd(trace)
+        >>> if result["applicable"]:
+        ...     print(f"THD: {result['display']}")
 
     References:
         IEEE 1241-2010 Section 4.1.4.2
@@ -676,33 +680,40 @@ def thd(
     result = fft(trace, window=window, nfft=nfft, detrend="mean")
     freq, mag_db = result[0], result[1]
 
-    # Convert to linear
+    # Convert to linear magnitude
     magnitude = 10 ** (mag_db / 20)
 
-    # Find fundamental
+    # Find fundamental (strongest peak above DC)
     _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 harmonics
+    # 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, "%")
 
-    # Sum harmonic power
+    # Compute total harmonic power: sum of squared magnitudes
     harmonic_power = sum(magnitude[i] ** 2 for i in harmonic_indices)
 
-    # THD ratio
+    # THD = sqrt(sum(harmonic_power)) / fundamental_amplitude
+    # This is the IEEE 1241-2010 definition
     thd_ratio = np.sqrt(harmonic_power) / fund_mag
 
-    if return_db:
-        if thd_ratio <= 0:
-            return -np.inf
-        return float(20 * np.log10(thd_ratio))
-    else:
-        return float(thd_ratio * 100)
+    # Validate: THD must always be non-negative
+    if thd_ratio < 0:
+        raise ValueError(
+            f"THD ratio is negative ({thd_ratio:.6f}), indicating a calculation error. "
+            f"Fundamental: {fund_mag:.6f}, Harmonic power: {harmonic_power:.6f}"
+        )
+
+    if thd_ratio <= 0:
+        return make_measurement(0.0, "%")
+
+    # Return as percentage (0-100)
+    return make_measurement(float(thd_ratio * 100), "%")
 
 
 def snr(
@@ -711,7 +722,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.
@@ -724,11 +735,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
@@ -740,7 +752,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))
@@ -749,9 +761,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(
@@ -842,7 +854,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.
@@ -854,11 +866,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
@@ -875,7 +888,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
@@ -891,10 +904,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(
@@ -902,7 +915,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
@@ -913,21 +926,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(
@@ -935,7 +953,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.
@@ -947,11 +965,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
@@ -968,7 +988,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)
@@ -987,15 +1007,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(
@@ -1015,7 +1035,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
@@ -1072,7 +1092,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:
@@ -1936,20 +1956,444 @@ def _extract_fft_segment(
     return segment
 
 
+def find_peaks(
+    trace: WaveformTrace,
+    *,
+    window: str = "hann",
+    nfft: int | None = None,
+    threshold_db: float = -60.0,
+    min_distance: int = 5,
+    n_peaks: int | None = None,
+) -> dict[str, NDArray[np.float64]]:
+    """Find spectral peaks in FFT magnitude spectrum.
+
+    Identifies prominent frequency components above a threshold with
+    minimum spacing between peaks.
+
+    Args:
+        trace: Input waveform trace.
+        window: Window function for FFT.
+        nfft: FFT length.
+        threshold_db: Minimum peak magnitude in dB (relative to max).
+        min_distance: Minimum bin spacing between peaks.
+        n_peaks: Maximum number of peaks to return (None = all).
+
+    Returns:
+        Dictionary with keys:
+            - "frequencies": Peak frequencies in Hz
+            - "magnitudes_db": Peak magnitudes in dB
+            - "indices": FFT bin indices of peaks
+
+    Example:
+        >>> peaks = find_peaks(trace, threshold_db=-40, n_peaks=10)
+        >>> print(f"Found {len(peaks['frequencies'])} peaks")
+        >>> for freq, mag in zip(peaks['frequencies'], peaks['magnitudes_db']):
+        ...     print(f"  {freq:.1f} Hz: {mag:.1f} dB")
+
+    References:
+        IEEE 1241-2010 Section 4.1.5 - Spectral Analysis
+    """
+    from scipy.signal import find_peaks as sp_find_peaks
+
+    result = fft(trace, window=window, nfft=nfft)
+    freq, mag_db = result[0], result[1]
+
+    # Find peaks using scipy
+    # Convert threshold from dB relative to max
+    max_mag_db = np.max(mag_db)
+    abs_threshold = max_mag_db + threshold_db  # threshold_db is negative
+
+    peak_indices, _ = sp_find_peaks(mag_db, height=abs_threshold, distance=min_distance)
+
+    # Sort by magnitude (strongest first)
+    sorted_idx = np.argsort(mag_db[peak_indices])[::-1]
+    peak_indices = peak_indices[sorted_idx]
+
+    # Limit number of peaks
+    if n_peaks is not None:
+        peak_indices = peak_indices[:n_peaks]
+
+    return {
+        "frequencies": freq[peak_indices],
+        "magnitudes_db": mag_db[peak_indices],
+        "indices": peak_indices.astype(np.float64),
+    }
+
+
+def extract_harmonics(
+    trace: WaveformTrace,
+    *,
+    fundamental_freq: float | None = None,
+    n_harmonics: int = 10,
+    window: str = "hann",
+    nfft: int | None = None,
+    search_width_hz: float = 50.0,
+) -> dict[str, NDArray[np.float64]]:
+    """Extract harmonic frequencies and amplitudes from spectrum.
+
+    Identifies fundamental frequency (if not provided) and extracts
+    harmonic series with frequencies and amplitudes.
+
+    Args:
+        trace: Input waveform trace.
+        fundamental_freq: Fundamental frequency in Hz. If None, auto-detected.
+        n_harmonics: Number of harmonics to extract (excluding fundamental).
+        window: Window function for FFT.
+        nfft: FFT length.
+        search_width_hz: Search range around expected harmonic frequencies.
+
+    Returns:
+        Dictionary with keys:
+            - "frequencies": Harmonic frequencies [f0, 2f0, 3f0, ...]
+            - "amplitudes": Harmonic amplitudes (linear scale)
+            - "amplitudes_db": Harmonic amplitudes in dB
+            - "fundamental_freq": Detected or provided fundamental frequency
+
+    Example:
+        >>> harmonics = extract_harmonics(trace, n_harmonics=5)
+        >>> f0 = harmonics["fundamental_freq"]
+        >>> print(f"Fundamental: {f0:.1f} Hz")
+        >>> for i, (freq, amp_db) in enumerate(
+        ...     zip(harmonics["frequencies"], harmonics["amplitudes_db"]), 1
+        ... ):
+        ...     print(f"  H{i}: {freq:.1f} Hz at {amp_db:.1f} dB")
+
+    References:
+        IEEE 1241-2010 Section 4.1.4.2 - Harmonic Analysis
+    """
+    result = fft(trace, window=window, nfft=nfft)
+    freq, mag_db = result[0], result[1]
+    magnitude = 10 ** (mag_db / 20)
+
+    # Auto-detect fundamental if not provided
+    if fundamental_freq is None:
+        _fund_idx, fund_freq, _fund_mag = _find_fundamental(freq, magnitude)
+        fundamental_freq = fund_freq
+
+    if fundamental_freq == 0:
+        # Return empty result
+        return {
+            "frequencies": np.array([]),
+            "amplitudes": np.array([]),
+            "amplitudes_db": np.array([]),
+            "fundamental_freq": np.array([0.0]),
+        }
+
+    # Extract harmonics
+    harmonic_freqs = []
+    harmonic_amps = []
+
+    for h in range(1, n_harmonics + 2):  # Include fundamental (h=1)
+        target_freq = h * fundamental_freq
+        if target_freq > freq[-1]:
+            break
+
+        # Search around expected frequency
+        search_mask = np.abs(freq - target_freq) <= search_width_hz
+        if not np.any(search_mask):
+            continue
+
+        # Find peak in search region
+        search_region_mag = magnitude.copy()
+        search_region_mag[~search_mask] = 0
+        peak_idx = np.argmax(search_region_mag)
+
+        harmonic_freqs.append(float(freq[peak_idx]))
+        harmonic_amps.append(float(magnitude[peak_idx]))
+
+    harmonic_freqs_arr = np.array(harmonic_freqs)
+    harmonic_amps_arr = np.array(harmonic_amps)
+    harmonic_amps_db = 20 * np.log10(np.maximum(harmonic_amps_arr, 1e-20))
+
+    return {
+        "frequencies": harmonic_freqs_arr,
+        "amplitudes": harmonic_amps_arr,
+        "amplitudes_db": harmonic_amps_db,
+        "fundamental_freq": np.array([fundamental_freq]),
+    }
+
+
+def phase_spectrum(
+    trace: WaveformTrace,
+    *,
+    window: str = "hann",
+    nfft: int | None = None,
+    unwrap: bool = True,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Compute phase spectrum from FFT.
+
+    Extracts phase information from frequency domain representation.
+
+    Args:
+        trace: Input waveform trace.
+        window: Window function for FFT.
+        nfft: FFT length.
+        unwrap: If True, unwrap phase to remove 2π discontinuities.
+
+    Returns:
+        (frequencies, phase) where phase is in radians.
+
+    Example:
+        >>> freq, phase = phase_spectrum(trace)
+        >>> plt.plot(freq, phase)
+        >>> plt.xlabel("Frequency (Hz)")
+        >>> plt.ylabel("Phase (radians)")
+
+    References:
+        Oppenheim & Schafer (2009) - Discrete-Time Signal Processing
+    """
+    result = fft(trace, window=window, nfft=nfft, return_phase=True)
+    assert len(result) == 3, "Expected 3-tuple from fft with return_phase=True"
+    freq, _mag_db, phase = result[0], result[1], result[2]
+
+    if unwrap:
+        phase = np.unwrap(phase)
+
+    return freq, phase
+
+
+def group_delay(
+    trace: WaveformTrace,
+    *,
+    window: str = "hann",
+    nfft: int | None = None,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Compute group delay from phase spectrum.
+
+    Group delay is the negative derivative of phase with respect to
+    frequency, representing signal delay at each frequency.
+
+    Args:
+        trace: Input waveform trace.
+        window: Window function for FFT.
+        nfft: FFT length.
+
+    Returns:
+        (frequencies, group_delay_samples) - Delay in samples at each frequency.
+
+    Example:
+        >>> freq, gd = group_delay(trace)
+        >>> plt.plot(freq, gd)
+        >>> plt.xlabel("Frequency (Hz)")
+        >>> plt.ylabel("Group Delay (samples)")
+
+    References:
+        Oppenheim & Schafer (2009) Section 5.1.1
+    """
+    freq, phase = phase_spectrum(trace, window=window, nfft=nfft, unwrap=True)
+
+    # Group delay = -dφ/dω
+    # In discrete frequency: gd[i] ≈ -(φ[i+1] - φ[i]) / (ω[i+1] - ω[i])
+    # Convert frequency to angular frequency: ω = 2π * f
+    omega = 2 * np.pi * freq
+
+    # Compute derivative using central differences
+    gd = np.zeros_like(phase)
+
+    # Central difference for interior points
+    gd[1:-1] = -(phase[2:] - phase[:-2]) / (omega[2:] - omega[:-2])
+
+    # Forward/backward difference for boundaries
+    if len(phase) > 1:
+        gd[0] = -(phase[1] - phase[0]) / (omega[1] - omega[0])
+        gd[-1] = -(phase[-1] - phase[-2]) / (omega[-1] - omega[-2])
+
+    return freq, gd
+
+
+def measure(
+    trace: WaveformTrace,
+    *,
+    parameters: list[str] | None = None,
+    include_units: bool = True,
+) -> dict[str, Any]:
+    """Compute multiple spectral measurements with consistent format.
+
+    Unified function for computing spectral quality metrics following IEEE 1241-2010.
+    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 MeasurementResult format. If False, return flat values.
+
+    Returns:
+        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.
+        AnalysisError: If computation fails.
+
+    Example:
+        >>> from oscura.analyzers.waveform.spectral import measure
+        >>> results = measure(trace)
+        >>> if results['thd']['applicable']:
+        ...     print(f"THD: {results['thd']['display']}")
+
+        >>> # Get specific measurements only
+        >>> results = measure(trace, parameters=["thd", "snr"])
+
+        >>> # Get flat values (legacy compatibility)
+        >>> results = measure(trace, include_units=False)
+        >>> thd_value = results["thd"]  # float or np.nan
+
+    References:
+        IEEE 1241-2010: ADC Terminology and Test Methods
+    """
+    # Define all available spectral measurements
+    all_measurements = {
+        "thd": thd,
+        "snr": snr,
+        "sinad": sinad,
+        "enob": enob,
+        "sfdr": sfdr,
+    }
+
+    # Select requested measurements or all
+    if parameters is None:
+        selected = all_measurements
+    else:
+        selected = {k: v for k, v in all_measurements.items() if k in parameters}
+
+    results: dict[str, Any] = {}
+
+    for name, func in selected.items():
+        try:
+            measurement_result = func(trace)  # type: ignore[operator]
+
+            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:
+        try:
+            fft_result = fft(trace, return_phase=False)
+            freq, magnitude = fft_result[0], fft_result[1]
+            dominant_idx = int(np.argmax(np.abs(magnitude[1:]))) + 1  # Skip DC
+            dominant_freq_value = float(freq[dominant_idx])
+
+            if include_units:
+                results["dominant_freq"] = make_measurement(dominant_freq_value, "Hz")
+            else:
+                results["dominant_freq"] = dominant_freq_value
+        except Exception:
+            if include_units:
+                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",
     "cwt",
     "dwt",
     "enob",
+    "extract_harmonics",
     "fft",
     "fft_chunked",
+    "find_peaks",
     "get_fft_cache_stats",
+    "group_delay",
     "hilbert_transform",
     "idwt",
+    "measure",
     "mfcc",
     "periodogram",
+    "phase_spectrum",
     "psd",
     "psd_chunked",
     "sfdr",