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

sigima/proc/signal/__init__.py

@@ -0,0 +1,376 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Basic signal processing
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.base
+   :members:
+   :no-index:
+
+Arithmetic
+~~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.arithmetic
+    :members:
+    :no-index:
+
+Mathematical Operations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.mathops
+    :members:
+    :no-index:
+
+Extraction
+~~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.extraction
+    :members:
+    :no-index:
+
+Filtering
+~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.filtering
+    :members:
+    :no-index:
+
+Processing
+~~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.processing
+    :members:
+    :no-index:
+
+Fourier
+~~~~~~~
+
+.. automodule:: sigima.proc.signal.fourier
+    :members:
+    :no-index:
+
+Fitting
+~~~~~~~
+
+.. automodule:: sigima.proc.signal.fitting
+    :members:
+    :no-index:
+
+Features
+~~~~~~~~
+
+.. automodule:: sigima.proc.signal.features
+    :members:
+    :no-index:
+
+Stability
+~~~~~~~~~
+
+.. automodule:: sigima.proc.signal.stability
+    :members:
+    :no-index:
+
+Analysis
+~~~~~~~~
+
+.. automodule:: sigima.proc.signal.analysis
+    :members:
+    :no-index:
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+# MARK: Important notes
+# ---------------------
+# - All `guidata.dataset.DataSet` classes must also be imported
+#   in the `sigima.params` module.
+# - All functions decorated by `computation_function` defined in the other modules
+#   of this package must be imported right here.
+
+from __future__ import annotations
+
+# Import parameter classes from the main base module
+from sigima.proc.signal.analysis import (
+    PulseFeaturesParam,
+    contrast,
+    extract_pulse_features,
+    histogram,
+    sampling_rate_period,
+    x_at_minmax,
+)
+from sigima.proc.signal.arithmetic import (
+    addition,
+    addition_constant,
+    arithmetic,
+    average,
+    difference,
+    difference_constant,
+    division,
+    division_constant,
+    product,
+    product_constant,
+    quadratic_difference,
+    signals_to_array,
+    signals_to_image,
+    standard_deviation,
+)
+from sigima.proc.signal.base import (
+    Wrap1to1Func,
+    compute_geometry_from_obj,
+    is_uncertainty_data_available,
+    restore_data_outside_roi,
+    signals_dy_to_array,
+    signals_y_to_array,
+)
+from sigima.proc.signal.extraction import (
+    extract_roi,
+    extract_rois,
+)
+from sigima.proc.signal.features import (
+    AbscissaParam,
+    DynamicParam,
+    FWHMParam,
+    OrdinateParam,
+    PeakDetectionParam,
+    bandwidth_3db,
+    dynamic_parameters,
+    full_width_at_y,
+    fw1e2,
+    fwhm,
+    peak_detection,
+    stats,
+    x_at_y,
+    y_at_x,
+)
+from sigima.proc.signal.filtering import (
+    BandPassFilterParam,
+    BandStopFilterParam,
+    BaseHighLowBandParam,
+    FrequencyFilterMethod,
+    HighPassFilterParam,
+    LowPassFilterParam,
+    PadLocation1D,
+    add_gaussian_noise,
+    add_poisson_noise,
+    add_uniform_noise,
+    bandpass,
+    bandstop,
+    frequency_filter,
+    gaussian_filter,
+    highpass,
+    lowpass,
+    moving_average,
+    moving_median,
+    wiener,
+)
+from sigima.proc.signal.fitting import (
+    PolynomialFitParam,
+    cdf_fit,
+    evaluate_fit,
+    exponential_fit,
+    extract_fit_params,
+    gaussian_fit,
+    linear_fit,
+    lorentzian_fit,
+    piecewiseexponential_fit,
+    planckian_fit,
+    polynomial_fit,
+    sigmoid_fit,
+    sinusoidal_fit,
+    twohalfgaussian_fit,
+    voigt_fit,
+)
+from sigima.proc.signal.fourier import (
+    ZeroPadding1DParam,
+    fft,
+    ifft,
+    magnitude_spectrum,
+    phase_spectrum,
+    psd,
+    zero_padding,
+)
+from sigima.proc.signal.mathops import (
+    DataTypeSParam,
+    PowerParam,
+    absolute,
+    astype,
+    complex_from_magnitude_phase,
+    complex_from_real_imag,
+    exp,
+    imag,
+    inverse,
+    log10,
+    phase,
+    power,
+    real,
+    sqrt,
+    to_cartesian,
+    to_polar,
+    transpose,
+)
+from sigima.proc.signal.processing import (
+    DetrendingParam,
+    InterpolationParam,
+    Resampling1DParam,
+    WindowingParam,
+    XYCalibrateParam,
+    apply_window,
+    calibration,
+    check_same_sample_rate,
+    clip,
+    convolution,
+    deconvolution,
+    derivative,
+    detrending,
+    get_nyquist_frequency,
+    integral,
+    interpolate,
+    normalize,
+    offset_correction,
+    resampling,
+    reverse_x,
+    xy_mode,
+)
+from sigima.proc.signal.stability import (
+    AllanVarianceParam,
+    allan_deviation,
+    allan_variance,
+    hadamard_variance,
+    modified_allan_variance,
+    overlapping_allan_variance,
+    time_deviation,
+    total_variance,
+)
+
+__all__ = [
+    "AbscissaParam",
+    "AllanVarianceParam",
+    "BandPassFilterParam",
+    "BandStopFilterParam",
+    "BaseHighLowBandParam",
+    "DataTypeSParam",
+    "DetrendingParam",
+    "DynamicParam",
+    "FWHMParam",
+    "FrequencyFilterMethod",
+    "HighPassFilterParam",
+    "InterpolationParam",
+    "LowPassFilterParam",
+    "OrdinateParam",
+    "PadLocation1D",
+    "PeakDetectionParam",
+    "PolynomialFitParam",
+    "PowerParam",
+    "PulseFeaturesParam",
+    "Resampling1DParam",
+    "WindowingParam",
+    "Wrap1to1Func",
+    "XYCalibrateParam",
+    "ZeroPadding1DParam",
+    "absolute",
+    "add_gaussian_noise",
+    "add_poisson_noise",
+    "add_uniform_noise",
+    "addition",
+    "addition_constant",
+    "allan_deviation",
+    "allan_variance",
+    "apply_window",
+    "arithmetic",
+    "astype",
+    "average",
+    "bandpass",
+    "bandstop",
+    "bandwidth_3db",
+    "calibration",
+    "cdf_fit",
+    "check_same_sample_rate",
+    "clip",
+    "complex_from_magnitude_phase",
+    "complex_from_real_imag",
+    "compute_geometry_from_obj",
+    "contrast",
+    "convolution",
+    "deconvolution",
+    "derivative",
+    "detrending",
+    "difference",
+    "difference_constant",
+    "division",
+    "division_constant",
+    "dynamic_parameters",
+    "evaluate_fit",
+    "exp",
+    "exponential_fit",
+    "extract_fit_params",
+    "extract_pulse_features",
+    "extract_roi",
+    "extract_rois",
+    "fft",
+    "frequency_filter",
+    "full_width_at_y",
+    "fw1e2",
+    "fwhm",
+    "gaussian_filter",
+    "gaussian_fit",
+    "get_nyquist_frequency",
+    "hadamard_variance",
+    "highpass",
+    "histogram",
+    "ifft",
+    "imag",
+    "integral",
+    "interpolate",
+    "inverse",
+    "is_uncertainty_data_available",
+    "linear_fit",
+    "log10",
+    "lorentzian_fit",
+    "lowpass",
+    "magnitude_spectrum",
+    "modified_allan_variance",
+    "moving_average",
+    "moving_median",
+    "normalize",
+    "offset_correction",
+    "overlapping_allan_variance",
+    "peak_detection",
+    "phase",
+    "phase_spectrum",
+    "piecewiseexponential_fit",
+    "planckian_fit",
+    "polynomial_fit",
+    "power",
+    "product",
+    "product_constant",
+    "psd",
+    "quadratic_difference",
+    "real",
+    "resampling",
+    "restore_data_outside_roi",
+    "reverse_x",
+    "sampling_rate_period",
+    "sigmoid_fit",
+    "signals_dy_to_array",
+    "signals_to_array",
+    "signals_to_image",
+    "signals_y_to_array",
+    "sinusoidal_fit",
+    "sqrt",
+    "standard_deviation",
+    "stats",
+    "time_deviation",
+    "to_cartesian",
+    "to_polar",
+    "total_variance",
+    "transpose",
+    "twohalfgaussian_fit",
+    "voigt_fit",
+    "wiener",
+    "x_at_minmax",
+    "x_at_y",
+    "xy_mode",
+    "y_at_x",
+    "zero_padding",
+]

sigima/proc/signal/analysis.py

@@ -0,0 +1,206 @@
+# -*- coding: utf-8 -*-
+# Licensed under the terms of the BSD 3-Clause
+# (see sigima/LICENSE for details)
+
+"""
+General analysis functions
+==========================
+
+This module provides general analysis functions for signal objects:
+
+- Histogram computation
+- Other analysis operations
+
+.. note::
+
+    Most operations use standard NumPy/SciPy functions or custom analysis routines.
+"""
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+import numpy as np
+
+from sigima.config import _
+from sigima.objects import (
+    SignalObj,
+    TableKind,
+    TableResult,
+    TableResultBuilder,
+)
+from sigima.proc.base import HistogramParam, new_signal_result
+from sigima.proc.decorator import computation_function
+from sigima.tools.signal import dynamic, features, pulse
+
+
+@computation_function()
+def histogram(src: SignalObj, p: HistogramParam) -> SignalObj:
+    """Compute histogram with :py:func:`numpy.histogram`
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    data = src.get_masked_view().compressed()
+    suffix = p.get_suffix(data)  # Also updates p.lower and p.upper
+
+    # Compute histogram:
+    y, bin_edges = np.histogram(data, bins=p.bins, range=(p.lower, p.upper))
+    x = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+    # Note: we use the `new_signal_result` function to create the result signal object
+    # because the `dst_1_to_1` would copy the source signal, which is not what we want
+    # here (we want a brand new signal object).
+    dst = new_signal_result(
+        src,
+        "histogram",
+        suffix=suffix,
+        units=(src.yunit, ""),
+        labels=(src.ylabel, _("Counts")),
+    )
+    dst.set_xydata(x, y)
+    dst.set_metadata_option("shade", 0.5)
+    dst.set_metadata_option("curvestyle", "Steps")
+    return dst
+
+
+class PulseFeaturesParam(gds.DataSet, title=_("Pulse features")):
+    """Pulse features parameters."""
+
+    signal_shape = gds.ChoiceItem(
+        _("Signal shape"),
+        [
+            (None, _("Auto")),
+            ("step", _("Step")),
+            ("square", _("Square")),
+        ],
+        default=None,
+        help=_("Signal type: auto-detect, step, or square."),
+    )
+    xstartmin = gds.FloatItem(
+        _("Start baseline min"),
+        default=0.0,
+        help=_("Lower X boundary for the start baseline"),
+    )
+    xstartmax = gds.FloatItem(
+        _("Start baseline max"),
+        default=0.0,
+        help=_("Upper X boundary for the start baseline"),
+    )
+    xendmin = gds.FloatItem(
+        _("End baseline min"),
+        default=1.0,
+        help=_("Lower X boundary for the end baseline"),
+    )
+    xendmax = gds.FloatItem(
+        _("End baseline max"),
+        default=1.0,
+        help=_("Upper X boundary for the end baseline"),
+    )
+    reference_levels = gds.ChoiceItem(
+        _("Rise/Fall time"),
+        [
+            ((5, 95), _("5% - 95% (High precision)")),
+            ((10, 90), _("10% - 90% (IEEE standard)")),
+            ((20, 80), _("20% - 80% (Noisy signals)")),
+            ((25, 75), _("25% - 75% (Alternative)")),
+        ],
+        default=(10, 90),
+        help=_(
+            "Reference levels for rise/fall time measurement. "
+            "10%-90% is the IEEE standard for digital signal analysis."
+        ),
+    )
+
+    def update_from_obj(self, obj: SignalObj) -> None:
+        """Update parameters from a signal object."""
+        self.xstartmin, self.xstartmax = pulse.get_start_range(obj.x)
+        self.xendmin, self.xendmax = pulse.get_end_range(obj.x)
+
+
+@computation_function()
+def extract_pulse_features(obj: SignalObj, p: PulseFeaturesParam) -> TableResult:
+    """Extract pulse features.
+
+    Args:
+        obj: The signal object from which to extract features.
+        p: The pulse features parameters.
+
+    Returns:
+        An object containing the pulse features.
+    """
+    start_ratio, stop_ratio = p.reference_levels
+
+    def func_extract_pulse_features(xydata: tuple[np.ndarray, np.ndarray]):
+        """Extract pulse features (internal function).
+
+        Args:
+            xydata: Tuple of (x, y) data arrays
+
+        Returns:
+            Pulse features dataclass
+        """
+        return pulse.extract_pulse_features(
+            xydata[0],
+            xydata[1],
+            signal_shape=p.signal_shape,
+            start_range=[p.xstartmin, p.xstartmax],
+            end_range=[p.xendmin, p.xendmax],
+            start_ratio=start_ratio / 100.0,
+            stop_ratio=stop_ratio / 100.0,
+        )
+
+    builder = TableResultBuilder(_("Pulse features"), kind=TableKind.PULSE_FEATURES)
+    builder.set_global_function(func_extract_pulse_features)
+    builder.hide_columns(
+        ["xstartmin", "xstartmax", "xendmin", "xendmax", "xplateaumin", "xplateaumax"]
+    )
+    return builder.compute(obj)
+
+
+@computation_function()
+def sampling_rate_period(obj: SignalObj) -> TableResult:
+    """Compute sampling rate and period
+    using the following functions:
+
+    - fs: :py:func:`sigima.tools.signal.dynamic.sampling_rate`
+    - T: :py:func:`sigima.tools.signal.dynamic.sampling_period`
+
+    Args:
+        obj: source signal
+
+    Returns:
+        Result properties with sampling rate and period
+    """
+    table = TableResultBuilder(_("Sampling rate and period"))
+    table.add(lambda xy: dynamic.sampling_rate(xy[0]), "fs")
+    table.add(lambda xy: dynamic.sampling_period(xy[0]), "T")
+    return table.compute(obj)
+
+
+@computation_function()
+def contrast(obj: SignalObj) -> TableResult:
+    """Compute contrast with :py:func:`sigima.tools.signal.misc.contrast`"""
+    table = TableResultBuilder(_("Contrast"))
+    table.add(lambda xy: features.contrast(xy[1]), "contrast")
+    return table.compute(obj)
+
+
+@computation_function()
+def x_at_minmax(obj: SignalObj) -> TableResult:
+    """
+    Compute the smallest argument at the minima and the smallest argument at the maxima.
+
+    Args:
+        obj: The signal object.
+
+    Returns:
+        An object containing the x-values at the minima and the maxima.
+    """
+    table = TableResultBuilder(_("X at min/max"))
+    table.add(lambda xy: xy[0][np.argmin(xy[1])], "X@Ymin")
+    table.add(lambda xy: xy[0][np.argmax(xy[1])], "X@Ymax")
+    return table.compute(obj)