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

smoothiepy/filter/filter2d_naive.py

@@ -0,0 +1,266 @@
+"""
+Contains the two-dimensional naive filter implementation using
+two 1D filters in x and y directions.
+"""
+from abc import ABC
+import numpy as np
+
+from smoothiepy.filter.basefilter import Filter2D, Filter1D, MovingAverageType
+from smoothiepy.filter.filter1d import (
+    SimpleMovingAverageFilter1D, WeightedMovingAverageFilter1D,
+    GaussianAverageFilter1D, MedianAverageFilter1D,
+    ExponentialMovingAverageFilter1D, CumulativeMovingAverageFilter1D,
+    FixationSmoothFilter1D, MultiPassMovingAverage1D
+)
+
+
+class NaiveFilter2D(Filter2D, ABC):
+    """
+    Provides a basic 2D filtering mechanism, where input data is processed
+    through two 1D filters (`filter_x` and `filter_y`). It is intended to serve as
+     a straightforward 2D filtering implementation that deals with basic
+     use cases of filtering in two dimensions.
+
+    :ivar filter_x: A 1D filter is applied on the x-buffer data.
+    :type filter_x: Filter1D | None
+    :ivar filter_y: A 1D filter is applied on the y-buffer data.
+    :type filter_y: Filter1D | None
+    """
+    def __init__(self):
+        super().__init__(window_size_x=1, window_size_y=1)
+        self.filter_x: Filter1D | None = None
+        self.filter_y: Filter1D | None = None
+
+    def _process_next(self, buffer_x: np.array, buffer_y: np.array) \
+            -> tuple[float | int, float | int]:
+        avg_x = self.filter_x.next(buffer_x[0])
+        avg_y = self.filter_y.next(buffer_y[0])
+        return avg_x, avg_y
+
+
+class NaiveSimpleMovingAverageFilter2D(NaiveFilter2D):
+    """
+    The NaiveSimpleMovingAverageFilter2D class implements a 2D simple moving
+    average filter. It smooths sequential data points along both x and y
+    axes using separate 1D simple moving average filters.
+
+    :param window_size: The size of the moving average window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, the
+        x-axis window size will be used for both axes.
+    :type window_size: int
+    :param window_size_y: The size of the moving average window for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis window size.
+    :type window_size_y: int
+    """
+    def __init__(self, window_size, window_size_y=None):
+        if window_size_y is None:
+            window_size_y = window_size
+        super().__init__()
+        self.filter_x = SimpleMovingAverageFilter1D(window_size=window_size)
+        self.filter_y = SimpleMovingAverageFilter1D(window_size=window_size_y)
+
+
+class NaiveWeightedMovingAverageFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that computes a weighted average of the input data over a specified window size
+    in both x and y directions. The weights are linearly decreasing from 1 to 0, applied to the
+    most recent data points.
+
+    :param window_size: The size of the weighted moving average window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, the
+        x-axis window size will be used for both axes.
+    :type window_size: int
+    :param window_size_y: The size of the weighted moving average window for the y-axis.
+    :type window_size_y: int
+    """
+    def __init__(self, window_size: int, window_size_y: int = None):
+        if window_size_y is None:
+            window_size_y = window_size
+        super().__init__()
+        self.filter_x = WeightedMovingAverageFilter1D(window_size=window_size)
+        self.filter_y = WeightedMovingAverageFilter1D(window_size=window_size_y)
+
+
+class NaiveGaussianAverageFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that implements a Gaussian Average Filter for two-dimensional data.
+    It applies a Gaussian weighting function over
+    a sliding window of data in both x and y directions.
+
+    :param window_size: The size of the Gaussian window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, the
+        x-axis window size will be used for both axes.
+    :type window_size: int
+    :param window_size_y: The size of the Gaussian window for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis window size.
+    :type window_size_y: int
+    :param std_dev_x: The standard deviation of the Gaussian distribution for the x-axis.
+        Must be a positive value. If not provided, it defaults to one-third of the window size.
+    :type std_dev_x: float
+    :param std_dev_y: The standard deviation of the Gaussian distribution for the y-axis.
+        Must be a positive value. If not provided, it defaults to one-third of the window size_y.
+    :type std_dev_y: float
+    """
+    def __init__(self, window_size: int, window_size_y: int = None,
+                 std_dev_x: float = None, std_dev_y: float = None):
+        if window_size_y is None:
+            window_size_y = window_size
+        super().__init__()
+        self.filter_x = GaussianAverageFilter1D(window_size=window_size, std_dev=std_dev_x)
+        self.filter_y = GaussianAverageFilter1D(window_size=window_size_y, std_dev=std_dev_y)
+
+
+class NaiveMedianAverageFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that computes the median of the input data over a specified
+    window size in both x and y directions.
+
+    :param window_size: The size of the median window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, the
+        x-axis window size will be used for both axes.
+    :type window_size: int
+    :param window_size_y: The size of the median window for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis window size.
+    :type window_size_y: int
+    """
+    def __init__(self, window_size: int, window_size_y: int = None):
+        if window_size_y is None:
+            window_size_y = window_size
+        super().__init__()
+        self.filter_x = MedianAverageFilter1D(window_size=window_size)
+        self.filter_y = MedianAverageFilter1D(window_size=window_size_y)
+
+
+class NaiveExponentialMovingAverageFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that implements an exponential moving average filter for two-dimensional data.
+    It applies exponential moving average weights to the current and
+    the previous filtered data points in both x and y directions.
+
+    :param alpha: The smoothing factor for the x-axis. Must be between 0 and 1 (inclusive).
+        If `alpha_y` is not provided, it will be set to the same value as `alpha`.
+    :type alpha: float
+    :param alpha_y: The smoothing factor for the y-axis. Must be between 0 and 1 (inclusive).
+        If not provided, it defaults to the x-axis alpha value.
+    :type alpha_y: float
+    """
+    def __init__(self, alpha: float, alpha_y: float = None):
+        if alpha_y is None:
+            alpha_y = alpha
+        super().__init__()
+        self.filter_x = ExponentialMovingAverageFilter1D(alpha=alpha)
+        self.filter_y = ExponentialMovingAverageFilter1D(alpha=alpha_y)
+
+
+class NaiveCumulativeMovingAverageFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that implements a cumulative moving average filter for two-dimensional data.
+    It computes the cumulative average of the input data points as they are processed,
+    updating the average with each new data point in both x and y directions.
+    """
+    def __init__(self):
+        super().__init__()
+        self.filter_x = CumulativeMovingAverageFilter1D()
+        self.filter_y = CumulativeMovingAverageFilter1D()
+
+
+class NaiveFixationSmoothFilter2D(NaiveFilter2D):
+    """
+    A 2D filter that implements a fixation smooth filter for two-dimensional data.
+    It uses a weighted averaging mechanism in conjunction with
+    standard deviation-based thresholding to determine whether to maintain
+     or update the fixation value in both x and y directions.
+
+    An example for the threshold would be calculated using the following formula:
+    ``{screen_width_px} * 0.004 + sqrt({window_size})``.
+    Where `screen_width_px` is the width of the screen in pixels and
+    `window_size` is the size of the sliding window used for the filter.
+    This could be used for eye-tracking data to smooth out noise when you fixate on a point
+    for a longer period of time.
+
+    :param window_size: The size of the sliding window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, it will be set to the
+        same value as `window_size`.
+    :type window_size: int
+    :param window_size_y: The size of the sliding window for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis window size.
+    :type window_size_y: int
+    :param threshold: The threshold value for the x-axis.
+    :type threshold: float
+    :param threshold_y: The threshold value for the y-axis.
+    :type threshold_y: float
+    """
+    def __init__(self, window_size: int, threshold: float,
+                 window_size_y: int = None, threshold_y: float = None):
+        if window_size_y is None:
+            window_size_y = window_size
+        if threshold_y is None:
+            threshold_y = threshold
+        super().__init__()
+        self.filter_x = FixationSmoothFilter1D(window_size=window_size, threshold=threshold)
+        self.filter_y = FixationSmoothFilter1D(window_size=window_size_y, threshold=threshold_y)
+
+
+class NaiveMultiPassMovingAverage2D(NaiveFilter2D):
+    """
+    A 2D filter that implements a multi-pass moving average filter for two-dimensional data.
+    It applies a user-defined number of passes over the data using the
+    specified moving average filter type in both x and y directions.
+
+    :param window_size: The size of the sliding window for the x-axis.
+        Must be a positive integer.
+        If the y-axis window size is not provided, it will be set to the
+        same value as `window_size`.
+    :type window_size: int
+    :param window_size_y: The size of the sliding window for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis window size.
+    :type window_size_y: int
+    :param num_passes: Number of passes to apply to the moving average filter for the x-axis.
+        Must be a positive integer.
+        If `num_passes_y` is not provided, it will be set to the same value as `num_passes`.
+    :type num_passes: int
+    :param num_passes_y: Number of passes to apply to the moving average filter for the y-axis.
+        Must be a positive integer.
+        If not provided, it defaults to the x-axis number of passes.
+    :type num_passes_y: int
+    :param average_filter_type_x: The type of moving average filter to use for the x-axis.
+        Defaults to ``MovingAverageType.SIMPLE``.
+        If `average_filter_type_y` is not provided, it will be set to the
+        same value as `average_filter_type_x`.
+    :type average_filter_type_x: MovingAverageType
+    :param average_filter_type_y: The type of moving average filter to use for the y-axis.
+        If not provided, it defaults to the x-axis average filter type.
+    :type average_filter_type_y: MovingAverageType
+    """
+    def __init__(self, window_size: int, num_passes: int,
+                 window_size_y: int = None, num_passes_y: int = None,
+                 average_filter_type_x: MovingAverageType = MovingAverageType.SIMPLE,
+                 average_filter_type_y: MovingAverageType = None):
+        if window_size_y is None:
+            window_size_y = window_size
+        if num_passes_y is None:
+            num_passes_y = num_passes
+        if average_filter_type_y is None:
+            average_filter_type_y = average_filter_type_x
+
+        super().__init__()
+        self.filter_x = MultiPassMovingAverage1D(
+            window_size=window_size,
+            num_passes=num_passes,
+            average_filter_type=average_filter_type_x
+        )
+        self.filter_y = MultiPassMovingAverage1D(
+            window_size=window_size_y,
+            num_passes=num_passes_y,
+            average_filter_type=average_filter_type_y
+        )

smoothiepy/smoother/builder.py

@@ -0,0 +1,110 @@
+"""
+Contains the helper classes to build a signal smoother.
+"""
+from smoothiepy.filter.basefilter import Filter1D, Filter2D
+from smoothiepy.smoother.smoother import Smoother1DContinuous, Smoother2DContinuous
+
+
+class SmootherBuilder:
+    """
+    Provides utilities for building smoother objects for data.
+
+    This class provides methods to construct smoother objects based on
+    specified dimensional requirements. It currently supports
+    one-dimensional smoother creation.
+    """
+    @staticmethod
+    def one_dimensional() -> 'Smoother1DBuilder':
+        return Smoother1DBuilder()
+
+    @staticmethod
+    def two_dimensional() -> 'Smoother2DBuilder':
+        return Smoother2DBuilder()
+
+    def set_dimensions(self, dimensions: int) -> 'Smoother1DBuilder | Smoother2DBuilder':
+        if dimensions == 1:
+            return self.one_dimensional()
+        if dimensions == 2:
+            return self.two_dimensional()
+
+        raise ValueError("Unsupported dimensions. Currently only 1D and 2D is supported.")
+
+
+class Smoother1DBuilder:
+    """
+    Provides a builder for creating 1D signal smoother instances.
+
+    This class offers static methods to initialize builders for smoothing
+    operations tailored to different types of data. It simplifies the
+    creation of signal smoother objects by providing predefined builder
+    methods.
+    """
+    @staticmethod
+    def continuous() -> 'Smoother1DContinuousBuilder':
+        return Smoother1DContinuousBuilder()
+
+
+class Smoother2DBuilder:
+    """
+    Provides a builder for creating 2D signal smoother instances.
+
+    This class offers static methods to initialize builders for smoothing
+    operations tailored to different types of data. It simplifies the
+    creation of signal smoother objects by providing predefined builder
+    methods.
+    """
+    @staticmethod
+    def set_continuous() -> 'Smoother2DContinuousBuilder':
+        return Smoother2DContinuousBuilder()
+
+
+class Smoother1DContinuousBuilder:
+    """
+    A builder class for creating 1D continuous signal smoother.
+
+    This class facilitates the creation and configuration of a 1D continuous
+    signal smoother by allowing filters to be attached and then constructing
+    the smoother object.
+    """
+    def __init__(self):
+        self.__smoother = Smoother1DContinuous()
+
+    def attach_filter(self, filter_obj: Filter1D) -> 'Smoother1DContinuousBuilder':
+        self.__smoother.attach_filter(filter_obj)
+        return self
+
+    def build(self) -> Smoother1DContinuous:
+        self.__smoother.build()
+        return self.__smoother
+
+
+class Smoother2DContinuousBuilder:
+    """
+    A builder class for creating 2D continuous signal smoother.
+
+    This class facilitates the creation and configuration of a 2D continuous
+    signal smoother by allowing filters to be attached and then constructing
+    the smoother object.
+    """
+    def __init__(self):
+        self.__smoother = Smoother2DContinuous()
+
+    def attach_filter(self, filter_obj: Filter2D) -> 'Smoother2DContinuousBuilder':
+        self.__smoother.attach_filter(filter_obj)
+        return self
+
+    def build(self) -> Smoother2DContinuous:
+        self.__smoother.build()
+        return self.__smoother
+
+
+# class SignalSmootherBuilder1DList:
+#     def __init__(self):
+#         self.smoother = SignalSmootherSeparateLists1D()
+#
+#     def attach_filter(self, filter_obj: BaseFilter1D):
+#         self.smoother.attach_filter(filter_obj)
+#
+#     def build(self):
+#         self.smoother.build()
+#         return self.smoother

smoothiepy/smoother/smoother.py

@@ -0,0 +1,200 @@
+"""
+Contains the Signal Smoother class which is the main class to smooth signals.
+"""
+from abc import ABC, abstractmethod
+from smoothiepy.filter.basefilter import Filter, Filter1D, Filter2D
+
+
+class Smoother(ABC):
+    """
+    Represents an abstract base class for smoothing signals by attaching and managing filters.
+
+    This class is designed as a foundation for implementing specific signal smoothing
+    strategies. It provides a structure for managing filters and implementing custom
+    signal smoothing logic.
+
+    :ivar filter_list: A list that holds the filters attached to this smoother.
+    :type filter_list: list[Filter]
+    """
+    def __init__(self):
+        self.filter_list: list[Filter] = []
+
+    @abstractmethod
+    def attach_filter(self, filter_obj: Filter) -> None:
+        """
+        Attaches a filter object to the implementing class.
+
+        :param filter_obj: The filter object to attach.
+        :type filter_obj: Filter
+        """
+
+    @abstractmethod
+    def build(self):
+        """
+        Builds the final configuration of the smoother, setting up the filters
+        and their parameters as needed.
+
+        :raises NotImplementedError: If the subclass does not implement this method.
+        """
+
+
+class Smoother1D(Smoother, ABC):
+    """
+    Provides one-dimensional signal smoothing functionality.
+
+    This class is an extension of the ``Smoother`` class designed specifically
+    for one-dimensional signal data. It maintains a list of 1D filters and allows
+    attachment of additional filters which must be of type Filter1D.
+
+    :ivar filter_list: Stores instances of Filter1D for smoothing operations.
+    :type filter_list: list[Filter1D]
+    """
+    def __init__(self):
+        super().__init__()
+        self.filter_list: list[Filter1D] = []
+
+    def attach_filter(self, filter_obj: Filter) -> None:
+        if not isinstance(filter_obj, Filter1D):
+            raise TypeError("filter_obj must be an 1D filter")
+
+        self.filter_list.append(filter_obj)
+
+
+class Smoother1DContinuous(Smoother1D):
+    """
+    A class for continuously smoothing one-dimensional data.
+
+    Provides functionality to smooth incoming data points in a continuous manner
+    using a list of filters.
+    The smoothed value is updated as new data points are added.
+
+    :ivar last_filtered_value: Stores the most recent smoothed value.
+    :type last_filtered_value: float | int
+    """
+    def __init__(self):
+        super().__init__()
+        self.last_filtered_value: float | int = 0.0
+
+    def build(self):
+        pass
+        # self.filter_list[-1].set_buffer_size(1)
+        # for cur_filter, next_filter in zip(self.filter_list, self.filter_list[1:]):
+        #     cur_filter.set_buffer_size(next_filter.window_size)
+
+    def add_and_get(self, data: float | int) -> float | int:
+        """
+        Adds the given data to the signal smoother and returns the filtered value.
+
+        :param data: The numeric value to be added.
+        :type data: float | int
+        :return: Filtered value after the input has been added.
+        :rtype: float | int
+        """
+        self.add(data)
+        return self.get()
+
+    def add(self, data: float | int) -> None:
+        """
+        Adds a new data point to the signal smoother.
+
+        :param data: The data point to be added.
+        :type data: float | int
+        """
+        temp_filtered_value = data
+        for cur_filter in self.filter_list:
+            temp_filtered_value = cur_filter.next(temp_filtered_value)
+
+        self.last_filtered_value = temp_filtered_value
+
+    def get(self) -> float | int:
+        """
+        Retrieves the smoothed value from the signal smoother.
+
+        :return: The smoothed value.
+        :rtype: float | int
+        """
+        return self.last_filtered_value
+
+
+class Smoother2D(Smoother, ABC):
+    """
+    Provides two-dimensional signal smoothing functionality.
+
+    This class is an extension of the ``Smoother`` class designed specifically
+    for two-dimensional signal data. It maintains a list of 2D filters and allows
+    attachment of additional filters which must be of type Filter2D.
+
+    :ivar filter_list: Stores instances of Filter2D for smoothing operations.
+    :type filter_list: list[Filter2D]
+    """
+    def __init__(self):
+        super().__init__()
+        self.filter_list: list[Filter2D] = []
+
+    def attach_filter(self, filter_obj: Filter) -> None:
+        if not isinstance(filter_obj, Filter2D):
+            raise TypeError("filter_obj must be an 2D filter")
+
+        self.filter_list.append(filter_obj)
+
+
+class Smoother2DContinuous(Smoother2D):
+    """
+        A class for continuously smoothing two-dimensional data.
+
+        Provides functionality to smooth incoming data points in a continuous manner
+        using a list of filters.
+        The smoothed value is updated as new data points are added.
+
+        :ivar last_filtered_value: Stores the most recent smoothed value.
+        :type last_filtered_value: float | int
+        """
+    def __init__(self):
+        super().__init__()
+        self.last_filtered_value: tuple[float | int, float | int] = (0.0, 0.0)
+
+    def build(self):
+        pass
+
+    def add_and_get(self, data_x: float | int, data_y: float | int) \
+            -> tuple[float | int, float | int]:
+        """
+        Adds the given data to the signal smoother and returns the filtered value.
+
+        :param data_x: The first numeric value to be added.
+        :type data_x: float | int
+        :param data_y: The second numeric value to be added.
+        :type data_y: float | int
+        :return: Filtered value after the input has been added.
+        :rtype: float | int
+        """
+        self.add(data_x=data_x, data_y=data_y)
+        return self.get()
+
+    def add(self, data_x: float | int, data_y: float | int) -> None:
+        """
+        Adds a new data point to the signal smoother.
+
+         :param data_x: The first numeric value to be added.
+        :type data_x: float | int
+        :param data_y: The second numeric value to be added.
+        :type data_y: float | int
+        """
+        temp_filtered_value = data_x, data_y
+        for cur_filter in self.filter_list:
+            temp_filtered_value = cur_filter.next(temp_filtered_value)
+
+        self.last_filtered_value = temp_filtered_value
+
+    def get(self) -> tuple[float | int, float | int]:
+        """
+        Retrieves the smoothed value from the signal smoother.
+
+        :return: The smoothed value.
+        :rtype: float | int
+        """
+        return self.last_filtered_value
+
+# class SignalSmootherSeparateLists1D:
+#     def filter_list(self, signal: list[float]) -> list[float]:
+#         return signal