oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/pipeline/base.py

@@ -0,0 +1,338 @@
+"""Base classes for trace transformations and pipeline stages.
+
+This module implements the foundational abstract base classes for creating
+custom trace transformations compatible with the Pipeline architecture.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core.types import WaveformTrace
+
+
+class TraceTransformer(ABC):
+    """Abstract base class for trace transformations.
+
+    All pipeline stages and custom transformations must inherit from this class.
+    Provides the fit/transform pattern similar to sklearn transformers.
+
+    The TraceTransformer enforces a consistent interface:
+    - transform(trace) -> trace: Required transformation method
+    - fit(trace) -> self: Optional learning/calibration method
+    - fit_transform(trace) -> trace: Convenience method
+    - get_params() / set_params(): Hyperparameter access
+    - clone(): Create a copy of the transformer
+
+    Example:
+        >>> class AmplitudeScaler(TraceTransformer):
+        ...     def __init__(self, scale_factor=1.0):
+        ...         self.scale_factor = scale_factor
+        ...
+        ...     def transform(self, trace):
+        ...         scaled_data = trace.data * self.scale_factor
+        ...         return WaveformTrace(
+        ...             data=scaled_data,
+        ...             metadata=trace.metadata
+        ...         )
+        ...
+        >>> scaler = AmplitudeScaler(scale_factor=2.0)
+        >>> result = scaler.transform(trace)
+
+    References:
+        API-004: TraceTransformer Base Class
+        sklearn.base.BaseEstimator, TransformerMixin
+    """
+
+    @abstractmethod
+    def transform(self, trace: WaveformTrace) -> WaveformTrace:
+        """Transform a trace.
+
+        Args:
+            trace: Input WaveformTrace to transform.
+
+        Returns:
+            Transformed WaveformTrace.
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement transform() method")
+
+    def fit(self, trace: WaveformTrace) -> TraceTransformer:
+        """Fit transformer to a reference trace (optional for stateful transformers).
+
+        This method is optional and should be overridden by stateful transformers
+        that need to learn parameters from a reference trace (e.g., normalization
+        statistics, adaptive filters).
+
+        Args:
+            trace: Reference WaveformTrace to fit to.
+
+        Returns:
+            Self for method chaining.
+
+        Example:
+            >>> class AdaptiveNormalizer(TraceTransformer):
+            ...     def __init__(self):
+            ...         self.mean_ = None
+            ...         self.std_ = None
+            ...
+            ...     def fit(self, trace):
+            ...         self.mean_ = trace.data.mean()
+            ...         self.std_ = trace.data.std()
+            ...         return self
+            ...
+            ...     def transform(self, trace):
+            ...         normalized = (trace.data - self.mean_) / self.std_
+            ...         return WaveformTrace(
+            ...             data=normalized,
+            ...             metadata=trace.metadata
+            ...         )
+        """
+        # Default implementation: no fitting required
+        return self
+
+    def fit_transform(self, trace: WaveformTrace) -> WaveformTrace:
+        """Fit to trace, then transform it.
+
+        Convenience method that calls fit() followed by transform().
+
+        Args:
+            trace: Input WaveformTrace to fit and transform.
+
+        Returns:
+            Transformed WaveformTrace.
+
+        Example:
+            >>> normalizer = AdaptiveNormalizer()
+            >>> result = normalizer.fit_transform(reference_trace)
+        """
+        return self.fit(trace).transform(trace)
+
+    def get_params(self, deep: bool = True) -> dict[str, Any]:
+        """Get parameters for this transformer.
+
+        Args:
+            deep: If True, will return parameters for nested objects.
+
+        Returns:
+            Dictionary of parameter names mapped to their values.
+
+        Example:
+            >>> scaler = AmplitudeScaler(scale_factor=2.0)
+            >>> params = scaler.get_params()
+            >>> print(params)
+            {'scale_factor': 2.0}
+        """
+        params = {}
+        for key in dir(self):
+            # Skip private/magic attributes and methods
+            if key.startswith("_") or callable(getattr(self, key)):
+                continue
+            value = getattr(self, key)
+            params[key] = value
+
+            # Handle nested transformers if deep=True
+            if deep and hasattr(value, "get_params"):
+                nested_params = value.get_params(deep=True)
+                for nested_key, nested_value in nested_params.items():
+                    params[f"{key}__{nested_key}"] = nested_value
+
+        return params
+
+    def set_params(self, **params: Any) -> TraceTransformer:
+        """Set parameters for this transformer.
+
+        Args:
+            **params: Parameter names and values to set.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            ValueError: If parameter name is invalid.
+
+        Example:
+            >>> scaler = AmplitudeScaler(scale_factor=1.0)
+            >>> scaler.set_params(scale_factor=3.0)
+            >>> print(scaler.scale_factor)
+            3.0
+        """
+        if not params:
+            return self
+
+        valid_params = self.get_params(deep=False)
+
+        for key, value in params.items():
+            # Handle nested parameters (e.g., 'filter__cutoff')
+            if "__" in key:
+                nested_obj, nested_key = key.split("__", 1)
+                if nested_obj not in valid_params:
+                    raise ValueError(
+                        f"Invalid parameter {nested_obj} for transformer {self.__class__.__name__}"
+                    )
+                nested = getattr(self, nested_obj)
+                if hasattr(nested, "set_params"):
+                    nested.set_params(**{nested_key: value})
+                else:
+                    raise ValueError(f"Parameter {nested_obj} does not support set_params")
+            else:
+                if key not in valid_params:
+                    raise ValueError(
+                        f"Invalid parameter {key} for transformer "
+                        f"{self.__class__.__name__}. "
+                        f"Valid parameters: {list(valid_params.keys())}"
+                    )
+                setattr(self, key, value)
+
+        return self
+
+    def clone(self) -> TraceTransformer:
+        """Create a copy of this transformer with the same parameters.
+
+        Returns:
+            New instance of the transformer with same parameters.
+
+        Example:
+            >>> scaler = AmplitudeScaler(scale_factor=2.0)
+            >>> scaler_copy = scaler.clone()
+            >>> scaler_copy.scale_factor
+            2.0
+        """
+        params = self.get_params(deep=False)
+        return self.__class__(**params)
+
+    def __getstate__(self) -> dict[str, Any]:
+        """Get state for pickling.
+
+        Returns:
+            Dictionary containing transformer state.
+        """
+        return self.__dict__.copy()
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        """Set state from unpickling.
+
+        Args:
+            state: Dictionary containing transformer state.
+        """
+        self.__dict__.update(state)
+
+    def get_intermediate_result(self, key: str) -> Any:
+        """Get intermediate result from last transformation.
+
+        Some transformers cache intermediate results (e.g., FFT coefficients,
+        filter states) that can be accessed after transformation.
+
+        Args:
+            key: Name of intermediate result to retrieve.
+
+        Returns:
+            Intermediate result value.
+
+        Raises:
+            KeyError: If key not found or transformer doesn't support intermediates.
+
+        Example:
+            >>> filter = LowPassFilter(cutoff=1e6)
+            >>> result = filter.transform(trace)
+            >>> transfer_func = filter.get_intermediate_result('transfer_function')
+
+        References:
+            API-005: Intermediate Result Access
+        """
+        # Check if transformer has _intermediates cache
+        if not hasattr(self, "_intermediates"):
+            raise KeyError(f"{self.__class__.__name__} does not cache intermediate results")
+
+        intermediates = self._intermediates
+        if key not in intermediates:
+            available = list(intermediates.keys())
+            raise KeyError(
+                f"Intermediate '{key}' not found in {self.__class__.__name__}. "
+                f"Available: {available}"
+            )
+
+        return intermediates[key]
+
+    def has_intermediate_result(self, key: str) -> bool:
+        """Check if intermediate result is available.
+
+        Args:
+            key: Name of intermediate result.
+
+        Returns:
+            True if intermediate result exists.
+
+        Example:
+            >>> if filter.has_intermediate_result('impulse_response'):
+            ...     impulse = filter.get_intermediate_result('impulse_response')
+
+        References:
+            API-005: Intermediate Result Access
+        """
+        if not hasattr(self, "_intermediates"):
+            return False
+        return key in self._intermediates
+
+    def list_intermediate_results(self) -> list[str]:
+        """List all available intermediate result keys.
+
+        Returns:
+            List of intermediate result names, or empty list if none available.
+
+        Example:
+            >>> print(filter.list_intermediate_results())
+            ['transfer_function', 'impulse_response', 'frequency_response']
+
+        References:
+            API-005: Intermediate Result Access
+        """
+        if not hasattr(self, "_intermediates"):
+            return []
+        return list(self._intermediates.keys())
+
+    def _cache_intermediate(self, key: str, value: Any) -> None:
+        """Cache an intermediate result for later access.
+
+        This is a protected method for subclasses to use when storing
+        intermediate computation results.
+
+        Args:
+            key: Name of intermediate result.
+            value: Value to cache.
+
+        Example (in subclass):
+            >>> def transform(self, trace):
+            ...     fft_coeffs = compute_fft(trace)
+            ...     self._cache_intermediate('fft_coeffs', fft_coeffs)
+            ...     return processed_trace
+
+        References:
+            API-005: Intermediate Result Access
+        """
+        if not hasattr(self, "_intermediates"):
+            self._intermediates = {}
+        self._intermediates[key] = value
+
+    def _clear_intermediates(self) -> None:
+        """Clear all cached intermediate results.
+
+        Useful for freeing memory when intermediate results are no longer needed.
+
+        Example (in subclass):
+            >>> def transform(self, trace):
+            ...     self._clear_intermediates()  # Clear previous results
+            ...     # ... perform transformation ...
+
+        References:
+            API-005: Intermediate Result Access
+        """
+        if hasattr(self, "_intermediates"):
+            self._intermediates.clear()
+
+
+__all__ = ["TraceTransformer"]

oscura/pipeline/composition.py

@@ -0,0 +1,242 @@
+"""Functional composition operators for trace transformations.
+
+This module implements compose() and pipe() functions for functional-style
+trace processing, with support for operator overloading.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import reduce, wraps
+from typing import Any, TypeVar
+
+from ..core.types import WaveformTrace
+
+# Type variables for generic composition
+T = TypeVar("T")
+TraceFunc = Callable[[WaveformTrace], WaveformTrace]
+
+
+def compose(*funcs: TraceFunc) -> TraceFunc:
+    """Compose functions right-to-left: compose(f, g, h)(x) == f(g(h(x))).
+
+    Creates a single function that applies the given functions in reverse order.
+    This follows mathematical function composition notation.
+
+    Args:
+        *funcs: Variable number of functions to compose. Each function should
+            take a WaveformTrace and return a WaveformTrace.
+
+    Returns:
+        Composite function that applies all functions in reverse order.
+
+    Raises:
+        ValueError: If no functions provided.
+
+    Example:
+        >>> import oscura as tk
+        >>> from functools import partial
+        >>> # Create composed analysis function
+        >>> analyze_signal = tk.compose(
+        ...     tk.extract_thd,
+        ...     partial(tk.fft, nfft=8192, window='hann'),
+        ...     partial(tk.normalize, method='peak'),
+        ...     partial(tk.low_pass, cutoff=5e6)
+        ... )
+        >>> # Apply to trace: low_pass -> normalize -> fft -> extract_thd
+        >>> thd = analyze_signal(trace)
+
+    References:
+        API-002: Function Composition Operators
+        toolz.functoolz
+        https://github.com/pytoolz/toolz
+    """
+    if not funcs:
+        raise ValueError("compose() requires at least one function")
+
+    if len(funcs) == 1:
+        return funcs[0]
+
+    def composed(x: WaveformTrace) -> WaveformTrace:
+        """Apply composed functions right-to-left."""
+        # Apply functions in reverse order (right to left)
+        return reduce(lambda val, func: func(val), reversed(funcs), x)
+
+    # Preserve function metadata
+    composed.__name__ = "compose(" + ", ".join(f.__name__ for f in funcs) + ")"
+    composed.__doc__ = f"Composition of {len(funcs)} functions"
+
+    return composed
+
+
+def pipe(data: WaveformTrace, *funcs: TraceFunc) -> WaveformTrace:
+    """Apply functions left-to-right: pipe(x, f, g, h) == h(g(f(x))).
+
+    Applies the given functions sequentially to the data, passing the output
+    of each function to the next. This is more intuitive for sequential
+    processing pipelines.
+
+    Args:
+        data: Initial WaveformTrace to process.
+        *funcs: Variable number of functions to apply sequentially.
+
+    Returns:
+        Transformed WaveformTrace after applying all functions.
+
+    Example:
+        >>> import oscura as tk
+        >>> # Apply operations left-to-right
+        >>> result = tk.pipe(
+        ...     trace,
+        ...     tk.low_pass(cutoff=1e6),
+        ...     tk.resample(rate=1e9),
+        ...     tk.fft(nfft=8192)
+        ... )
+        >>> # Equivalent to: fft(resample(low_pass(trace)))
+
+    Advanced Example:
+        >>> # Use with partial application
+        >>> from functools import partial
+        >>> result = tk.pipe(
+        ...     trace,
+        ...     partial(tk.low_pass, cutoff=1e6),
+        ...     partial(tk.normalize, method='zscore'),
+        ...     partial(tk.fft, nfft=8192, window='hann')
+        ... )
+
+    References:
+        API-002: Function Composition Operators
+        toolz.pipe
+    """
+    # Apply functions left-to-right
+    return reduce(lambda val, func: func(val), funcs, data)
+
+
+class Composable:
+    """Mixin class to enable >> operator for function composition.
+
+    This class provides the __rshift__ operator to enable pipe-style
+    composition using the >> syntax. Intended to be mixed into WaveformTrace
+    or used as a wrapper for transformer functions.
+
+    Example:
+        >>> # Enable >> operator on WaveformTrace
+        >>> result = trace >> low_pass(1e6) >> normalize() >> fft()
+        >>> # Equivalent to: fft(normalize(low_pass(trace)))
+
+    References:
+        API-002: Function Composition Operators
+    """
+
+    def __rshift__(self, func: Callable[[Any], Any]) -> Any:
+        """Enable >> operator for function application.
+
+        Args:
+            func: Function to apply to self.
+
+        Returns:
+            Result of applying func to self.
+
+        Example:
+            >>> result = trace >> low_pass(1e6)
+        """
+        return func(self)
+
+
+def make_composable(func: Callable[..., WaveformTrace]) -> Callable[..., TraceFunc]:
+    """Decorator to make a function support partial application and composition.
+
+    Wraps a function so it can be used in compose() and pipe() with
+    partial argument application.
+
+    Args:
+        func: Function to wrap.
+
+    Returns:
+        Wrapped function that returns a partially applied function when
+        called without a trace argument.
+
+    Example:
+        >>> @make_composable
+        ... def scale(trace, factor=1.0):
+        ...     return WaveformTrace(
+        ...         data=trace.data * factor,
+        ...         metadata=trace.metadata
+        ...     )
+        >>> # Use with partial application
+        >>> double = scale(factor=2.0)
+        >>> result = double(trace)
+        >>> # Or in pipe
+        >>> result = pipe(trace, scale(factor=2.0), scale(factor=0.5))
+
+    References:
+        API-002: Function Composition Operators
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> TraceFunc | WaveformTrace:
+        # If first arg is a WaveformTrace, apply function immediately
+        if args and isinstance(args[0], WaveformTrace):
+            return func(*args, **kwargs)
+
+        # Otherwise, return a partially applied function
+        def partial_func(trace: WaveformTrace) -> WaveformTrace:
+            return func(trace, *args, **kwargs)
+
+        return partial_func
+
+    return wrapper  # type: ignore[return-value]
+
+
+def curry(func: Callable[..., WaveformTrace]) -> Callable[..., TraceFunc]:
+    """Curry a function for easier composition.
+
+    Transforms a multi-argument function into a series of single-argument
+    functions. Useful for creating reusable transformation functions.
+
+    Args:
+        func: Function to curry.
+
+    Returns:
+        Curried version of the function.
+
+    Example:
+        >>> @curry
+        ... def scale_and_offset(trace, scale, offset):
+        ...     return WaveformTrace(
+        ...         data=trace.data * scale + offset,
+        ...         metadata=trace.metadata
+        ...     )
+        >>> # Create specialized functions
+        >>> double_and_shift = scale_and_offset(scale=2.0, offset=1.0)
+        >>> result = double_and_shift(trace)
+
+    References:
+        API-002: Function Composition Operators
+        Functional programming currying
+    """
+
+    @wraps(func)
+    def curried(*args: Any, **kwargs: Any) -> TraceFunc | WaveformTrace:
+        # If we have a WaveformTrace as first arg, apply immediately
+        if args and isinstance(args[0], WaveformTrace):
+            return func(*args, **kwargs)
+
+        # Return a function that waits for the trace
+        def partial(*more_args: Any, **more_kwargs: Any) -> WaveformTrace:
+            all_args = args + more_args
+            all_kwargs = {**kwargs, **more_kwargs}
+            return func(*all_args, **all_kwargs)
+
+        return partial
+
+    return curried  # type: ignore[return-value]
+
+
+__all__ = [
+    "Composable",
+    "compose",
+    "curry",
+    "make_composable",
+    "pipe",
+]