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

sigima/proc/signal/stability.py

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see sigima/LICENSE for details)
+
+"""
+Stability analysis functions
+============================
+
+This module provides stability analysis functions for signal objects:
+
+- Allan variance and deviation
+- Overlapping Allan variance
+- Modified Allan variance
+- Hadamard variance
+- Total variance
+
+.. note::
+
+    All operations use functions from :mod:`sigima.tools.signal.stability` for
+    actual computations.
+"""
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+import numpy as np
+
+from sigima.config import _
+from sigima.objects import SignalObj
+from sigima.proc.decorator import computation_function
+from sigima.tools.signal import stability
+
+from .base import dst_1_to_1
+
+
+class AllanVarianceParam(gds.DataSet, title=_("Allan variance")):
+    """Allan variance parameters"""
+
+    max_tau = gds.IntItem("Max τ", default=100, min=1, unit="pts")
+
+
+@computation_function()
+def allan_variance(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Allan variance with
+    :py:func:`sigima.tools.signal.stability.allan_variance`.
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "allan_variance", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    avar = stability.allan_variance(x, y, tau_values)
+    dst.set_xydata(tau_values, avar)
+    return dst
+
+
+@computation_function()
+def allan_deviation(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Allan deviation with
+    :py:func:`sigima.tools.signal.stability.allan_deviation`
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "allan_deviation", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    adev = stability.allan_deviation(x, y, tau_values)
+    dst.set_xydata(tau_values, adev)
+    return dst
+
+
+@computation_function()
+def overlapping_allan_variance(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Overlapping Allan variance.
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "overlapping_allan_variance", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    oavar = stability.overlapping_allan_variance(x, y, tau_values)
+    dst.set_xydata(tau_values, oavar)
+    return dst
+
+
+@computation_function()
+def modified_allan_variance(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Modified Allan variance.
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "modified_allan_variance", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    mavar = stability.modified_allan_variance(x, y, tau_values)
+    dst.set_xydata(tau_values, mavar)
+    return dst
+
+
+@computation_function()
+def hadamard_variance(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Hadamard variance.
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "hadamard_variance", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    hvar = stability.hadamard_variance(x, y, tau_values)
+    dst.set_xydata(tau_values, hvar)
+    return dst
+
+
+@computation_function()
+def total_variance(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Total variance.
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "total_variance", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    tvar = stability.total_variance(x, y, tau_values)
+    dst.set_xydata(tau_values, tvar)
+    return dst
+
+
+@computation_function()
+def time_deviation(src: SignalObj, p: AllanVarianceParam) -> SignalObj:
+    """Compute Time Deviation (TDEV).
+
+    Args:
+        src: source signal
+        p: parameters
+
+    Returns:
+        Result signal object
+    """
+    dst = dst_1_to_1(src, "time_deviation", f"max_tau={p.max_tau}")
+    x, y = src.get_data()
+    tau_values = np.arange(1, p.max_tau + 1)
+    tdev = stability.time_deviation(x, y, tau_values)
+    dst.set_xydata(tau_values, tdev)
+    return dst

sigima/proc/title_formatting.py

@@ -0,0 +1,227 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Title formatting system for computation results
+-----------------------------------------------
+
+This module provides a configurable title formatting system for computation results.
+It allows different applications (Sigima vs DataLab) to use different title formatting
+strategies while maintaining compatibility.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from sigima.objects.base import BaseObj
+
+__all__ = [
+    "PlaceholderTitleFormatter",
+    "SimpleTitleFormatter",
+    "TitleFormatter",
+    "get_default_title_formatter",
+    "set_default_title_formatter",
+]
+
+
+@runtime_checkable
+class TitleFormatter(Protocol):
+    """Protocol for title formatting strategies used in computation functions.
+
+    This protocol allows different title formatting approaches:
+    - Simple descriptive titles for Sigima-only usage
+    - Placeholder-based titles for DataLab integration
+    - Custom formatting for specific use cases
+    """
+
+    def format_1_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 1-to-1 computation (single input → single output).
+
+        Args:
+            name: Name of the computation function
+            suffix: Optional suffix to add to the title
+
+        Returns:
+            Formatted title string
+        """
+
+    def format_n_to_1_title(
+        self, name: str, n_inputs: int, suffix: str | None = None
+    ) -> str:
+        """Format title for n-to-1 computation (multiple inputs → single output).
+
+        Args:
+            name: Name of the computation function
+            n_inputs: Number of input objects
+            suffix: Optional suffix to add to the title
+
+        Returns:
+            Formatted title string
+        """
+
+    def format_2_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 2-to-1 computation (two inputs → single output).
+
+        Args:
+            name: Name of the computation function
+            suffix: Optional suffix to add to the title
+
+        Returns:
+            Formatted title string
+        """
+
+    def resolve_placeholder_title(
+        self,
+        title: str,
+        source_objects: list[BaseObj],
+    ) -> str:
+        """Resolve placeholder title with actual object references.
+
+        This method takes a title with placeholders (e.g., "wiener({0})")
+        and replaces them with actual object identifiers.
+
+        Args:
+            title: Title containing placeholders
+            source_objects: List of source objects to use for replacement
+
+        Returns:
+            Title with placeholders resolved
+        """
+
+
+class SimpleTitleFormatter:
+    """Simple descriptive title formatter for Sigima-only usage.
+
+    Creates human-readable titles without placeholders, suitable for
+    standalone Sigima usage where object relationships are less critical.
+    """
+
+    def format_1_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 1-to-1 computation."""
+        if len(name) == 1:  # This is an operator
+            base_title = f"operator_{name}"
+        else:
+            # Convert function names to human-readable format
+            readable_name = name.replace("_", " ").title()
+            base_title = f"{readable_name} Result"
+
+        if suffix:
+            base_title += f" ({suffix})"
+        return base_title
+
+    def format_n_to_1_title(
+        self, name: str, n_inputs: int, suffix: str | None = None
+    ) -> str:
+        """Format title for n-to-1 computation."""
+        readable_name = name.replace("_", " ").title()
+        base_title = f"{readable_name} of {n_inputs} Objects"
+
+        if suffix:
+            base_title += f" ({suffix})"
+        return base_title
+
+    def format_2_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 2-to-1 computation."""
+        if len(name) == 1:  # This is an operator
+            base_title = f"Binary Operation {name}"
+        else:
+            readable_name = name.replace("_", " ").title()
+            base_title = f"{readable_name} Result"
+
+        if suffix:
+            base_title += f" ({suffix})"
+        return base_title
+
+    def resolve_placeholder_title(
+        self,
+        title: str,
+        source_objects: list[BaseObj],  # pylint: disable=unused-argument
+    ) -> str:
+        """For simple formatter, just return the title as-is."""
+        return title
+
+
+class PlaceholderTitleFormatter:
+    """Placeholder-based title formatter compatible with DataLab.
+
+    Creates titles with placeholders that can be resolved later by DataLab's
+    patch_title_with_ids() function.
+    """
+
+    def format_1_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 1-to-1 computation with placeholder."""
+        if len(name) == 1:  # This is an operator
+            title = f"{{0}}{name}"
+        else:
+            title = f"{name}({{0}})"
+            if suffix:  # suffix may be None or an empty string
+                title += "|"
+        if suffix:  # suffix may be None or an empty string
+            title += suffix
+        return title
+
+    def format_n_to_1_title(
+        self, name: str, n_inputs: int, suffix: str | None = None
+    ) -> str:
+        """Format title for n-to-1 computation with placeholders."""
+        placeholders = ", ".join(f"{{{i}}}" for i in range(n_inputs))
+        title = f"{name}({placeholders})"
+        if suffix:
+            title += "|" + suffix
+        return title
+
+    def format_2_to_1_title(self, name: str, suffix: str | None = None) -> str:
+        """Format title for 2-to-1 computation with placeholders."""
+        if len(name) == 1:  # This is an operator
+            title = f"{{0}}{name}{{1}}"
+        else:
+            title = f"{name}({{0}}, {{1}})"
+        if suffix:
+            title += "|" + suffix
+        return title
+
+    def resolve_placeholder_title(
+        self,
+        title: str,
+        source_objects: list[BaseObj],
+    ) -> str:
+        """Resolve placeholder title with object short IDs (if available)."""
+        # For basic Sigima usage, use simple indexing
+        # DataLab will override this with its own patch_title_with_ids logic
+        try:
+            # Try to use short_id if available (for DataLab compatibility)
+            ids = []
+            for i, obj in enumerate(source_objects):
+                short_id = getattr(obj, "short_id", None)
+                if short_id is not None:
+                    ids.append(short_id)
+                else:
+                    ids.append(f"obj{i + 1}")
+            return title.format(*ids)
+        except (IndexError, AttributeError):
+            # Fallback: use simple object indices
+            return title.format(*[f"obj{i + 1}" for i in range(len(source_objects))])
+
+
+# Global default title formatter
+_default_title_formatter: TitleFormatter = SimpleTitleFormatter()
+
+
+def get_default_title_formatter() -> TitleFormatter:
+    """Get the current default title formatter.
+
+    Returns:
+        Current default title formatter
+    """
+    return _default_title_formatter
+
+
+def set_default_title_formatter(formatter: TitleFormatter) -> None:
+    """Set the default title formatter.
+
+    Args:
+        formatter: Title formatter to use as default
+    """
+    global _default_title_formatter  # pylint: disable=global-statement
+    _default_title_formatter = formatter

sigima/proc/validation.py

@@ -0,0 +1,272 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Validation statistics module
+(see parent package :mod:`sigima.computation`)
+"""
+
+from __future__ import annotations
+
+import csv
+import dataclasses
+import importlib
+import inspect
+import os.path as osp
+import pkgutil
+import re
+
+from _pytest.mark import Mark
+
+import sigima.tests as tests_pkg
+from sigima import __version__
+from sigima.proc.decorator import find_computation_functions
+
+
+def generate_valid_test_names_for_function(
+    module_name: str, func_name: str
+) -> list[str]:
+    """Generate all valid test names for a computation function.
+
+    Args:
+        module_name: Module name containing the computation function
+            (e.g., "sigima.proc.image")
+        func_name: Function name (e.g., "compute_add_gaussian_noise")
+
+    Returns:
+        List of valid test names that could test this computation function
+    """
+    family = module_name.split(".")[-1]  # "signal" or "image"
+    shortname = func_name.removeprefix("compute_")
+    endings = [shortname, shortname + "_unit", shortname + "_validation"]
+    beginnings = ["test", f"test_{family}", f"test_{family[:3]}", f"test_{family[0]}"]
+    names = [f"{beginning}_{ending}" for beginning in beginnings for ending in endings]
+    return names
+
+
+def check_for_validation_test(
+    full_function_name: str, validation_tests: list[tuple[str, str]]
+) -> str:
+    """Check if a validation test exists for a compute function
+
+    Args:
+        full_function_name: Compute function name
+        validation_tests: List of validation tests
+
+    Returns:
+        Text to be included in the CSV file or None if it doesn't exist
+    """
+    # Extract module name and function name from full function name
+    module_parts = full_function_name.split(".")
+    module_name = ".".join(module_parts[:-1])  # e.g., "sigima.proc.image"
+    func_name = module_parts[-1]  # e.g., "compute_add_gaussian_noise"
+
+    # Generate all valid test names for this computation function
+    names = generate_valid_test_names_for_function(module_name, func_name)
+
+    stable_version = re.sub(r"\.?(post|dev|rc|b|a)\S*", "", __version__)
+    for test, path, line_number in validation_tests:
+        if test in names:
+            # Path relative to the `datalab` package:
+            path = osp.relpath(path, start=osp.dirname(osp.join(tests_pkg.__file__)))
+            name = "/".join(path.split(osp.sep))
+            link = (
+                f"https://github.com/DataLab-Platform/Sigima/blob/"
+                f"v{stable_version}/sigima/tests/{name}#L{line_number}"
+            )
+            return f"`{test} <{link}>`_"
+    return None
+
+
+def get_validation_tests(package: str) -> list:
+    """Retrieve list of validation tests from a package and its submodules
+
+    Args:
+        package: Python package
+
+    Returns:
+        List of tuples containing the test name, module path and line number
+    """
+    validation_tests = []
+    package_path = package.__path__
+    for _, module_name, _ in pkgutil.walk_packages(
+        package_path, package.__name__ + "."
+    ):
+        try:
+            module = importlib.import_module(module_name)
+        except ImportError as exc:
+            if "vistools" in module_name:
+                # This is expected as vistools requires a GUI
+                continue
+            raise ImportError(
+                f"Failed to import module {module_name}. "
+                "Ensure the module is correctly installed and accessible."
+            ) from exc
+        for name, obj in inspect.getmembers(module, inspect.isfunction):
+            if hasattr(obj, "pytestmark"):
+                for mark in obj.pytestmark:
+                    if isinstance(mark, Mark) and mark.name == "validation":
+                        module_path = inspect.getfile(obj)
+                        try:
+                            line_number = inspect.getsourcelines(obj)[1]
+                        except OSError as exc:
+                            raise RuntimeError(
+                                f"Failed to get source line for {name} in {module_name}"
+                            ) from exc
+                        validation_tests.append((name, module_path, line_number))
+    return validation_tests
+
+
+def shorten_docstring(docstring: str) -> str:
+    """Shorten a docstring to a single line
+
+    Args:
+        docstring: Docstring
+
+    Returns:
+        Shortened docstring
+    """
+    shorter = docstring.split("\n")[0].strip() if docstring else "-"
+    for suffix in (".", ":", ",", "using", "with"):
+        shorter = shorter.removesuffix(suffix)
+    shorter = shorter.split(" with :py:func:")[0]  # Remove function references
+    return shorter
+
+
+@dataclasses.dataclass
+class ValidationStatus:
+    """Data class to hold validation status of a compute function"""
+
+    module_name: str
+    function_name: str
+    description: str
+    test_script: str
+
+    def get_pyfunc_link(self) -> str:
+        """Get the reStructuredText link to the compute function"""
+        return (
+            f":py:func:`{self.function_name} <{self.module_name}.{self.function_name}>`"
+        )
+
+    def __str__(self) -> str:
+        """String representation of the validation status"""
+        return f"{self.get_pyfunc_link()} - {self.description} - {self.test_script}"
+
+    def to_csv_row(self) -> list[str]:
+        """Convert the validation status to a CSV row"""
+        return [self.get_pyfunc_link(), self.description, self.test_script]
+
+
+class ValidationStatistics:
+    """Data class to hold validation statistics of compute functions"""
+
+    def __init__(self):
+        self.submodules: dict[str, list[tuple[str, str, str]]] = {}
+        self.t_count: dict[str, int] = {}
+        self.v_count: dict[str, int] = {}
+        self.signal_pct: int = 0
+        self.image_pct: int = 0
+        self.total_pct: int = 0
+        self.validations: dict[str, list[ValidationStatus]] = {}
+        self.validation_info_list: list[str] = []
+
+    def collect_validation_status(self, verbose: bool = False) -> None:
+        """Populate the statistics from the validation status"""
+        compute_functions = find_computation_functions()
+        validation_tests = get_validation_tests(tests_pkg)
+
+        self.submodules = {"signal": [], "image": []}
+        for modname, funcname, docstring in compute_functions:
+            if "signal" in modname:
+                self.submodules["signal"].append((modname, funcname, docstring))
+            elif "image" in modname:
+                self.submodules["image"].append((modname, funcname, docstring))
+
+        self.t_count = t_count = {"signal": 0, "image": 0, "total": 0}
+        self.v_count = v_count = {"signal": 0, "image": 0, "total": 0}
+
+        self.validations = {"signal": [], "image": []}
+        for submodule, functions in self.submodules.items():
+            for modname, funcname, docstring in functions:
+                full_funcname = f"{modname}.{funcname}"
+                test_link = check_for_validation_test(full_funcname, validation_tests)
+                if test_link:
+                    v_count[submodule] += 1
+                    v_count["total"] += 1
+                t_count[submodule] += 1
+                t_count["total"] += 1
+                status = ValidationStatus(
+                    module_name=modname,
+                    function_name=funcname,
+                    description=shorten_docstring(docstring),
+                    test_script=test_link if test_link else "N/A",
+                )
+                self.validations[submodule].append(status)
+
+            self.signal_pct = signal_pct = (
+                int((v_count["signal"] / t_count["signal"]) * 100)
+                if t_count["signal"] > 0
+                else 0
+            )
+            self.image_pct = image_pct = (
+                int((v_count["image"] / t_count["image"]) * 100)
+                if t_count["image"] > 0
+                else 0
+            )
+            self.total_pct = total_pct = (
+                int((v_count["total"] / t_count["total"]) * 100)
+                if t_count["total"] > 0
+                else 0
+            )
+
+        self.validation_info_list = [
+            f"Validation statistics for Sigima {__version__}:",
+            f"  Signal: {v_count['signal']}/{t_count['signal']} ({signal_pct}%)",
+            f"  Image : {v_count['image']}/{t_count['image']} ({image_pct}%)",
+            f"  Total : {v_count['total']}/{t_count['total']} ({total_pct}%)",
+        ]
+
+        if verbose:
+            print("\n".join(self.validation_info_list))
+            print()
+
+    def get_validation_info(self) -> list[str]:
+        """Get the validation information as a list of strings"""
+        if not self.validation_info_list:
+            self.collect_validation_status(verbose=False)
+        return self.validation_info_list
+
+    def generate_csv_files(self, path: str) -> None:
+        """Generate CSV files for each submodule's validation status"""
+        for submodule, validation_status_list in self.validations.items():
+            rows = [status.to_csv_row() for status in validation_status_list]
+            fname = osp.join(path, f"validation_status_{submodule}.csv")
+            with open(fname, "w", newline="", encoding="utf-8") as csvfile:
+                writer = csv.writer(csvfile)
+                writer.writerows(rows)
+
+    def generate_statistics_csv(self, path: str) -> None:
+        """Generate a CSV file with the validation statistics"""
+        statistics_rows = [
+            [
+                "Number of compute functions",
+                self.t_count["signal"],
+                self.t_count["image"],
+                self.t_count["total"],
+            ],
+            [
+                "Number of validated compute functions",
+                self.v_count["signal"],
+                self.v_count["image"],
+                self.v_count["total"],
+            ],
+            [
+                "Percentage of validated compute functions",
+                f"{self.signal_pct}%",
+                f"{self.image_pct}%",
+                f"{self.total_pct}%",
+            ],
+        ]
+        fname = osp.join(path, "validation_statistics.csv")
+        with open(fname, "w", newline="", encoding="utf-8") as csvfile:
+            writer = csv.writer(csvfile)
+            writer.writerows(statistics_rows)

sigima/tests/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Sigima test suite
+"""
+
+SIGIMA_TESTS_GUI_ENV = "SIGIMA_TESTS_GUI"