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

sigima/proc/signal/base.py

@@ -0,0 +1,262 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Base signal processing functions and utilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from sigima.objects import NO_ROI, GeometryResult, KindShape, SignalObj
+from sigima.proc.base import dst_1_to_1
+
+
+def restore_data_outside_roi(dst: SignalObj, src: SignalObj) -> None:
+    """Restore data outside the Region Of Interest (ROI) of the input signal
+    after a computation, only if the input signal has a ROI,
+    and if the output signal has the same ROI as the input signal,
+    and if the data types are the same,
+    and if the shapes are the same.
+    Otherwise, do nothing.
+
+    Args:
+        dst: destination signal object
+        src: source signal object
+    """
+    if src.maskdata is not None and dst.maskdata is not None:
+        if (
+            np.array_equal(src.maskdata, dst.maskdata)
+            and dst.xydata.dtype == src.xydata.dtype
+            and dst.xydata.shape == src.xydata.shape
+        ):
+            dst.xydata[src.maskdata] = src.xydata[src.maskdata]
+
+
+def is_uncertainty_data_available(signals: SignalObj | list[SignalObj]) -> bool:
+    """Check if all signals have uncertainty data.
+
+    This functions is used to determine whether enough information is available to
+    propagate uncertainty.
+
+    Args:
+        signals: Signal object or list of signal objects.
+
+    Returns:
+        True if all signals have uncertainty data, False otherwise.
+    """
+    if isinstance(signals, SignalObj):
+        signals = [signals]
+    return all(sig.dy is not None for sig in signals)
+
+
+class Wrap1to1Func:
+    """Wrap a 1 array → 1 array function (the simple case of y1 = f(y0)) to produce
+    a 1 signal → 1 signal function, which can be used as a Sigima computation function
+    and inside DataLab's infrastructure to perform computations with the Signal
+    Processor object.
+
+    This wrapping mechanism using a class is necessary for the resulted function to be
+    pickable by the ``multiprocessing`` module.
+
+    The instance of this wrapper is callable and returns
+    a :class:`sigima.objects.SignalObj` object.
+
+    Example:
+
+        >>> import numpy as np
+        >>> from sigima.proc.signal import Wrap1to1Func
+        >>> import sigima.objects
+        >>> def square(y):
+        ...     return y**2
+        >>> compute_square = Wrap1to1Func(square)
+        >>> x = np.linspace(0, 10, 100)
+        >>> y = np.sin(x)
+        >>> sig0 = sigima.objects.create_signal("Example", x, y)
+        >>> sig1 = compute_square(sig0)
+
+    Args:
+        func: 1 array → 1 array function
+        *args: Additional positional arguments to pass to the function
+        **kwargs: Additional keyword arguments to pass to the function
+
+    .. note::
+
+        If `func_name` is provided in the keyword arguments, it will be used as the
+        function name instead of the default name derived from the function itself.
+
+    .. note::
+
+        This wrapper is suitable for functions that don't require custom uncertainty
+        propagation. For mathematical functions with specific uncertainty formulas
+        (sqrt, log10, exp, etc.), implement uncertainty propagation directly in the
+        computation function.
+    """
+
+    def __init__(self, func: Callable, *args: Any, **kwargs: Any) -> None:
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs
+        self.__name__ = self.kwargs.pop("func_name", func.__name__)
+        self.__doc__ = func.__doc__
+        self.__call__.__func__.__doc__ = self.func.__doc__
+
+    def __call__(self, src: SignalObj) -> SignalObj:
+        """Compute the function on the input signal and return the result signal
+
+        Args:
+            src: input signal object
+
+        Returns:
+            Result signal object
+        """
+        suffix = ", ".join(
+            [str(arg) for arg in self.args]
+            + [f"{k}={v}" for k, v in self.kwargs.items() if v is not None]
+        )
+        dst = dst_1_to_1(src, self.__name__, suffix)
+        x, y = src.get_data()
+        # Apply function and propagate uncertainty unchanged
+        dst.set_xydata(x, self.func(y, *self.args, **self.kwargs), src.dx, src.dy)
+
+        restore_data_outside_roi(dst, src)
+        return dst
+
+
+def signals_to_array(
+    signals: list[SignalObj], attr: str = "y", dtype: np.dtype | None = None
+) -> np.ndarray:
+    """Create an array from a list of signals.
+
+    Args:
+        signals: List of signal objects.
+        attr: Name of the attribute to extract ("y", "dy", etc.). Defaults to "y".
+        dtype: Desired type for the output array. If None, use the first signal's dtype.
+
+    Returns:
+        A NumPy array stacking the specified attribute from all signals.
+
+    Raises:
+        ValueError: If the signals list is empty.
+    """
+    if not signals:
+        raise ValueError("The signal list is empty.")
+    if dtype is None:
+        dtype = getattr(signals[0], attr).dtype
+    arr = np.array([getattr(sig, attr) for sig in signals], dtype=dtype)
+    return arr
+
+
+def signals_y_to_array(
+    signals: SignalObj | list[SignalObj], dtype: np.dtype | None = None
+) -> np.ndarray:
+    """Create an array from a list of signals, extracting the `y` attribute.
+
+    Args:
+        signals: List of signal objects.
+        dtype: Desired type for the output array. If None, use the first signal's dtype.
+
+    Returns:
+        A NumPy array stacking the `y` attribute from all signals.
+    """
+    if isinstance(signals, SignalObj):
+        signals = [signals]
+    return signals_to_array(signals, attr="y", dtype=dtype)
+
+
+def signals_dy_to_array(
+    signals: SignalObj | list[SignalObj], dtype: np.dtype | None = None
+) -> np.ndarray:
+    """Create an array from a list of signals, extracting the `dy` attribute.
+
+    Args:
+        signals: List of signal objects.
+        dtype: Desired type for the output array. If None, use the first signal's dtype.
+
+    Returns:
+        A NumPy array stacking the `dy` attribute from all signals.
+    """
+    if isinstance(signals, SignalObj):
+        signals = [signals]
+    return signals_to_array(signals, attr="dy", dtype=dtype)
+
+
+def compute_geometry_from_obj(
+    title: str,
+    shape: str,
+    obj: SignalObj,
+    func: Callable,
+    *args: Any,
+) -> GeometryResult | None:
+    """Calculate result geometry by executing a computation function on a signal object.
+
+    Args:
+        title: Result title
+        shape: Result shape kind (e.g., "segment", "point")
+        obj: Input signal object
+        func: Computation function that takes (x, y, ``*args``) and returns coordinates
+        *args: Additional computation function arguments
+
+    Returns:
+        Result geometry object or None if no result is found
+
+    .. note::
+
+        The computation function must take x and y arrays as the first two arguments,
+        followed by any additional arguments, and return a NumPy array containing
+        coordinate pairs in the form ``[[x0, y0], [x1, y1], ...]``.
+    """
+    rows: list[np.ndarray] = []
+    roi_idx: list[int] = []
+
+    for i_roi in obj.iterate_roi_indices():
+        x, y = obj.get_data(i_roi)
+        if args:
+            results: np.ndarray = func(x, y, *args)
+        else:
+            results: np.ndarray = func(x, y)
+
+        if results is None:
+            continue
+
+        results = np.array(results, dtype=float)
+        if results.size == 0:
+            continue
+
+        # Ensure results are in the correct 2D format
+        if results.ndim == 1:
+            # For segment shapes, expect 4 coordinates: [x0, y0, x1, y1]
+            if shape == "segment" and len(results) == 4:
+                results = results.reshape(1, 4)
+            elif len(results) % 2 == 0:
+                # Reshape flat coordinate array to pairs for points
+                results = results.reshape(-1, 2)
+            else:
+                continue  # Skip malformed results
+        elif results.ndim != 2 or results.shape[1] < 2:
+            continue  # Skip malformed results
+
+        rows.append(results)
+        roi_idx.extend([NO_ROI if i_roi is None else int(i_roi)] * results.shape[0])
+
+    if not rows:
+        return None
+
+    coords = np.vstack(rows)
+    if shape == "segment":
+        shape_kind = KindShape.SEGMENT
+    elif shape == "point":
+        shape_kind = KindShape.POINT
+    else:
+        shape_kind = KindShape.POINT  # Default fallback
+
+    return GeometryResult(
+        title=title,
+        kind=shape_kind,
+        coords=coords,
+        roi_indices=np.array(roi_idx, dtype=int),
+    )

sigima/proc/signal/extraction.py

@@ -0,0 +1,60 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Signal extraction and ROI operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sigima.objects import ROI1DParam, SignalObj
+from sigima.proc.base import dst_1_to_1
+from sigima.proc.decorator import computation_function
+
+
+@computation_function()
+def extract_rois(src: SignalObj, params: list[ROI1DParam]) -> SignalObj:
+    """Extract multiple regions of interest from data
+
+    Args:
+        src: source signal
+        params: list of ROI parameters
+
+    Returns:
+        Signal with multiple regions of interest
+    """
+    suffix = None
+    if len(params) == 1:
+        p: ROI1DParam = params[0]
+        suffix = f"{p.xmin:.3g}≤x≤{p.xmax:.3g}"
+    dst = dst_1_to_1(src, "extract_rois", suffix)
+    x, y = src.get_data()
+    xout, yout = np.ones_like(x) * np.nan, np.ones_like(y) * np.nan
+    for p in params:
+        idx1, idx2 = np.searchsorted(x, p.xmin), np.searchsorted(x, p.xmax)
+        slice0 = slice(idx1, idx2)
+        xout[slice0], yout[slice0] = x[slice0], y[slice0]
+    nans = np.isnan(xout) | np.isnan(yout)
+    # TODO: Handle uncertainty data
+    dst.set_xydata(xout[~nans], yout[~nans])
+    return dst
+
+
+@computation_function()
+def extract_roi(src: SignalObj, p: ROI1DParam) -> SignalObj:
+    """Extract single region of interest from data
+
+    Args:
+        src: source signal
+        p: ROI parameters
+
+    Returns:
+        Signal with single region of interest
+    """
+    dst = dst_1_to_1(src, "extract_roi", f"{p.xmin:.3g}≤x≤{p.xmax:.3g}")
+    x, y = p.get_data(src).copy()
+    # TODO: Handle uncertainty data
+    dst.set_xydata(x, y)
+    return dst

sigima/proc/signal/features.py

@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see sigima/LICENSE for details)
+
+"""
+Feature extraction and analysis functions
+=========================================
+
+This module provides feature extraction and analysis functions for signal objects:
+
+- Peak detection
+- Full Width at Half Maximum (FWHM) and related measurements
+- Statistical analysis
+- Bandwidth calculations
+- Dynamic parameters (ENOB, SNR, SINAD, THD, SFDR)
+
+.. note::
+
+    Most operations use functions from :mod:`sigima.tools.signal` for actual
+    computations.
+"""
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+import numpy as np
+import scipy.integrate as spt
+
+from sigima.config import _
+from sigima.enums import PowerUnit
+from sigima.objects import (
+    GeometryResult,
+    SignalObj,
+    TableKind,
+    TableResult,
+    TableResultBuilder,
+)
+from sigima.proc.base import dst_1_to_1
+from sigima.proc.decorator import computation_function
+from sigima.proc.signal.base import compute_geometry_from_obj
+from sigima.tools.signal import dynamic, features, peakdetection, pulse
+
+
+class PeakDetectionParam(gds.DataSet, title=_("Peak detection")):
+    """Peak detection parameters"""
+
+    threshold = gds.FloatItem(_("Threshold"), default=0.1, min=0.0)
+    min_dist = gds.IntItem(_("Minimum distance"), default=1, min=1)
+
+
+@computation_function()
+def peak_detection(src: SignalObj, p: PeakDetectionParam) -> SignalObj:
+    """Peak detection with
+    :py:func:`sigima.tools.signal.peakdetection.peak_indices`
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(
+        src, "peak_detection", f"threshold={p.threshold}%, min_dist={p.min_dist}pts"
+    )
+    x, y = src.get_data()
+    indices = peakdetection.peak_indices(
+        y, thres=p.threshold * 0.01, min_dist=p.min_dist
+    )
+    dst.set_xydata(x[indices], y[indices])
+    dst.set_metadata_option("curvestyle", "Sticks")
+    return dst
+
+
+class FWHMParam(gds.DataSet, title=_("FWHM")):
+    """FWHM parameters"""
+
+    methods = (
+        ("zero-crossing", _("Zero-crossing")),
+        ("gauss", _("Gaussian fit")),
+        ("lorentz", _("Lorentzian fit")),
+        ("voigt", _("Voigt fit")),
+    )
+    method = gds.ChoiceItem(_("Method"), methods, default="zero-crossing")
+    xmin = gds.FloatItem(
+        "X<sub>MIN</sub>",
+        default=None,
+        check=False,
+        help=_("Lower X boundary (empty for no limit, i.e. start of the signal)"),
+    )
+    xmax = gds.FloatItem(
+        "X<sub>MAX</sub>",
+        default=None,
+        check=False,
+        help=_("Upper X boundary (empty for no limit, i.e. end of the signal)"),
+    )
+
+
+@computation_function()
+def fwhm(obj: SignalObj, param: FWHMParam) -> GeometryResult | None:
+    """Compute FWHM with :py:func:`sigima.tools.signal.pulse.fwhm`
+
+    Args:
+        obj: source signal
+        param: parameters
+
+    Returns:
+        Segment coordinates
+    """
+    return compute_geometry_from_obj(
+        "fwhm",
+        "segment",
+        obj,
+        pulse.fwhm,
+        param.method,
+        param.xmin,
+        param.xmax,
+    )
+
+
+@computation_function()
+def fw1e2(obj: SignalObj) -> GeometryResult | None:
+    """Compute FW at 1/e² with :py:func:`sigima.tools.signal.pulse.fw1e2`
+
+    Args:
+        obj: source signal
+
+    Returns:
+        Segment coordinates
+    """
+    return compute_geometry_from_obj("fw1e2", "segment", obj, pulse.fw1e2)
+
+
+class OrdinateParam(gds.DataSet, title=_("Ordinate")):
+    """Ordinate parameter."""
+
+    y = gds.FloatItem(_("Ordinate"), default=0.0)
+
+
+@computation_function()
+def full_width_at_y(obj: SignalObj, p: OrdinateParam) -> GeometryResult | None:
+    """
+    Compute full width at a given y value for a signal object.
+
+    Args:
+        obj: The signal object containing x and y data.
+        p: The ordinate parameter dataset
+
+    Returns:
+        Segment coordinates
+    """
+    return compute_geometry_from_obj("∆X", "segment", obj, pulse.full_width_at_y, p.y)
+
+
+def _find_first_x_at_y_value(xy: np.ndarray, y_target: float) -> float:
+    """Find the first x value where :math:`y = f(x)` equals the value :math:`y_target`.
+
+    Args:
+        xy: Tuple of (x, y) data arrays.
+        y_target: Target y value.
+
+    Returns:
+        The first interpolated x value at the given :math:`y_target`,
+        or `nan` if none found.
+    """
+    x_values = features.find_x_values_at_y(xy[0], xy[1], y_target)
+    return x_values[0] if len(x_values) > 0 else np.nan
+
+
+@computation_function()
+def x_at_y(obj: SignalObj, p: OrdinateParam) -> TableResult:
+    """
+    Compute the smallest x-value at a given y-value for a signal object.
+
+    Args:
+        obj: The signal object containing x and y data.
+        p: The parameter dataset for finding the abscissa.
+
+    Returns:
+         An object containing the x-value.
+    """
+    table = TableResultBuilder(f"x|y={p.y}")
+    table.add(lambda xy: _find_first_x_at_y_value(xy, p.y), "x@y")
+    return table.compute(obj)
+
+
+class AbscissaParam(gds.DataSet, title=_("Abscissa")):
+    """Abscissa parameter."""
+
+    x = gds.FloatItem(_("Abscissa"), default=0.0)
+
+
+@computation_function()
+def y_at_x(obj: SignalObj, p: AbscissaParam) -> TableResult:
+    """
+    Compute the smallest y-value at a given x-value for a signal object.
+
+    Args:
+        obj: The signal object containing x and y data.
+        p: The parameter dataset for finding the ordinate.
+
+    Returns:
+         An object containing the y-value.
+    """
+    table = TableResultBuilder(f"y|x={p.x}")
+    table.add(lambda xy: features.find_y_at_x_value(xy[0], xy[1], p.x), "y@x")
+    return table.compute(obj)
+
+
+@computation_function()
+def stats(obj: SignalObj) -> TableResult:
+    """Compute statistics on a signal
+
+    Args:
+        obj: source signal
+
+    Returns:
+        Result properties object
+    """
+    table = TableResultBuilder(_("Signal statistics"), kind=TableKind.STATISTICS)
+    table.add(lambda xy: np.nanmin(xy[1]), "min")
+    table.add(lambda xy: np.nanmax(xy[1]), "max")
+    table.add(lambda xy: np.nanmean(xy[1]), "mean")
+    table.add(lambda xy: np.nanmedian(xy[1]), "median")
+    table.add(lambda xy: np.nanstd(xy[1]), "std")
+    table.add(lambda xy: np.nanmean(xy[1]) / np.nanstd(xy[1]), "snr")
+    table.add(lambda xy: np.nanmax(xy[1]) - np.nanmin(xy[1]), "ptp")
+    table.add(lambda xy: np.nansum(xy[1]), "sum")
+    table.add(lambda xy: spt.trapezoid(xy[1], xy[0]), "trapz")
+    return table.compute(obj)
+
+
+@computation_function()
+def bandwidth_3db(obj: SignalObj) -> GeometryResult | None:
+    """Compute bandwidth at -3 dB with
+    :py:func:`sigima.tools.signal.misc.bandwidth`
+
+    .. note::
+
+       The bandwidth is defined as the range of frequencies over which the signal
+       maintains a certain level relative to its peak.
+
+    .. warning::
+
+        The signal is assumed to be smooth enough for the bandwidth calculation to be
+        meaningful. If the signal contains excessive noise, multiple peaks, or is not
+        sufficiently continuous, the computed bandwidth may not accurately represent the
+        true -3dB range. It is recommended to preprocess the signal to ensure reliable
+        results.
+
+    Args:
+        obj: Source signal.
+
+    Returns:
+        Result shape with bandwidth.
+    """
+    return compute_geometry_from_obj(
+        "bandwidth", "segment", obj, features.find_bandwidth_coordinates, -3.0
+    )
+
+
+class DynamicParam(gds.DataSet, title=_("Dynamic parameters")):
+    """Parameters for dynamic range computation (ENOB, SNR, SINAD, THD, SFDR)"""
+
+    full_scale = gds.FloatItem(_("Full scale"), default=0.16, min=0.0, unit="V")
+    unit = gds.ChoiceItem(
+        _("Unit"),
+        [(PowerUnit.DBC, "dBc"), (PowerUnit.DBFS, "dBFS")],
+        default=PowerUnit.DBC,
+        help=_("Unit for SINAD"),
+    )
+    nb_harm = gds.IntItem(
+        _("Number of harmonics"),
+        default=5,
+        min=1,
+        help=_("Number of harmonics to consider for THD"),
+    )
+
+
+@computation_function()
+def dynamic_parameters(src: SignalObj, p: DynamicParam) -> TableResult:
+    """Compute Dynamic parameters
+    using the following functions:
+
+    - Freq: :py:func:`sigima.tools.signal.dynamic.sinus_frequency`
+    - ENOB: :py:func:`sigima.tools.signal.dynamic.enob`
+    - SNR: :py:func:`sigima.tools.signal.dynamic.snr`
+    - SINAD: :py:func:`sigima.tools.signal.dynamic.sinad`
+    - THD: :py:func:`sigima.tools.signal.dynamic.thd`
+    - SFDR: :py:func:`sigima.tools.signal.dynamic.sfdr`
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result properties with ENOB, SNR, SINAD, THD, SFDR
+    """
+    unit: PowerUnit = p.unit
+    table = TableResultBuilder(_("Dynamic parameters"))
+    table.add(lambda xy: dynamic.sinus_frequency(xy[0], xy[1]), "freq")
+    table.add(lambda xy: dynamic.enob(xy[0], xy[1], p.full_scale), "enob")
+    table.add(lambda xy: dynamic.snr(xy[0], xy[1], unit), "snr")
+    table.add(lambda xy: dynamic.sinad(xy[0], xy[1], unit), "sinad")
+    table.add(
+        lambda xy: dynamic.thd(xy[0], xy[1], p.full_scale, unit, p.nb_harm), "thd"
+    )
+    table.add(lambda xy: dynamic.sfdr(xy[0], xy[1], p.full_scale, unit), "sfdr")
+    return table.compute(src)