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

oscura/analyzers/waveform/spectral.py

@@ -646,9 +646,12 @@ def thd(
     nfft: int | None = None,
     return_db: bool = True,
 ) -> float:
-    """Compute Total Harmonic Distortion.
+    """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.
@@ -659,12 +662,14 @@ def thd(
         return_db: If True, return in dB. If False, return percentage.
 
     Returns:
-        THD in dB or percentage.
+        THD in dB (if return_db=True) or percentage (if return_db=False).
+        Always non-negative in percentage form.
 
     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"
 
     References:
         IEEE 1241-2010 Section 4.1.4.2
@@ -676,32 +681,41 @@ 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
 
-    # 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
 
-    # 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
 
+    # 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 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)
 
 
@@ -1936,6 +1950,340 @@ 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.
+    Matches the API pattern of oscura.analyzers.waveform.measurements.measure().
+
+    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.
+
+    Returns:
+        Dictionary mapping measurement names to values (with units if requested).
+
+    Raises:
+        InsufficientDataError: If trace is too short for analysis.
+        AnalysisError: If computation fails.
+
+    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']}")
+
+        >>> # Get specific measurements only
+        >>> results = measure(trace, parameters=["thd", "snr"])
+
+        >>> # Get flat values without units
+        >>> results = measure(trace, include_units=False)
+        >>> thd_value = results["thd"]  # Just the float
+
+    References:
+        IEEE 1241-2010: ADC Terminology and Test Methods
+    """
+    # Define all available spectral measurements with units
+    all_measurements = {
+        "thd": (thd, "%"),
+        "snr": (snr, "dB"),
+        "sinad": (sinad, "dB"),
+        "enob": (enob, "bits"),
+        "sfdr": (sfdr, "dB"),
+    }
+
+    # 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, unit) in selected.items():
+        try:
+            value = func(trace)  # type: ignore[operator]
+        except Exception:
+            value = np.nan
+
+        if include_units:
+            results[name] = {"value": value, "unit": unit}
+        else:
+            results[name] = value
+
+    # 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"] = {"value": dominant_freq_value, "unit": "Hz"}
+            else:
+                results["dominant_freq"] = dominant_freq_value
+        except Exception:
+            if include_units:
+                results["dominant_freq"] = {"value": np.nan, "unit": "Hz"}
+            else:
+                results["dominant_freq"] = np.nan
+
+    return results
+
+
 __all__ = [
     "bartlett_psd",
     "clear_fft_cache",
@@ -1943,13 +2291,18 @@ __all__ = [
     "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",

oscura/automotive/__init__.py

@@ -49,7 +49,7 @@ try:
     __version__ = version("oscura")
 except Exception:
     # Fallback for development/testing when package not installed
-    __version__ = "0.6.0"
+    __version__ = "0.8.0"
 
 __all__ = [
     "CANMessage",

oscura/core/config/loader.py

@@ -225,7 +225,6 @@ def load_config(
         config = copy.deepcopy(DEFAULT_CONFIG)
 
     # Search for config files if no explicit path provided
-    # use_defaults flag only controls whether to merge with DEFAULT_CONFIG
     if config_path is None:
         # Search standard locations
         search_paths = [

oscura/core/types.py

@@ -240,6 +240,42 @@ class WaveformTrace:
             return 0.0
         return (len(self.data) - 1) * self.metadata.time_base
 
+    @property
+    def is_analog(self) -> bool:
+        """Check if this is an analog signal trace.
+
+        Returns:
+            True for WaveformTrace (always analog).
+        """
+        return True
+
+    @property
+    def is_digital(self) -> bool:
+        """Check if this is a digital signal trace.
+
+        Returns:
+            False for WaveformTrace (always analog).
+        """
+        return False
+
+    @property
+    def is_iq(self) -> bool:
+        """Check if this is an I/Q signal trace.
+
+        Returns:
+            False for WaveformTrace.
+        """
+        return False
+
+    @property
+    def signal_type(self) -> str:
+        """Get the signal type identifier.
+
+        Returns:
+            "analog" for WaveformTrace.
+        """
+        return "analog"
+
     def __len__(self) -> int:
         """Return number of samples in the trace."""
         return len(self.data)
@@ -323,6 +359,42 @@ class DigitalTrace:
             return []
         return [ts for ts, is_rising in self.edges if not is_rising]
 
+    @property
+    def is_analog(self) -> bool:
+        """Check if this is an analog signal trace.
+
+        Returns:
+            False for DigitalTrace (always digital).
+        """
+        return False
+
+    @property
+    def is_digital(self) -> bool:
+        """Check if this is a digital signal trace.
+
+        Returns:
+            True for DigitalTrace (always digital).
+        """
+        return True
+
+    @property
+    def is_iq(self) -> bool:
+        """Check if this is an I/Q signal trace.
+
+        Returns:
+            False for DigitalTrace.
+        """
+        return False
+
+    @property
+    def signal_type(self) -> str:
+        """Get the signal type identifier.
+
+        Returns:
+            "digital" for DigitalTrace.
+        """
+        return "digital"
+
     def __len__(self) -> int:
         """Return number of samples in the trace."""
         return len(self.data)
@@ -421,6 +493,42 @@ class IQTrace:
             return 0.0
         return (len(self.i_data) - 1) * self.metadata.time_base
 
+    @property
+    def is_analog(self) -> bool:
+        """Check if this is an analog signal trace.
+
+        Returns:
+            False for IQTrace (complex I/Q data).
+        """
+        return False
+
+    @property
+    def is_digital(self) -> bool:
+        """Check if this is a digital signal trace.
+
+        Returns:
+            False for IQTrace (complex I/Q data).
+        """
+        return False
+
+    @property
+    def is_iq(self) -> bool:
+        """Check if this is an I/Q signal trace.
+
+        Returns:
+            True for IQTrace (always I/Q).
+        """
+        return True
+
+    @property
+    def signal_type(self) -> str:
+        """Get the signal type identifier.
+
+        Returns:
+            "iq" for IQTrace.
+        """
+        return "iq"
+
     def __len__(self) -> int:
         """Return number of samples in the trace."""
         return len(self.i_data)

oscura/loaders/__init__.py

@@ -29,6 +29,7 @@ from oscura.core.types import DigitalTrace, IQTrace, WaveformTrace
 _LOADER_REGISTRY: dict[str, tuple[str, str]] = {
     "tektronix": ("oscura.loaders.tektronix", "load_tektronix_wfm"),
     "tek": ("oscura.loaders.tektronix", "load_tektronix_wfm"),
+    "tss": ("oscura.loaders.tss", "load_tss"),
     "rigol": ("oscura.loaders.rigol", "load_rigol_wfm"),
     "numpy": ("oscura.loaders.numpy_loader", "load_npz"),
     "csv": ("oscura.loaders.csv_loader", "load_csv"),
@@ -180,6 +181,7 @@ logger = logging.getLogger(__name__)
 # Supported format extensions mapped to loader names
 SUPPORTED_FORMATS: dict[str, str] = {
     ".wfm": "auto_wfm",  # Auto-detect Tektronix vs Rigol
+    ".tss": "tss",  # Tektronix session files
     ".npz": "numpy",
     ".csv": "csv",
     ".h5": "hdf5",
@@ -392,8 +394,8 @@ def load_all_channels(
             )
         loader_name = SUPPORTED_FORMATS[ext]
 
-    # Currently only supports Tektronix WFM for multi-channel loading
-    if loader_name in ("auto_wfm", "tektronix", "tek"):
+    # Currently only supports Tektronix WFM and TSS for multi-channel loading
+    if loader_name in ("auto_wfm", "tektronix", "tek", "tss"):
         return _load_all_channels_tektronix(path)
     else:
         # For other formats, try loading as single channel
@@ -405,10 +407,10 @@ def load_all_channels(
 def _load_all_channels_tektronix(
     path: Path,
 ) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
-    """Load all channels from a Tektronix WFM file.
+    """Load all channels from a Tektronix WFM or TSS file.
 
     Args:
-        path: Path to the Tektronix .wfm file.
+        path: Path to the Tektronix .wfm or .tss file.
 
     Returns:
         Dictionary mapping channel names to traces.
@@ -416,6 +418,12 @@ def _load_all_channels_tektronix(
     Raises:
         LoaderError: If the file cannot be read or parsed.
     """
+    # Check if this is a .tss session file
+    if path.suffix.lower() == ".tss":
+        from oscura.loaders.tss import load_all_channels_tss
+
+        return load_all_channels_tss(path)
+
     wfm = _read_tektronix_file(path)
     channels: dict[str, WaveformTrace | DigitalTrace | IQTrace] = {}