oscura 0.7.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.7.0"
+    __version__ = "0.8.0"
 
 __all__ = [
     "CANMessage",

oscura/automotive/dtc/data.json

@@ -266,7 +266,12 @@
       "category": "Powertrain",
       "severity": "High",
       "system": "Throttle Control",
-      "possible_causes": ["TPS circuit shorted to voltage", "Faulty TPS sensor", "Wiring harness open", "ECM problem"]
+      "possible_causes": [
+        "TPS circuit shorted to voltage",
+        "Faulty TPS sensor",
+        "Wiring harness open",
+        "ECM problem"
+      ]
     },
     "P0125": {
       "code": "P0125",
@@ -860,7 +865,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Emissions Control",
-      "possible_causes": ["EGR valve stuck closed", "EGR passages clogged", "Faulty EGR valve", "Vacuum leak"]
+      "possible_causes": [
+        "EGR valve stuck closed",
+        "EGR passages clogged",
+        "Faulty EGR valve",
+        "Vacuum leak"
+      ]
     },
     "P0401": {
       "code": "P0401",
@@ -881,7 +891,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Emissions Control",
-      "possible_causes": ["EGR valve stuck open", "Faulty EGR valve", "EGR vacuum solenoid fault", "ECM problem"]
+      "possible_causes": [
+        "EGR valve stuck open",
+        "Faulty EGR valve",
+        "EGR vacuum solenoid fault",
+        "ECM problem"
+      ]
     },
     "P0403": {
       "code": "P0403",
@@ -943,7 +958,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Emissions Control",
-      "possible_causes": ["Loose or missing fuel cap", "EVAP system leak", "Faulty purge valve", "Faulty vent valve"]
+      "possible_causes": [
+        "Loose or missing fuel cap",
+        "EVAP system leak",
+        "Faulty purge valve",
+        "Faulty vent valve"
+      ]
     },
     "P0441": {
       "code": "P0441",
@@ -1055,7 +1075,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Idle Control",
-      "possible_causes": ["Vacuum leak", "IAC valve fault", "Dirty throttle body", "PCV valve problem"]
+      "possible_causes": [
+        "Vacuum leak",
+        "IAC valve fault",
+        "Dirty throttle body",
+        "PCV valve problem"
+      ]
     },
     "P0507": {
       "code": "P0507",
@@ -1063,7 +1088,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Idle Control",
-      "possible_causes": ["Vacuum leak", "IAC valve stuck open", "PCV valve stuck open", "EVAP purge valve leaking"]
+      "possible_causes": [
+        "Vacuum leak",
+        "IAC valve stuck open",
+        "PCV valve stuck open",
+        "EVAP purge valve leaking"
+      ]
     },
     "P0600": {
       "code": "P0600",
@@ -1097,7 +1127,12 @@
       "category": "Powertrain",
       "severity": "Critical",
       "system": "Engine Control Module",
-      "possible_causes": ["ECM not programmed", "ECM programming incomplete", "Wrong software version", "ECM fault"]
+      "possible_causes": [
+        "ECM not programmed",
+        "ECM programming incomplete",
+        "Wrong software version",
+        "ECM fault"
+      ]
     },
     "P0603": {
       "code": "P0603",
@@ -1170,7 +1205,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Charging System",
-      "possible_causes": ["Faulty alternator", "Wiring harness problem", "Poor electrical connection", "ECM fault"]
+      "possible_causes": [
+        "Faulty alternator",
+        "Wiring harness problem",
+        "Poor electrical connection",
+        "ECM fault"
+      ]
     },
     "P0625": {
       "code": "P0625",
@@ -1243,7 +1283,12 @@
       "category": "Powertrain",
       "severity": "High",
       "system": "Transmission",
-      "possible_causes": ["Faulty input speed sensor", "Wiring harness problem", "Sensor reluctor damaged", "TCM fault"]
+      "possible_causes": [
+        "Faulty input speed sensor",
+        "Wiring harness problem",
+        "Sensor reluctor damaged",
+        "TCM fault"
+      ]
     },
     "P0720": {
       "code": "P0720",
@@ -1446,7 +1491,12 @@
       "category": "Chassis",
       "severity": "High",
       "system": "ABS",
-      "possible_causes": ["Faulty valve relay", "Relay circuit problem", "ABS module fault", "Wiring harness issue"]
+      "possible_causes": [
+        "Faulty valve relay",
+        "Relay circuit problem",
+        "ABS module fault",
+        "Wiring harness issue"
+      ]
     },
     "C0161": {
       "code": "C0161",
@@ -2156,7 +2206,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out bulb", "Wiring harness problem", "Lamp socket corrosion", "BCM fault"]
+      "possible_causes": [
+        "Burned out bulb",
+        "Wiring harness problem",
+        "Lamp socket corrosion",
+        "BCM fault"
+      ]
     },
     "B0601": {
       "code": "B0601",
@@ -2177,7 +2232,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out turn signal bulb", "Wiring harness problem", "Flasher relay fault", "BCM fault"]
+      "possible_causes": [
+        "Burned out turn signal bulb",
+        "Wiring harness problem",
+        "Flasher relay fault",
+        "BCM fault"
+      ]
     },
     "B0603": {
       "code": "B0603",
@@ -2185,7 +2245,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out turn signal bulb", "Wiring harness problem", "Flasher relay fault", "BCM fault"]
+      "possible_causes": [
+        "Burned out turn signal bulb",
+        "Wiring harness problem",
+        "Flasher relay fault",
+        "BCM fault"
+      ]
     },
     "B0604": {
       "code": "B0604",
@@ -2297,7 +2362,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Keyless Entry",
-      "possible_causes": ["Key fob battery weak", "Key fob not synchronized", "BCM fault", "Receiver antenna fault"]
+      "possible_causes": [
+        "Key fob battery weak",
+        "Key fob not synchronized",
+        "BCM fault",
+        "Receiver antenna fault"
+      ]
     },
     "B1300": {
       "code": "B1300",
@@ -2396,7 +2466,12 @@
       "category": "Network",
       "severity": "Critical",
       "system": "CAN Bus",
-      "possible_causes": ["TCM not powered", "CAN bus wiring problem", "TCM internal fault", "CAN bus short circuit"]
+      "possible_causes": [
+        "TCM not powered",
+        "CAN bus wiring problem",
+        "TCM internal fault",
+        "CAN bus short circuit"
+      ]
     },
     "U0102": {
       "code": "U0102",
@@ -2469,7 +2544,12 @@
       "category": "Network",
       "severity": "High",
       "system": "CAN Bus",
-      "possible_causes": ["BCM not powered", "CAN bus wiring problem", "BCM internal fault", "Ground connection issue"]
+      "possible_causes": [
+        "BCM not powered",
+        "CAN bus wiring problem",
+        "BCM internal fault",
+        "Ground connection issue"
+      ]
     },
     "U0141": {
       "code": "U0141",
@@ -2477,7 +2557,12 @@
       "category": "Network",
       "severity": "High",
       "system": "CAN Bus",
-      "possible_causes": ["BCM not powered", "CAN bus wiring problem", "Module internal fault", "Connector problem"]
+      "possible_causes": [
+        "BCM not powered",
+        "CAN bus wiring problem",
+        "Module internal fault",
+        "Connector problem"
+      ]
     },
     "U0151": {
       "code": "U0151",

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 = [