sigima 0.0.1.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

sigima/tools/signal/dynamic.py

@@ -0,0 +1,254 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Dynamic Parameters (see parent package :mod:`sigima.tools.signal`)
+
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import scipy.optimize
+
+from sigima.enums import PowerUnit
+from sigima.tools.checks import check_1d_arrays
+
+
+def sinusoidal_model(
+    x: np.ndarray, a: float, f: float, phi: float, offset: float
+) -> np.ndarray:
+    """Sinusoidal model function."""
+    return a * np.sin(2 * np.pi * f * x + phi) + offset
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def sinusoidal_fit(
+    x: np.ndarray, y: np.ndarray
+) -> tuple[tuple[float, float, float, float], float]:
+    """Fit a sinusoidal model to the input data.
+
+    Args:
+        x: X data
+        y: Y data
+
+    Returns:
+        A tuple containing the fit parameters (amplitude, frequency, phase, offset)
+        and the residuals
+    """
+    # Initial guess for the parameters
+    # ==================================================================================
+    offset = np.mean(y)
+    amp = (np.max(y) - np.min(y)) / 2
+    phase_origin = 0
+    # Search for the maximum of the FFT
+    i_maxfft = np.argmax(np.abs(np.fft.fft(y - offset)))
+    if i_maxfft > len(x) / 2:
+        # If the index is greater than N/2, we are in the mirrored half spectrum
+        # (negative frequencies)
+        i_maxfft = len(x) - i_maxfft
+    freq = i_maxfft / (x[-1] - x[0])
+    # ==================================================================================
+
+    def optfunc(fitparams: np.ndarray, x: np.ndarray, y: np.ndarray) -> np.ndarray:
+        """Optimization function."""
+        return y - sinusoidal_model(x, *fitparams)
+
+    # Fit the model to the data
+    fitparams = scipy.optimize.leastsq(
+        optfunc, [amp, freq, phase_origin, offset], args=(x, y)
+    )[0]
+    y_th = sinusoidal_model(x, *fitparams)
+    residuals = np.std(y - y_th)
+    return fitparams, residuals
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def sinus_frequency(x: np.ndarray, y: np.ndarray) -> float:
+    """Compute the frequency of a sinusoidal signal.
+
+    Args:
+        x: x signal data
+        y: y signal data
+
+    Returns:
+        Frequency of the sinusoidal signal
+    """
+    fitparams, _residuals = sinusoidal_fit(x, y)
+    return fitparams[1]
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def enob(x: np.ndarray, y: np.ndarray, full_scale: float = 1.0) -> float:
+    """Compute Effective Number of Bits (ENOB).
+
+    Args:
+        x: x signal data
+        y: y signal data
+        full_scale: Full scale(V). Defaults to 1.0.
+
+    Returns:
+        Effective Number of Bits (ENOB)
+    """
+    _fitparams, residuals = sinusoidal_fit(x, y)
+    return -np.log2(residuals * np.sqrt(12) / full_scale)
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def sinad(
+    x: np.ndarray,
+    y: np.ndarray,
+    full_scale: float = 1.0,
+    unit: PowerUnit = PowerUnit.DBC,
+) -> float:
+    """Compute Signal-to-Noise and Distortion Ratio (SINAD).
+
+    Args:
+        x: x signal data
+        y: y signal data
+        full_scale: Full scale(V). Defaults to 1.0.
+        unit: Unit of the input data. Defaults to PowerUnit.DBC.
+
+    Returns:
+        Signal-to-Noise and Distortion Ratio (SINAD)
+    """
+    fitparams, residuals = sinusoidal_fit(x, y)
+    amp = fitparams[0]
+
+    # Compute the power of the fundamental
+    if unit == PowerUnit.DBC:
+        powf = np.abs(amp / np.sqrt(2))
+    else:
+        powf = full_scale / (2 * np.sqrt(2))
+
+    return 20 * np.log10(powf / residuals)
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def thd(
+    x: np.ndarray,
+    y: np.ndarray,
+    full_scale: float = 1.0,
+    unit: PowerUnit = PowerUnit.DBC,
+    nb_harm: int = 5,
+) -> float:
+    """Compute Total Harmonic Distortion (THD).
+
+    Args:
+        x: x signal data
+        y: y signal data
+        full_scale: Full scale(V). Defaults to 1.0.
+        unit: Unit of the input data. Defaults to PowerUnit.DBC.
+        nb_harm: Number of harmonics to consider. Defaults to 5.
+
+    Returns:
+        Total Harmonic Distortion (THD)
+    """
+    fitparams, _residuals = sinusoidal_fit(x, y)
+    offset = np.mean(y)
+    amp, freq = fitparams[:2]
+    ampfft = np.abs(np.fft.fft(y - offset))
+
+    # Compute the power of the fundamental
+    if unit == PowerUnit.DBC:
+        powfund = np.max(ampfft[: len(ampfft) // 2])
+    else:
+        powfund = (full_scale / (2 * np.sqrt(2))) * (len(x) / np.sqrt(2))
+
+    sumharm = 0
+    for i in np.arange(nb_harm + 2)[2:]:
+        a = i * np.ceil(freq * (x[-1] - x[0]))
+        amp = ampfft[int(a - 5) : int(a + 5)]
+        if len(amp) > 0:
+            sumharm += np.max(amp)
+    return 20 * np.log10(sumharm / powfund)
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def sfdr(
+    x: np.ndarray,
+    y: np.ndarray,
+    full_scale: float = 1.0,
+    unit: PowerUnit = PowerUnit.DBC,
+) -> float:
+    """Compute Spurious-Free Dynamic Range (SFDR).
+
+    Args:
+        x: x signal data
+        y: y signal data
+        full_scale: Full scale(V). Defaults to 1.0.
+        unit: Unit of the input data. Defaults to PowerUnit.DBC.
+
+    Returns:
+        Spurious-Free Dynamic Range (SFDR)
+    """
+    fitparams, _residuals = sinusoidal_fit(x, y)
+
+    # Compute the power of the fundamental
+    if unit == PowerUnit.DBC:
+        powfund = np.max(np.abs(np.fft.fft(y)))
+    else:
+        powfund = (full_scale / (2 * np.sqrt(2))) * (len(x) / np.sqrt(2))
+
+    maxspike = np.max(np.abs(np.fft.fft(y - sinusoidal_model(x, *fitparams))))
+    return 20 * np.log10(powfund / maxspike)
+
+
+@check_1d_arrays(x_evenly_spaced=True, x_sorted=True)
+def snr(
+    x: np.ndarray,
+    y: np.ndarray,
+    full_scale: float = 1.0,
+    unit: PowerUnit = PowerUnit.DBC,
+) -> float:
+    """Compute Signal-to-Noise Ratio (SNR).
+
+    Args:
+        x: x signal data
+        y: y signal data
+        full_scale: Full scale(V). Defaults to 1.0.
+        unit: Unit of the input data. Defaults to PowerUnit.DBC.
+
+    Returns:
+        Signal-to-Noise Ratio (SNR)
+    """
+    fitparams, _residuals = sinusoidal_fit(x, y)
+
+    # Compute the power of the fundamental
+    if unit == PowerUnit.DBC:
+        powfund = np.max(np.abs(np.fft.fft(y)))
+    else:
+        powfund = (full_scale / (2 * np.sqrt(2))) * (len(x) / np.sqrt(2))
+
+    noise = np.sqrt(np.mean((y - sinusoidal_model(x, *fitparams)) ** 2))
+    return 20 * np.log10(powfund / noise)
+
+
+def sampling_period(x: np.ndarray) -> float:
+    """Compute sampling period
+
+    Args:
+        x: X data
+
+    Returns:
+        Sampling period
+    """
+    steps = np.diff(x)
+    if not np.isclose(np.diff(steps).max(), 0, atol=1e-10):
+        warnings.warn("Non-constant sampling signal")
+    return steps[0]
+
+
+def sampling_rate(x: np.ndarray) -> float:
+    """Compute mean sampling rate
+
+    Args:
+        x: X data
+
+    Returns:
+        Sampling rate
+    """
+    return 1.0 / sampling_period(x)

sigima/tools/signal/features.py

@@ -0,0 +1,135 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Features (see parent package :mod:`sigima.algorithms.signal`)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sigima.tools.checks import check_1d_array, check_1d_arrays
+
+
+@check_1d_array(min_size=2, finite_only=True)
+def find_zero_crossings(y: np.ndarray) -> np.ndarray:
+    """Find the left indices of the zero-crossing intervals in the given array.
+
+    Args:
+        y: Input array.
+
+    Returns:
+        An array of indices where zero-crossings occur.
+    """
+    return np.nonzero(np.diff(np.sign(y)))[0]
+
+
+@check_1d_arrays(x_sorted=True)
+def find_x_axis_crossings(x: np.ndarray, y: np.ndarray) -> np.ndarray:
+    """Find the :math:`x_n` values where :math:`y = f(x)` intercepts the x-axis.
+
+    This function uses zero-crossing detection and interpolation to find the x values
+    where :math:`y = 0`.
+
+    Args:
+        x: X data.
+        y: Y data.
+
+    Returns:
+        Array of x-intercepts. The array is empty if no intercept is found.
+    """
+    # Find zero crossings.
+    xi_before = find_zero_crossings(y)
+    if len(xi_before) == 0:
+        return np.array([])
+    # Interpolate to find x values at zero crossings.
+    xi_after = xi_before + 1
+    slope = (y[xi_after] - y[xi_before]) / (x[xi_after] - x[xi_before])
+    with np.errstate(divide="ignore"):
+        x0 = -y[xi_before] / slope + x[xi_before]
+        x0 = np.where(np.isfinite(x0), x0, (x[xi_before] + x[xi_after]) / 2)
+        # mask = ~np.isfinite(x0)
+        # x0[mask] = xi_before[mask]
+    return x0
+
+
+@check_1d_arrays(x_min_size=2, x_finite_only=True, x_sorted=True)
+def find_y_at_x_value(x: np.ndarray, y: np.ndarray, x_target: float) -> float:
+    """Return the y value at a specified x value using linear interpolation.
+
+    Args:
+        x: X data.
+        y: Y data.
+        x_target: Input x value.
+
+    Returns:
+        Interpolated y value at x_target, or `nan` if input value is not within the
+        interpolation range.
+    """
+    if np.isnan(x_target):
+        return np.nan
+    return float(np.interp(x_target, x, y, left=np.nan, right=np.nan))
+
+
+@check_1d_arrays
+def find_x_values_at_y(x: np.ndarray, y: np.ndarray, y_target: float) -> np.ndarray:
+    """Find all x values where :math:`y = f(x)` equals the value :math:`y_target`.
+
+    Args:
+        x: X data.
+        y: Y data.
+        y_target: Target value.
+
+    Returns:
+        Array of x values where :math:`y = f(x)` equals :math:`y_target`.
+    """
+    return find_x_axis_crossings(x, y - y_target)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def find_bandwidth_coordinates(
+    x: np.ndarray, y: np.ndarray, threshold: float = -3.0
+) -> tuple[float, float, float, float] | None:
+    """Compute the bandwidth of the signal at a given threshold relative to the maximum.
+
+    Args:
+        x: X data.
+        y: Y data.
+        threshold: Threshold in decibel (relative to the maximum) at which the bandwidth
+         is computed. Defaults to -3.0 dB.
+
+    Returns:
+        Segment coordinates of the bandwidth of the signal at the given threshold.
+        Returns None if the bandwidth cannot be determined.
+    """
+    level: float = np.max(y) + threshold
+    crossings = find_x_values_at_y(x, y, level)
+    if len(crossings) == 1:
+        # One crossing: 1) baseband bandwidth if max is above crossing
+        #               2) passband bandwidth if max is below crossing
+        if x[np.argmax(y)] < crossings[0]:  # Baseband bandwidth
+            coords = (0.0, level, crossings[0], level)
+        else:
+            coords = (crossings[0], level, x[-1], level)
+    elif len(crossings) == 2:  # Passband bandwidth
+        # Two crossings: 1) passband bandwidth if max is above both crossings
+        #                2) no bandwidth if max is below both crossings
+        #                3) baseband bandwidth if max is between crossings
+        coords = (crossings[0], level, crossings[1], level)
+    else:
+        # No crossing or more than two crossings: cannot determine bandwidth
+        return None
+    return coords
+
+
+def contrast(y: np.ndarray) -> float:
+    """Compute contrast
+
+    Args:
+        y: Input array
+
+    Returns:
+        Contrast
+    """
+    max_, min_ = np.max(y), np.min(y)
+    return (max_ - min_) / (max_ + min_)

sigima/tools/signal/filtering.py

@@ -0,0 +1,171 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Filtering functions (see parent package :mod:`sigima.tools.signal`).
+
+This module provides denoising and filtering tools, such as Savitzky-Golay.
+
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import numpy as np
+import scipy.signal  # type: ignore[import]
+
+
+@dataclasses.dataclass
+class SimilarityResult:
+    """Result of signal similarity validation."""
+
+    ok: bool
+    rel_dc_diff: float
+    corr: float
+
+
+def signal_similarity(
+    y: np.ndarray,
+    y_filtered: np.ndarray,
+    max_dc_diff: float = 1e-2,
+    min_corr: float = 0.99,
+) -> SimilarityResult:
+    """Check global similarity between two signals.
+
+    Criteria:
+        - DC level (mean value) must not drift more than ``max_dc_diff`` (relative).
+        - Correlation (cosine similarity) must stay above ``min_corr``.
+
+    Args:
+        y: Original 1D signal.
+        y_filtered: Filtered 1D signal (same length as ``y``).
+        max_dc_diff: Maximum allowed relative change in mean value.
+        min_corr: Minimum allowed correlation between signals.
+
+    Returns:
+        A result object containing the similarity metrics.
+    """
+    if y.size != y_filtered.size:
+        raise ValueError("Signals must have the same length.")
+
+    # DC level
+    dc_orig = float(np.mean(y))
+    dc_filt = float(np.mean(y_filtered))
+    rel_diff = abs(dc_filt - dc_orig) / (abs(dc_orig) + 1e-12)
+
+    # Correlation (cosine similarity)
+    num = float(np.dot(y, y_filtered))
+    denom = float(np.linalg.norm(y) * np.linalg.norm(y_filtered) + 1e-12)
+    corr = num / denom
+
+    ok = (rel_diff <= max_dc_diff) and (corr >= min_corr)
+
+    return SimilarityResult(ok=ok, rel_dc_diff=rel_diff, corr=corr)
+
+
+def savgol_filter(
+    y: np.ndarray, window_length: int = 11, polyorder: int = 3, mode: str = "interp"
+) -> np.ndarray:
+    """Smooth a 1D signal using the Savitzky-Golay filter.
+
+    Args:
+        y: Input signal values.
+        window_length: Length of the filter window (must be odd and > polyorder).
+        polyorder: Order of the polynomial used to fit the samples.
+        mode: Padding mode passed to ``scipy.signal.savgol_filter``.
+
+    Returns:
+        Smoothed signal values.
+    """
+    if window_length % 2 == 0:
+        raise ValueError("window_length must be odd.")
+    if window_length <= polyorder:
+        raise ValueError("window_length must be greater than polyorder.")
+
+    y_smooth = scipy.signal.savgol_filter(y, window_length, polyorder, mode=mode)
+    return y_smooth
+
+
+def choose_savgol_window_auto(
+    y: np.ndarray,
+    target_reduction: float = 0.3,
+    polyorder: int = 3,
+    min_len: int = 5,
+    max_len: int = 101,
+) -> int:
+    """Choose the smallest Savitzky-Golay window that sufficiently reduces noise.
+
+    Strategy: measure noise on first differences of y, then
+    increase the window until noise is reduced by ``target_reduction``.
+
+    Args:
+        y: 1D signal values.
+        target_reduction: Desired reduction factor in diff-std (e.g. 0.3 → ÷3).
+        polyorder: Polynomial order.
+        min_len: Minimum allowed window length.
+        max_len: Maximum allowed window length.
+
+    Returns:
+        Odd integer window length.
+    """
+    diffs = np.diff(y)
+    sigma0 = np.median(np.abs(diffs - np.median(diffs))) / 0.6745
+
+    for win in range(min_len | 1, max_len + 1, 2):  # odd lengths
+        if win <= polyorder:
+            continue
+        y_smooth = scipy.signal.savgol_filter(y, win, polyorder)
+        sigma = (
+            np.median(np.abs(np.diff(y_smooth) - np.median(np.diff(y_smooth)))) / 0.6745
+        )
+        if sigma <= target_reduction * sigma0:
+            return win
+
+    return max_len | 1  # fallback
+
+
+def denoise_preserve_shape(
+    y: np.ndarray,
+    polyorder: int = 3,
+    target_reduction: float = 0.3,
+    max_dc_diff: float = 1e-2,
+    min_corr: float = 0.99,
+    min_len: int = 5,
+    max_len: int = 101,
+) -> tuple[np.ndarray, SimilarityResult]:
+    """Denoise a signal while preserving slow variations.
+
+    Strategy:
+        1. Estimate noise on first differences.
+        2. Choose the smallest Savitzky-Golay window that reduces noise
+           by at least ``target_reduction``.
+        3. Apply the filter.
+        4. Check similarity with the original signal (DC and correlation).
+        5. Return filtered signal if ok, otherwise return original.
+
+    Args:
+        y: Input signal values.
+        polyorder: Polynomial order of Savitzky-Golay filter.
+        target_reduction: Desired noise reduction factor (0.3 → ÷3).
+        max_dc_diff: Maximum allowed relative change in mean value.
+        min_corr: Minimum allowed correlation between signals.
+        min_len: Minimum window length.
+        max_len: Maximum window length.
+
+    Returns:
+        A tuple ``(y_denoised, result)`` where ``y_denoised`` is either the
+        filtered signal or the original if similarity criteria are not met, and
+        ``result`` contains the details of the similarity check.
+    """
+    win = choose_savgol_window_auto(
+        y,
+        target_reduction=target_reduction,
+        polyorder=polyorder,
+        min_len=min_len,
+        max_len=max_len,
+    )
+    y_smooth = savgol_filter(y, window_length=win, polyorder=polyorder, mode="interp")
+    result = signal_similarity(y, y_smooth, max_dc_diff=max_dc_diff, min_corr=min_corr)
+    if not result.ok:
+        y_smooth = y
+    return y_smooth, result