scitex 2.0.0__py2.py3-none-any.whl

scitex/decorators/_converters.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-04-30 14:58:43 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_converters.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/decorators/_converters.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import functools
+import warnings
+from typing import Any as _Any
+from typing import Callable, Dict, Tuple, Union
+
+import numpy as np
+import pandas as pd
+import torch
+import xarray
+
+"""
+Core conversion utilities for handling data type transformations.
+Provides consistent conversion between NumPy, PyTorch, Pandas, and other formats.
+"""
+
+
+class ConversionWarning(UserWarning):
+    pass
+
+
+# Configure warnings
+warnings.simplefilter("always", ConversionWarning)
+
+
+@functools.lru_cache(maxsize=None)
+def _cached_warning(message: str) -> None:
+    """Cache warnings to avoid repetition."""
+    warnings.warn(message, category=ConversionWarning)
+
+
+def _conversion_warning(old: _Any, new: torch.Tensor) -> None:
+    """Generate standardized type conversion warning."""
+    message = (
+        f"Converted from {type(old).__name__} to {type(new).__name__} ({new.device}). "
+        f"Consider using {type(new).__name__} ({new.device}) as input for faster computation."
+    )
+    _cached_warning(message)
+
+
+def _try_device(tensor: torch.Tensor, device: str) -> torch.Tensor:
+    """Try to move tensor to specified device with graceful fallback."""
+    if not isinstance(tensor, torch.Tensor):
+        return tensor
+
+    if tensor.device.type == device:
+        return tensor
+
+    try:
+        return tensor.to(device)
+    except RuntimeError as error:
+        if "cuda" in str(error).lower() and device == "cuda":
+            warnings.warn("CUDA memory insufficient, falling back to CPU.", UserWarning)
+            return tensor.cpu()
+        raise error
+
+
+def is_torch(*args: _Any, **kwargs: _Any) -> bool:
+    """Check if any input is a PyTorch tensor."""
+    return any(isinstance(arg, torch.Tensor) for arg in args) or any(
+        isinstance(val, torch.Tensor) for val in kwargs.values()
+    )
+
+
+def is_cuda(*args: _Any, **kwargs: _Any) -> bool:
+    """Check if any input is a CUDA tensor."""
+    return any((isinstance(arg, torch.Tensor) and arg.is_cuda) for arg in args) or any(
+        (isinstance(val, torch.Tensor) and val.is_cuda) for val in kwargs.values()
+    )
+
+
+def _return_always(*args: _Any, **kwargs: _Any) -> Tuple[Tuple, Dict]:
+    """Always return args and kwargs as a tuple of (args, kwargs)."""
+    return args, kwargs
+
+
+def _return_if(*args: _Any, **kwargs: _Any) -> Union[Tuple, Dict, None]:
+    """Return args and/or kwargs depending on what's provided."""
+    if args and kwargs:
+        return args, kwargs
+    elif args:
+        return args
+    elif kwargs:
+        return kwargs
+    else:
+        return None
+
+
+def to_torch(
+    *args: _Any,
+    return_fn: Callable = _return_if,
+    device: str = None,
+    **kwargs: _Any,
+) -> _Any:
+    """Convert various data types to PyTorch tensors."""
+    if device is None:
+        device = kwargs.get("device", "cuda" if torch.cuda.is_available() else "cpu")
+
+    def _to_torch(data: _Any) -> _Any:
+        """Internal conversion function for various data types."""
+        # Check for None
+        if data is None:
+            return None
+
+        # Don't convert scalars (int, float, bool, str) - they should remain as is
+        if isinstance(data, (int, float, bool, str)):
+            return data
+
+        # Handle collections
+        if isinstance(data, (tuple, list)):
+            # Check if it's a tuple/list of integers (like dimensions)
+            if all(isinstance(item, int) for item in data):
+                return data  # Keep as is for dimension tuples
+            
+            # Check if it's a numeric array-like structure
+            try:
+                # Try to convert to tensor directly
+                new_data = torch.tensor(data).float()
+                new_data = _try_device(new_data, device)
+                if device == "cuda":
+                    _conversion_warning(data, new_data)
+                return new_data
+            except:
+                # If conversion fails, process items individually and return as tensor if possible
+                converted_items = [_to_torch(item) for item in data if item is not None]
+                # Try to stack if all items are tensors
+                if converted_items and all(isinstance(item, torch.Tensor) for item in converted_items):
+                    try:
+                        # Stack tensors along a new dimension
+                        return torch.stack(converted_items)
+                    except:
+                        # Return as list if stacking fails
+                        return converted_items
+                return converted_items
+
+        # Handle pandas types
+        if isinstance(data, (pd.Series, pd.DataFrame)):
+            new_data = torch.tensor(data.to_numpy()).squeeze().float()
+            new_data = _try_device(new_data, device)
+            if device == "cuda":
+                _conversion_warning(data, new_data)
+            return new_data
+
+        # Handle arrays
+        if isinstance(data, np.ndarray):
+            new_data = torch.tensor(data).float()
+            new_data = _try_device(new_data, device)
+            if device == "cuda":
+                _conversion_warning(data, new_data)
+            return new_data
+
+        # Handle xarray
+        if isinstance(data, xarray.core.dataarray.DataArray):
+            new_data = torch.tensor(np.array(data)).float()
+            new_data = _try_device(new_data, device)
+            if device == "cuda":
+                _conversion_warning(data, new_data)
+            return new_data
+
+        # Return as is for other types
+        return data
+
+    # Process args and kwargs
+    converted_args = [_to_torch(arg) for arg in args if arg is not None]
+    converted_kwargs = {
+        key: _to_torch(val) for key, val in kwargs.items() if val is not None
+    }
+
+    # Handle axis/dim parameter conversion
+    # Only convert axis to dim if dim is not already present
+    if "axis" in converted_kwargs and "dim" not in converted_kwargs:
+        converted_kwargs["dim"] = converted_kwargs.pop("axis")
+
+    # Return in the specified format
+    return return_fn(*converted_args, **converted_kwargs)
+
+
+def to_numpy(*args: _Any, return_fn: Callable = _return_if, **kwargs: _Any) -> _Any:
+    """Convert various data types to NumPy arrays."""
+
+    def _to_numpy(data: _Any) -> _Any:
+        """Internal conversion function for various data types."""
+        # Check for None
+        if data is None:
+            return None
+
+        # Don't convert scalars (int, float, bool, str) - they should remain as is
+        if isinstance(data, (int, float, bool, str)):
+            return data
+
+        # Handle pandas types
+        if isinstance(data, (pd.Series, pd.DataFrame)):
+            return data.to_numpy().squeeze()
+
+        # Handle torch tensors
+        if isinstance(data, torch.Tensor):
+            return data.detach().cpu().numpy()
+
+        # Handle lists and tuples
+        if isinstance(data, (list, tuple)):
+            # Check if it's a tuple/list of integers (like dimensions)
+            if all(isinstance(item, int) for item in data):
+                return data  # Keep as is for dimension tuples
+            
+            # Check if it's a numeric array-like structure
+            try:
+                # Try to convert to numpy array directly
+                return np.array(data)
+            except:
+                # If conversion fails, process items individually
+                converted_items = [_to_numpy(item) for item in data if item is not None]
+                # Try to stack if all items are numpy arrays
+                if converted_items and all(isinstance(item, np.ndarray) for item in converted_items):
+                    try:
+                        # Stack arrays along a new dimension
+                        return np.stack(converted_items)
+                    except:
+                        # Return as list if stacking fails
+                        return converted_items
+                return converted_items
+
+        # Return as is for other types
+        return data
+
+    # Process args and kwargs
+    converted_args = [_to_numpy(arg) for arg in args if arg is not None]
+    converted_kwargs = {
+        key: _to_numpy(val) for key, val in kwargs.items() if val is not None
+    }
+
+    # Handle dim/axis parameter conversion
+    # Only convert dim to axis if axis is not already present
+    if "dim" in converted_kwargs and "axis" not in converted_kwargs:
+        converted_kwargs["axis"] = converted_kwargs.pop("dim")
+
+    # Return in the specified format
+    return return_fn(*converted_args, **converted_kwargs)
+
+
+def is_nested_decorator():
+    """Check if we're in a nested decorator context."""
+    import inspect
+
+    frame = inspect.currentframe()
+    current_decorator = None
+    decorator_chain = []
+
+    # Walk up the call stack
+    while frame:
+        if frame.f_code.co_name == "wrapper":
+            # Check if this frame has local variables
+            if frame.f_locals:
+                # Try to get the self reference if it's a method
+                if "self" in frame.f_locals:
+                    decorator_chain.append(frame.f_locals["self"])
+
+                # Check if the wrapper has marked itself with decorator info
+                if "_current_decorator" in frame.f_locals:
+                    decorator_type = frame.f_locals["_current_decorator"]
+                    if current_decorator is None:
+                        current_decorator = decorator_type
+                    elif current_decorator != decorator_type:
+                        # Found a different decorator in the chain
+                        return True
+
+        frame = frame.f_back
+
+    # If we found more than one decorator in the chain
+    return len(decorator_chain) > 1
+
+
+# EOF

scitex/decorators/_deprecated.py

@@ -0,0 +1,26 @@
+import functools
+import warnings
+
+
+def deprecated(reason=None):
+    """
+    A decorator to mark functions as deprecated. It will result in a warning being emitted
+    when the function is used.
+
+    Args:
+        reason (str): A human-readable string explaining why this function was deprecated.
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def new_func(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__} is deprecated: {reason}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return new_func
+
+    return decorator

scitex/decorators/_not_implemented.py

@@ -0,0 +1,30 @@
+#!./env/bin/python3
+# -*- coding: utf-8 -*-
+# Time-stamp: "2024-06-07 22:16:25 (ywatanabe)"
+# /home/ywatanabe/proj/scitex/src/scitex/gen/_not_implemented.py
+
+import warnings
+
+
+def not_implemented(func):
+    """
+    Decorator to mark methods as not implemented, issue a warning, and prevent their execution.
+
+    Arguments:
+        func (callable): The function or method to decorate.
+
+    Returns:
+        callable: A wrapper function that issues a warning and raises NotImplementedError when called.
+    """
+
+    def wrapper(*args, **kwargs):
+        # Issue a warning before raising the error
+        warnings.warn(
+            f"Attempt to use unimplemented method: '{func.__name__}'. This method is not yet available.",
+            category=FutureWarning,
+            stacklevel=2,
+        )
+        # # Raise the NotImplementedError
+        # raise NotImplementedError(f"The method '{func.__name__}' is not implemented yet.")
+
+    return wrapper

scitex/decorators/_numpy_fn.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-04-30 15:29:53 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_numpy_fn.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/decorators/_numpy_fn.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import numpy as np
+import pandas as pd
+import torch
+
+THIS_FILE = "/home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_numpy_fn.py"
+
+from functools import wraps
+from typing import Any as _Any
+from typing import Callable
+
+from ._converters import _return_always, is_nested_decorator, to_numpy
+
+
+def numpy_fn(func: Callable) -> Callable:
+    @wraps(func)
+    def wrapper(*args: _Any, **kwargs: _Any) -> _Any:
+        # Skip conversion if already in a nested decorator context
+        if is_nested_decorator():
+            results = func(*args, **kwargs)
+            return results
+
+        # Set the current decorator context
+        wrapper._current_decorator = "numpy_fn"
+
+        # Store original object for type preservation
+        original_object = args[0] if args else None
+
+        converted_args, converted_kwargs = to_numpy(
+            *args, return_fn=_return_always, **kwargs
+        )
+
+        # Skip strict assertion for certain types that may not convert to arrays
+        # Instead, convert what we can and pass through what we can't
+        validated_args = []
+        for arg_index, arg in enumerate(converted_args):
+            if isinstance(arg, np.ndarray):
+                validated_args.append(arg)
+            elif isinstance(arg, (int, float, str, type(None))):
+                # Pass through scalars and strings unchanged
+                validated_args.append(arg)
+            elif isinstance(arg, list) and all(isinstance(item, np.ndarray) for item in arg):
+                # List of arrays - pass through as is
+                validated_args.append(arg)
+            else:
+                # Try one more conversion attempt
+                try:
+                    validated_args.append(np.array(arg))
+                except:
+                    # If all else fails, pass through unchanged
+                    validated_args.append(arg)
+
+        results = func(*validated_args, **converted_kwargs)
+
+        # Convert results back to original input types
+        if isinstance(results, np.ndarray):
+            if original_object is not None:
+                if isinstance(original_object, list):
+                    return results.tolist()
+                elif isinstance(original_object, torch.Tensor):
+                    return torch.tensor(results)
+                elif isinstance(original_object, pd.DataFrame):
+                    return pd.DataFrame(results)
+                elif isinstance(original_object, pd.Series):
+                    return pd.Series(results)
+            return results
+
+        return results
+
+    # Mark as a wrapper for detection
+    wrapper._is_wrapper = True
+    wrapper._decorator_type = "numpy_fn"
+    return wrapper
+
+
+# EOF

scitex/decorators/_pandas_fn.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-04-30 15:44:00 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_pandas_fn.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/decorators/_pandas_fn.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+THIS_FILE = "/home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_pandas_fn.py"
+
+from functools import wraps
+from typing import Any as _Any
+from typing import Callable
+
+import numpy as np
+import pandas as pd
+import torch
+import xarray as xr
+
+from ._converters import is_nested_decorator
+
+
+def pandas_fn(func: Callable) -> Callable:
+    @wraps(func)
+    def wrapper(*args: _Any, **kwargs: _Any) -> _Any:
+        # Skip conversion if already in a nested decorator context
+        if is_nested_decorator():
+            results = func(*args, **kwargs)
+            return results
+
+        # Set the current decorator context
+        wrapper._current_decorator = "pandas_fn"
+
+        # Store original object for type preservation
+        original_object = args[0] if args else None
+
+        # Convert args to pandas DataFrames
+        def to_pandas(data):
+            if data is None:
+                return None
+            elif isinstance(data, pd.DataFrame):
+                return data
+            elif isinstance(data, pd.Series):
+                return pd.DataFrame(data)
+            elif isinstance(data, np.ndarray):
+                return pd.DataFrame(data)
+            elif isinstance(data, list):
+                try:
+                    return pd.DataFrame(data)
+                except:
+                    # If list can't be converted to DataFrame, return as is
+                    return data
+            elif isinstance(data, torch.Tensor):
+                return pd.DataFrame(data.detach().cpu().numpy())
+            elif isinstance(data, xr.DataArray):
+                return pd.DataFrame(data.values)
+            elif isinstance(data, (int, float, str)):
+                # Don't convert scalars to DataFrames
+                return data
+            else:
+                try:
+                    return pd.DataFrame([data])
+                except:
+                    # If conversion fails, return as is
+                    return data
+
+        converted_args = [to_pandas(arg) for arg in args]
+        converted_kwargs = {k: to_pandas(v) for k, v in kwargs.items()}
+
+        # Skip strict assertion for certain types
+        validated_args = []
+        for arg_index, arg in enumerate(converted_args):
+            if isinstance(arg, pd.DataFrame):
+                validated_args.append(arg)
+            elif isinstance(arg, (int, float, str, type(None), pd.Series)):
+                # Pass through scalars, strings, Series, and None unchanged
+                validated_args.append(arg)
+            elif isinstance(arg, list) and all(isinstance(item, pd.DataFrame) for item in arg):
+                # List of DataFrames - pass through as is
+                validated_args.append(arg)
+            else:
+                # Try one more conversion attempt
+                try:
+                    validated_args.append(pd.DataFrame(arg))
+                except:
+                    # If all else fails, pass through unchanged
+                    validated_args.append(arg)
+
+        results = func(*validated_args, **converted_kwargs)
+
+        # Convert results back to original input types
+        if isinstance(results, pd.DataFrame):
+            if original_object is not None:
+                if isinstance(original_object, list):
+                    return results.values.tolist()
+                elif isinstance(original_object, np.ndarray):
+                    return results.values
+                elif isinstance(original_object, torch.Tensor):
+                    return torch.tensor(results.values)
+                elif isinstance(original_object, pd.Series):
+                    return (
+                        pd.Series(results.iloc[:, 0])
+                        if results.shape[1] > 0
+                        else pd.Series()
+                    )
+                elif isinstance(original_object, xr.DataArray):
+                    return xr.DataArray(results.values)
+            return results
+
+        return results
+
+    # Mark as a wrapper for detection
+    wrapper._is_wrapper = True
+    wrapper._decorator_type = "pandas_fn"
+    return wrapper
+
+
+# EOF

scitex/decorators/_preserve_doc.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Time-stamp: "2024-11-14 07:44:00 (ywatanabe)"
+# File: ./scitex_repo/src/scitex/decorators/_preserve_doc.py
+
+from functools import wraps
+
+
+def preserve_doc(loader_func):
+    """Wrap the loader functions to preserve their docstrings"""
+
+    @wraps(loader_func)
+    def wrapper(*args, **kwargs):
+        return loader_func(*args, **kwargs)
+
+    return wrapper
+
+
+# EOF

scitex/decorators/_signal_fn.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-31 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/decorators/_signal_fn.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/decorators/_signal_fn.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+from functools import wraps
+from typing import Any as _Any
+from typing import Callable
+
+import numpy as np
+import pandas as pd
+import torch
+import xarray as xr
+
+from ._converters import _return_always, is_nested_decorator, to_torch
+
+
+def signal_fn(func: Callable) -> Callable:
+    """Decorator for signal processing functions that converts only the first argument (signal) to torch tensor.
+
+    This decorator is designed for DSP functions where:
+    - The first argument is the signal data that should be converted to torch tensor
+    - Other arguments (like sampling frequency, bands, etc.) should remain as-is
+    """
+
+    @wraps(func)
+    def wrapper(*args: _Any, **kwargs: _Any) -> _Any:
+        # Skip conversion if already in a nested decorator context
+        if is_nested_decorator():
+            results = func(*args, **kwargs)
+            return results
+
+        # Set the current decorator context
+        wrapper._current_decorator = "signal_fn"
+
+        # Store original object for type preservation
+        original_object = args[0] if args else None
+
+        # Convert only the first argument (signal) to torch tensor
+        if args:
+            # Convert first argument to torch
+            converted_first_arg = to_torch(args[0], return_fn=_return_always)[0][0]
+
+            # Keep other arguments as-is
+            converted_args = (converted_first_arg,) + args[1:]
+        else:
+            converted_args = args
+
+        results = func(*converted_args, **kwargs)
+
+        # Convert results back to original input types
+        if isinstance(results, torch.Tensor):
+            if original_object is not None:
+                if isinstance(original_object, list):
+                    return results.detach().cpu().numpy().tolist()
+                elif isinstance(original_object, np.ndarray):
+                    return results.detach().cpu().numpy()
+                elif isinstance(original_object, pd.DataFrame):
+                    return pd.DataFrame(results.detach().cpu().numpy())
+                elif isinstance(original_object, pd.Series):
+                    return pd.Series(results.detach().cpu().numpy().flatten())
+                elif isinstance(original_object, xr.DataArray):
+                    return xr.DataArray(results.detach().cpu().numpy())
+            return results
+
+        # Handle tuple returns (e.g., (signal, frequencies))
+        elif isinstance(results, tuple):
+            converted_results = []
+            for r in results:
+                if isinstance(r, torch.Tensor):
+                    if original_object is not None and isinstance(
+                        original_object, np.ndarray
+                    ):
+                        converted_results.append(r.detach().cpu().numpy())
+                    else:
+                        converted_results.append(r)
+                else:
+                    converted_results.append(r)
+            return tuple(converted_results)
+
+        return results
+
+    # Mark as a wrapper for detection
+    wrapper._is_wrapper = True
+    wrapper._decorator_type = "signal_fn"
+    return wrapper
+
+
+# EOF