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

sigima/tools/signal/scaling.py

@@ -0,0 +1,50 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Scaling (see parent package :mod:`sigima.algorithms.signal`)
+
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+import numpy as np
+
+from sigima.enums import NormalizationMethod
+
+
+def normalize(
+    yin: np.ndarray,
+    parameter: NormalizationMethod = NormalizationMethod.MAXIMUM,
+) -> np.ndarray:
+    """Normalize input array to a given parameter.
+
+    Args:
+        yin: Input array
+        parameter: Normalization parameter. Defaults to MAXIMUM
+
+    Returns:
+        Normalized array
+    """
+    axis = len(yin.shape) - 1
+    if parameter == NormalizationMethod.MAXIMUM:
+        maximum = np.nanmax(yin, axis)
+        if axis == 1:
+            maximum = maximum.reshape((len(maximum), 1))
+        maxarray = np.tile(maximum, yin.shape[axis]).reshape(yin.shape)
+        return yin / maxarray
+    if parameter == NormalizationMethod.AMPLITUDE:
+        ytemp = np.array(yin, copy=True)
+        minimum = np.nanmin(yin, axis)
+        if axis == 1:
+            minimum = minimum.reshape((len(minimum), 1))
+        ytemp -= minimum
+        return normalize(ytemp, parameter=NormalizationMethod.MAXIMUM)
+    if parameter == NormalizationMethod.AREA:
+        return yin / np.nansum(yin)
+    if parameter == NormalizationMethod.ENERGY:
+        return yin / np.sqrt(np.nansum(yin * yin.conjugate()))
+    if parameter == NormalizationMethod.RMS:
+        return yin / np.sqrt(np.nanmean(yin * yin.conjugate()))
+    raise RuntimeError(f"Unsupported parameter {parameter}")

sigima/tools/signal/stability.py

@@ -0,0 +1,258 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Stability Analysis (see parent package :mod:`sigima.algorithms.signal`)
+
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sigima.tools.checks import check_1d_arrays
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def allan_variance(x: np.ndarray, y: np.ndarray, tau_values: np.ndarray) -> np.ndarray:
+    """
+    Calculate the Allan variance for given time and measurement values at specified
+    tau values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Allan deviation time values
+
+    Returns:
+        Allan variance values
+    """
+    if len(x) != len(y):
+        raise ValueError(
+            "Time array (x) and measured values array (y) must have the same length."
+        )
+
+    dt = np.mean(np.diff(x))  # Time step size
+    if not np.allclose(np.diff(x), dt):
+        raise ValueError("Time values (x) must be equally spaced.")
+
+    allan_var = []
+    for tau in tau_values:
+        m = int(round(tau / dt))  # Number of time steps in a tau
+        if m < 1:
+            raise ValueError(
+                f"Tau value {tau} is smaller than the sampling interval {dt}"
+            )
+        if m > len(y) // 2:
+            # Tau too large for reliable statistics
+            allan_var.append(np.nan)
+            continue
+
+        # Calculate the clusters/bins
+        clusters = y[: len(y) - (len(y) % m)].reshape(-1, m)
+        bin_means = clusters.mean(axis=1)
+
+        # Calculate Allan variance using the definition
+        # σ²(τ) = 1/(2(N-1)) Σ(y_(i+1) - y_i)²
+        # where y_i are the bin means
+        squared_diff = np.sum(np.diff(bin_means) ** 2)
+        n = len(bin_means) - 1
+
+        if n > 0:
+            var = squared_diff / (2.0 * n)
+            allan_var.append(var)
+        else:
+            allan_var.append(np.nan)
+
+    return np.array(allan_var)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def allan_deviation(x: np.ndarray, y: np.ndarray, tau_values: np.ndarray) -> np.ndarray:
+    """
+    Calculate the Allan deviation for given time and measurement values at specified
+    tau values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Allan deviation time values
+
+    Returns:
+        Allan deviation values
+    """
+    return np.sqrt(allan_variance(x, y, tau_values))
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def overlapping_allan_variance(
+    x: np.ndarray, y: np.ndarray, tau_values: np.ndarray
+) -> np.ndarray:
+    """
+    Calculate the Overlapping Allan variance for given time and measurement values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Allan deviation time values
+
+    Returns:
+        Overlapping Allan variance values
+    """
+    if len(x) != len(y):
+        raise ValueError(
+            "Time array (x) and measured values array (y) must have the same length."
+        )
+
+    dt = np.mean(np.diff(x))  # Time step size
+    if not np.allclose(np.diff(x), dt):
+        raise ValueError("Time values (x) must be equally spaced.")
+
+    overlapping_var = []
+    for tau in tau_values:
+        tau_bins = int(tau / dt)
+        if tau_bins <= 1 or tau_bins > len(y) / 2:
+            overlapping_var.append(np.nan)
+            continue
+
+        m = len(y) - tau_bins  # Number of overlapping segments
+        avg_values = [np.mean(y[i : i + tau_bins]) for i in range(m)]
+        diff = np.diff(avg_values)
+        overlapping_var.append(0.5 * np.mean(np.array(diff) ** 2))
+
+    return np.array(overlapping_var)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def modified_allan_variance(
+    x: np.ndarray, y: np.ndarray, tau_values: np.ndarray
+) -> np.ndarray:
+    """
+    Calculate the Modified Allan variance for given time and measurement values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Modified Allan deviation time values
+
+    Returns:
+        Modified Allan variance values
+    """
+    if len(x) != len(y):
+        raise ValueError(
+            "Time array (x) and measured values array (y) must have the same length."
+        )
+
+    dt = np.mean(np.diff(x))
+    if not np.allclose(np.diff(x), dt):
+        raise ValueError("Time values (x) must be equally spaced.")
+
+    mod_allan_var = []
+    for tau in tau_values:
+        tau_bins = int(tau / dt)
+        if tau_bins <= 1 or tau_bins > len(y) / 2:
+            mod_allan_var.append(np.nan)
+            continue
+
+        m = int(len(y) / tau_bins)
+        reshaped = y[: m * tau_bins].reshape(m, tau_bins)
+
+        avg_values = reshaped.mean(axis=1)
+        squared_diff = (np.diff(avg_values)) ** 2
+        mod_allan_var.append(np.mean(squared_diff) / (2 * (tau_bins**2)))
+
+    return np.array(mod_allan_var)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def hadamard_variance(
+    x: np.ndarray, y: np.ndarray, tau_values: np.ndarray
+) -> np.ndarray:
+    """
+    Calculate the Hadamard variance for given time and measurement values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Hadamard deviation time values
+
+    Returns:
+        Hadamard variance values
+    """
+    if len(x) != len(y):
+        raise ValueError(
+            "Time array (x) and measured values array (y) must have the same length."
+        )
+
+    dt = np.mean(np.diff(x))
+    if not np.allclose(np.diff(x), dt):
+        raise ValueError("Time values (x) must be equally spaced.")
+
+    hadamard_var = []
+    for tau in tau_values:
+        tau_bins = int(tau / dt)
+        if tau_bins <= 1 or tau_bins > len(y) / 3:
+            hadamard_var.append(np.nan)
+            continue
+
+        m = len(y) - 2 * tau_bins
+        avg_values = [np.mean(y[i : i + tau_bins]) for i in range(m)]
+        diff = np.diff(avg_values, n=2)  # Second differences
+        hadamard_var.append(np.mean(diff**2) / 6)
+
+    return np.array(hadamard_var)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def total_variance(x: np.ndarray, y: np.ndarray, tau_values: np.ndarray) -> np.ndarray:
+    """
+    Calculate the Total variance for given time and measurement values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Total variance time values
+
+    Returns:
+        Total variance values
+    """
+    if len(x) != len(y):
+        raise ValueError(
+            "Time array (x) and measured values array (y) must have the same length."
+        )
+
+    dt = np.mean(np.diff(x))
+    if not np.allclose(np.diff(x), dt):
+        raise ValueError("Time values (x) must be equally spaced.")
+
+    total_var = []
+    for tau in tau_values:
+        tau_bins = int(tau / dt)
+        if tau_bins <= 1 or tau_bins > len(y) / 2:
+            total_var.append(np.nan)
+            continue
+
+        m = int(len(y) / tau_bins)
+        reshaped = y[: m * tau_bins].reshape(m, tau_bins)
+
+        avg_values = reshaped.mean(axis=1)
+        squared_diff = np.diff(avg_values) ** 2
+        total_var.append(np.mean(squared_diff))
+
+    return np.array(total_var)
+
+
+@check_1d_arrays(x_evenly_spaced=True)
+def time_deviation(x: np.ndarray, y: np.ndarray, tau_values: np.ndarray) -> np.ndarray:
+    """
+    Calculate the Time Deviation (TDEV) for given time and measurement values.
+
+    Args:
+        x: Time array
+        y: Measured values array
+        tau_values: Time deviation time values
+
+    Returns:
+        Time deviation values
+    """
+    allan_var = allan_variance(x, y, tau_values)
+    return np.sqrt(allan_var) * tau_values

sigima/tools/signal/windowing.py

@@ -0,0 +1,90 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Windowing (see parent package :mod:`sigima.algorithms.signal`)
+
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+import scipy.signal.windows
+
+from sigima.enums import WindowingMethod
+
+
+def get_window(method: WindowingMethod) -> Callable[[int], np.ndarray]:
+    """Get the window function.
+
+    .. note::
+
+        The window functions are from `scipy.signal.windows` and `numpy`.
+        All functions take an integer argument that specifies the length of the window,
+        and return a NumPy array of the same length.
+
+    Args:
+        method: Windowing function method.
+
+    Returns:
+        Window function.
+
+    Raises:
+        ValueError: If the method is not recognized.
+    """
+    win_func = {
+        WindowingMethod.BARTHANN: scipy.signal.windows.barthann,
+        WindowingMethod.BARTLETT: np.bartlett,
+        WindowingMethod.BLACKMAN: np.blackman,
+        WindowingMethod.BLACKMAN_HARRIS: scipy.signal.windows.blackmanharris,
+        WindowingMethod.BOHMAN: scipy.signal.windows.bohman,
+        WindowingMethod.BOXCAR: scipy.signal.windows.boxcar,
+        WindowingMethod.COSINE: scipy.signal.windows.cosine,
+        WindowingMethod.EXPONENTIAL: scipy.signal.windows.exponential,
+        WindowingMethod.FLAT_TOP: scipy.signal.windows.flattop,
+        WindowingMethod.HAMMING: np.hamming,
+        WindowingMethod.HANN: np.hanning,
+        WindowingMethod.LANCZOS: scipy.signal.windows.lanczos,
+        WindowingMethod.NUTTALL: scipy.signal.windows.nuttall,
+        WindowingMethod.PARZEN: scipy.signal.windows.parzen,
+        WindowingMethod.TAYLOR: scipy.signal.windows.taylor,
+    }.get(method)
+    if win_func is not None:
+        return win_func
+    raise ValueError(f"Invalid window type {method.value}")
+
+
+def apply_window(
+    y: np.ndarray,
+    method: WindowingMethod = WindowingMethod.HAMMING,
+    alpha: float = 0.5,
+    beta: float = 14.0,
+    sigma: float = 7.0,
+) -> np.ndarray:
+    """Apply windowing to the input data.
+
+    Args:
+        x: X data.
+        y: Y data.
+        method: Windowing function. Defaults to "HAMMING".
+        alpha: Tukey window parameter. Defaults to 0.5.
+        beta: Kaiser window parameter. Defaults to 14.0.
+        sigma: Gaussian window parameter. Defaults to 7.0.
+
+    Returns:
+        Windowed Y data.
+
+    Raises:
+        ValueError: If the method is not recognized.
+    """
+    # Cases with parameters:
+    if method == WindowingMethod.GAUSSIAN:
+        return y * scipy.signal.windows.gaussian(len(y), sigma)
+    if method == WindowingMethod.KAISER:
+        return y * np.kaiser(len(y), beta)
+    if method == WindowingMethod.TUKEY:
+        return y * scipy.signal.windows.tukey(len(y), alpha)
+    # Cases without parameters:
+    win_func = get_window(method)
+    return y * win_func(len(y))

sigima/worker.py

@@ -0,0 +1,79 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Worker (:mod:`sigima.worker`)
+------------------------------
+
+This module provides a minimal interface for executing long-running operations
+with support for progress reporting and cancellation.
+
+It defines a generic protocol (`CallbackWorkerProtocol`) and a console-based
+implementation (`TextCallbackWorker`), suitable for non-GUI environments.
+
+Example:
+
+.. code-block:: python
+
+    from sigima.worker import TextCallbackWorker
+
+    def long_task(worker=None):
+        for i in range(10):
+            if worker and worker.was_canceled():
+                return None
+            worker.set_progress(i / 10)
+        return "done"
+
+    worker = TextCallbackWorker()
+    result = long_task(worker=worker)
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CallbackWorkerProtocol(Protocol):
+    """Protocol defining the minimal interface for progress/cancel-aware workers."""
+
+    def set_progress(self, value: float) -> None:
+        """Update progress (between 0.0 and 1.0)."""
+
+    def was_canceled(self) -> bool:
+        """Check whether the operation has been canceled."""
+
+
+class TextCallbackWorker:
+    """Minimal worker implementation for console-based environments.
+
+    Provides `set_progress()` and `was_canceled()` methods for use in long-running
+    computations. Intended for use in `sigima` where no GUI (e.g. Qt) is available.
+
+    Attributes:
+        _canceled: Whether the operation was canceled.
+        _progress: Most recent progress value.
+    """
+
+    def __init__(self) -> None:
+        self._canceled = False
+        self._progress = 0.0
+
+    def set_progress(self, value: float) -> None:
+        """Set the progress of the operation (prints to console).
+
+        Args:
+            value: Float between 0.0 and 1.0.
+        """
+        self._progress = min(max(value, 0.0), 1.0)
+        percent = int(self._progress * 100)
+        print(f"[sigima] Progress: {percent}%")
+
+    def was_canceled(self) -> bool:
+        """Return whether the operation has been canceled."""
+        return self._canceled
+
+    def cancel(self) -> None:
+        """Cancel the operation."""
+        self._canceled = True
+
+    def get_progress(self) -> float:
+        """Return the current progress value."""
+        return self._progress