congrads 1.0.7__py3-none-any.whl → 1.1.0__py3-none-any.whl

congrads/transformations.py

@@ -1,139 +1,116 @@
-"""
-This module defines the abstract base class `Transformation` and two
-specific transformations: `IdentityTransformation` and `DenormalizeMinMax`.
-These transformations are used to apply operations to neuron data.
-
-Classes:
-
-    - Transformation: An abstract base class for transformations that
-      can be applied to neuron data. Subclasses must implement the
-      `__call__` method to apply the transformation.
-    - IdentityTransformation: A subclass of `Transformation` that
-      returns the input data unchanged.
-    - DenormalizeMinMax: A subclass of `Transformation` that denormalizes
-      input data based on specified minimum and maximum values.
-
-Key Methods:
-
-    - `__call__(data: Tensor) -> Tensor`: Abstract method in the 
-      `Transformation` class that must be implemented by subclasses to apply 
-      a transformation to the input data.
-    - `__init__(neuron_name: str)`: Initializes the transformation with the
-      associated neuron name.
-    - `IdentityTransformation.__call__(data: Tensor) -> Tensor`: Returns
-      the input data without applying any transformation.
-    - `DenormalizeMinMax.__call__(data: Tensor) -> Tensor`: Denormalizes
-      the input data by scaling it based on the specified min and max values.
-
-The `Transformation` class is intended as a base class for creating
-custom transformations for neuron data, while the `IdentityTransformation`
-is used when no transformation is desired, and `DenormalizeMinMax` is used
-for reversing the normalization process by using a min-max scaling approach.
-"""
+"""Module defining transformations and components."""
 
 from abc import ABC, abstractmethod
 from numbers import Number
 
 from torch import Tensor
 
-from .utils import validate_type
+from .utils import validate_callable, validate_type
 
 
 class Transformation(ABC):
-    """
-    Abstract base class for transformations applied to neuron data.
+    """Abstract base class for tag data transformations."""
 
-    Args:
-        neuron_name (str): The name of the neuron associated with
-            the transformation.
+    def __init__(self, tag: str):
+        """Initialize a Transformation.
 
-    Methods:
-        __call__(data: Tensor) -> Tensor:
-            Applies the transformation to the provided data.
-            Must be implemented by subclasses.
-    """
-
-    def __init__(self, neuron_name: str):
-        validate_type("neuron_name", neuron_name, str)
+        Args:
+            tag (str): Tag this transformation applies to.
+        """
+        validate_type("tag", tag, str)
 
         super().__init__()
-        self.neuron_name = neuron_name
+        self.tag = tag
 
     @abstractmethod
     def __call__(self, data: Tensor) -> Tensor:
-        """
-        Abstract method to apply the transformation to the given data.
+        """Apply the transformation to the input tensor.
 
         Args:
-            data (Tensor): The input data to be transformed.
+            data (Tensor): Input tensor representing network data.
 
         Returns:
-            Tensor: The transformed data.
+            Tensor: Transformed tensor.
 
-        Must be implemented by subclasses.
+        Raises:
+            NotImplementedError: Must be implemented by subclasses.
         """
         raise NotImplementedError
 
 
 class IdentityTransformation(Transformation):
-    """
-    A transformation that returns the data unchanged (identity transformation).
-
-    Inherits from the Transformation class and implements the
-    __call__ method to return the input data as is.
-    """
+    """A transformation that returns the input unchanged."""
 
     def __call__(self, data: Tensor) -> Tensor:
-        """
-        Returns the input data without any transformation.
+        """Return the input tensor without any modification.
 
         Args:
-            data (Tensor): The input data to be returned as is.
+            data (Tensor): Input tensor.
 
         Returns:
-            Tensor: The unchanged input data.
+            Tensor: The same input tensor.
         """
         return data
 
 
 class DenormalizeMinMax(Transformation):
-    """
-    A transformation that denormalizes data based on a
-    specified min and max value.
-
-    This transformation scales the data by the range of the min and max values,
-    then adds the min value to denormalize it back to the original scale.
-
-    Args:
-        neuron_name (str): The name of the neuron associated with
-            the transformation.
-        min (Number): The minimum value to scale the data.
-        max (Number): The maximum value to scale the data.
-
-    Methods:
-        __call__(data: Tensor) -> Tensor:
-            Applies the denormalization to the given data by scaling it
-            with the min and max values.
-    """
-
-    # pylint: disable-next=redefined-builtin
-    def __init__(self, neuron_name: str, min: Number, max: Number):
+    """A transformation that denormalizes data using min-max scaling."""
+
+    def __init__(self, tag: str, min: Number, max: Number):
+        """Initialize a min-max denormalization transformation.
+
+        Args:
+            tag (str): Tag this transformation applies to.
+            min (Number): Minimum value used for denormalization.
+            max (Number): Maximum value used for denormalization.
+        """
         validate_type("min", min, Number)
         validate_type("max", max, Number)
 
-        super().__init__(neuron_name)
+        super().__init__(tag)
 
         self.min = min
         self.max = max
 
     def __call__(self, data: Tensor) -> Tensor:
-        """
-        Denormalizes the input data based on the min and max values.
+        """Denormalize the input tensor using the min-max range.
 
         Args:
-            data (Tensor): The normalized input data to be denormalized.
+            data (Tensor): Normalized input tensor (typically in range [0, 1]).
 
         Returns:
-            Tensor: The denormalized data.
+            Tensor: Denormalized tensor in the range [min, max].
         """
         return data * (self.max - self.min) + self.min
+
+
+class ApplyOperator(Transformation):
+    """A transformation that applies a binary operator to the input tensor."""
+
+    def __init__(self, tag: str, operator: callable, value: Number):
+        """Initialize an operator-based transformation.
+
+        Args:
+            tag (str): Tag this transformation applies to.
+            operator (callable): A callable that takes two arguments (tensor, value)
+                and returns a tensor.
+            value (Number): The value to use as the second argument in the operator.
+        """
+        validate_callable("operator", operator)
+        validate_type("value", value, Number)
+
+        super().__init__(tag)
+
+        self.operator = operator
+        self.value = value
+
+    def __call__(self, data: Tensor) -> Tensor:
+        """Apply the operator to the input tensor and the specified value.
+
+        Args:
+            data (Tensor): Input tensor.
+
+        Returns:
+            Tensor: Result of applying `operator(data, value)`.
+        """
+        return self.operator(data, self.value)