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

smoothiepy/__init__.py

@@ -1 +0,0 @@
-print("Easing with this one! [From smoothiepy]")

smoothiepy/core.py

@@ -0,0 +1,32 @@
+"""
+Main module for the application.
+"""
+from smoothiepy.smoother.builder import SmootherBuilder
+from smoothiepy.filter.filter1d import ExponentialMovingAverageFilter1D
+
+def main() -> None:
+    """
+    Main function to demonstrate and test the usage of the Signal Smoother.
+    """
+    smoother = (
+        SmootherBuilder()
+        .one_dimensional()
+        .continuous()
+        .attach_filter(ExponentialMovingAverageFilter1D(alpha=0.25))
+        .build()
+    )
+
+    print("Init finished")
+
+    smoother.add(40.0)
+    print(f"Smoothed value 1: {smoother.get()}")
+    smoother.add(60.0)
+    print(f"Smoothed value 2: {smoother.get()}")
+    smoother.add(100.0)
+    print(f"Smoothed value 3: {smoother.get()}")
+    smoother.add(3)
+    print(f"Smoothed value 4: {smoother.get()}")
+
+
+if __name__ == "__main__":
+    main()

smoothiepy/filter/basefilter.py

@@ -0,0 +1,122 @@
+"""
+Base module that defines the abstract base class for all signal filters.
+"""
+import enum
+from abc import ABC, abstractmethod
+from collections import deque
+import numpy as np
+
+
+class Filter(ABC):
+    """
+    Abstract base class for all signal filters.
+    """
+
+
+class Filter1D(Filter, ABC):
+    """
+    Abstract base class for all one-dimensional signal filters.
+    :param window_size: The size of the window for the filter. Must be a positive integer.
+    :type window_size: int
+    :ivar window_size: The size of the window for the filter.
+    :type window_size: int
+    :raises ValueError: If window_size is not a positive integer.
+    """
+    def __init__(self, window_size: int):
+        if window_size <= 0:
+            raise ValueError("window_size must be greater than 0")
+        self.window_size = window_size
+        self.buffer = deque(maxlen=window_size)
+        self.last_buffer_value: float | int = 0.0
+
+    def next(self, data: float | int) -> float | int:
+        """
+        Processes the next data point by adding it to the buffer
+        and calling the internal processing method.
+
+        :param data: The next data point to be processed.
+        :type data: float | int
+        :return: The filtered value.
+        :rtype: float | int
+        """
+        self.last_buffer_value = self.buffer[0] if self.buffer else 0.0
+        self.buffer.append(data)
+        return self._process_next(np.array(self.buffer))
+
+    @abstractmethod
+    def _process_next(self, buffer: np.array) -> float | int:
+        """
+        Processes the next data point using the current buffer data.
+
+        :param buffer: The current buffer data.
+        :type buffer: list[float | int]
+        :return: The processed value.
+        :rtype: float | int
+        """
+
+
+class Filter2D(Filter, ABC):
+    """
+    Abstract base class for all two-dimensional signal filters.
+    This class is currently a placeholder and does not implement any methods.
+    It serves as a base for future two-dimensional filter implementations.
+    """
+    def __init__(self, window_size_x: int, window_size_y: int):
+        """
+        Initializes the 2D filter with specified window sizes.
+
+        :param window_size_x: The size of the window in the x-direction. Must be a positive integer.
+        :type window_size_x: int
+        :param window_size_y: The size of the window in the y-direction. Must be a positive integer.
+        :type window_size_y: int
+        """
+        if window_size_x <= 0 or window_size_y <= 0:
+            raise ValueError("window_size_x and window_size_y must be greater than 0")
+        self.window_size_x = window_size_x
+        self.window_size_y = window_size_y
+        self.buffer_x = deque(maxlen=window_size_x)
+        self.buffer_y = deque(maxlen=window_size_y)
+
+    def next(self, data_x: float | int, data_y: float | int) -> tuple[float | int, float | int]:
+        """
+        Processes the next data point in both x and y dimensions by adding
+        them to their respective buffers and calling the internal processing method.
+
+        :param data_x: The next data point in the x dimension.
+        :type data_x: float | int
+        :param data_y: The next data point in the y dimension.
+        :type data_y: float | int
+        :return: A tuple containing the filtered values for x and y dimensions.
+        :rtype: tuple[float | int, float | int]
+        """
+        self.buffer_x.append(data_x)
+        self.buffer_y.append(data_y)
+        return self._process_next(np.array(self.buffer_x), np.array(self.buffer_y))
+
+    @abstractmethod
+    def _process_next(self, buffer_x: np.array, buffer_y: np.array) \
+            -> tuple[float | int, float | int]:
+        """
+        Processes the next data points using the current buffer data in both x and y dimensions.
+
+        :param buffer_x: The current buffer data in the x dimension.
+        :type buffer_x: np.array
+        :param buffer_y: The current buffer data in the y dimension.
+        :type buffer_y: np.array
+        :return: A tuple containing the processed values for x and y dimensions.
+        :rtype: tuple[float | int, float | int]
+        """
+
+
+class MovingAverageType(enum.Enum):
+    """
+    Enum for different types of moving averages.
+
+    This enum defines the types of moving averages that can be applied to signals.
+    """
+    SIMPLE = "simple"
+    WEIGHTED = "weighted"
+    GAUSSIAN = "gaussian"
+    MEDIAN = "median"
+    EXPONENTIAL = "exponential"
+    CUMULATIVE = "cumulative"

smoothiepy/filter/filter1d.py

@@ -0,0 +1,324 @@
+"""
+Contains the one-dimensional filters used for signal processing.
+"""
+from abc import ABC, abstractmethod
+import numpy as np
+from typing_extensions import deprecated
+
+from smoothiepy.filter.basefilter import MovingAverageType, Filter1D
+from smoothiepy.smoother.builder import SmootherBuilder
+
+
+# TODO versions for list data -> also account for future data
+
+@deprecated("Filter has no use, why would you use it?")
+class UselessFilter1D(Filter1D):
+    """
+    A filter that does not perform any filtering.
+    It simply returns the input data as is.
+    """
+    def __init__(self):
+        super().__init__(window_size=1)
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        return buffer[0]
+
+
+class OffsetFilter1D(Filter1D):
+    """
+    A filter that applies a constant offset to the input data.
+
+    :param offset: The constant value to be added to the input data.
+    :type offset: float | int
+    """
+    def __init__(self, offset: float | int):
+        super().__init__(window_size=1)
+        self.offset = offset
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        return buffer[0] + self.offset
+
+
+class KernelMovingAverageFilter1D(Filter1D, ABC):
+    """
+    KernelMovingAverageFilter1D is an abstract base class that implements a kernel-based moving
+    average filter in one dimension.
+
+    This class processes data using weights constructed for the filter,
+    providing a weighted average over a defined window size. The weights are
+    normalized automatically during processing.
+
+    :ivar weights: Weights for the kernel moving average filter, calculated by
+        the `_construct_weights` method.
+    :type weights: np.array
+    :ivar weights_sum: Precomputed sum of the weights, used for normalization in
+        the filtering process.
+    :type weights_sum: float
+    """
+    def __init__(self, window_size: int):
+        super().__init__(window_size)
+        self.weights = self._construct_weights()
+        self.weights_sum = self.weights.sum()
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        if len(buffer) < self.window_size:
+            offset = self.window_size - len(buffer)
+            weighted_sum = np.sum(buffer * self.weights[offset:])
+            cur_weights_sum = self.weights[offset:].sum()
+            if cur_weights_sum == 0:
+                return 0.0
+            return weighted_sum / cur_weights_sum
+
+        weighted_sum = np.sum(buffer * self.weights)
+        return weighted_sum / self.weights_sum
+
+    @abstractmethod
+    def _construct_weights(self) -> np.array:
+        """
+        Constructs the weights for the kernel moving average filter.
+        This method should be implemented by subclasses to define
+        how the weights are calculated based on the window size.
+
+        The weights don't have to sum up to 1, they are normalized
+        during the processing step.
+
+        :return: An array of weights for the kernel moving average filter.
+        :rtype: np.array
+        """
+
+
+class SimpleMovingAverageFilter1D(KernelMovingAverageFilter1D):
+    """
+    A filter that computes the average of the input data over a specified window size.
+    No weighting is applied, and the average is computed
+    as a simple arithmetic mean of the values in the buffer.
+
+    If not enough data points are available to fill the window,
+    it computes the average of the available data points.
+
+    :ivar window_size: The size of the window for averaging.
+    :type window_size: int
+    """
+    def _construct_weights(self) -> np.array:
+        return np.ones(self.window_size) / self.window_size
+
+class WeightedMovingAverageFilter1D(KernelMovingAverageFilter1D):
+    """
+    A filter that computes a weighted average of the input data over a specified window size.
+    The weights are linearly decreasing from 1 to 0, applied to the most recent data points.
+
+    If not enough data points are available to fill the window,
+    it computes the weighted average of the available data points.
+
+    :ivar window_size: The size of the sliding window used for the filter.
+    :type window_size: int
+    """
+    def _construct_weights(self) -> np.array:
+        return np.linspace(1, 0, self.window_size)
+
+
+class GaussianAverageFilter1D(KernelMovingAverageFilter1D):
+    """
+    Implements a Gaussian Average Filter for one-dimensional data.
+
+    Incorporating a Gaussian weighting function applied over a sliding window of data.
+    It is used for smoothing data by placing higher importance on values closer more
+    recent values of the window while progressively down-weighting values farther away.
+    The Gaussian distribution is controlled via the window size and standard deviation parameters.
+
+     If not enough data points are available to fill the window,
+    it computes the gaussian average of the available data points with
+    a trimmed gaussian filter.
+
+    The filter is only relying on previous data values in the buffer, not future values
+     which would result in a delay / offset in the output.
+
+    :param window_size: Size of the sliding window used for the filter.
+    :type window_size: int
+    :param std_dev: The standard deviation of the Gaussian distribution that determines the spread.
+        Must be a positive value.
+    :type std_dev: float
+    :raises ValueError: If std_dev is negative.
+    """
+    def __init__(self, window_size: int, std_dev: float = None):
+        if std_dev is None:
+            std_dev = window_size / 3
+        if std_dev <= 0:
+            raise ValueError("std_dev must be a positive value")
+        self.std_dev = std_dev
+        super().__init__(window_size)
+
+    def _construct_weights(self) -> np.array:
+        """
+        Constructs Gaussian weights based on the specified window size
+        and standard deviation.The weights are not centered around zero,
+        but rather they are computed from the window size down to zero.
+        The most recent data points are given more weight than older ones.
+
+        :return: Computed array of Gaussian weights with length equal to the window size
+        :rtype: np.array
+        """
+        lin_space = np.linspace(self.window_size, 0, self.window_size) \
+            if self.window_size % 2 == 0 else np.linspace(self.window_size, 0, self.window_size)
+        gaussian = np.exp(-0.5 * (lin_space / self.std_dev) ** 2)
+        return gaussian
+
+
+class MedianAverageFilter1D(Filter1D):
+    def _process_next(self, buffer: np.array) -> float | int:
+        return np.median(buffer).astype(float)
+
+
+class ExponentialMovingAverageFilter1D(Filter1D):
+    """
+    Implements a one-dimensional exponential moving average filter.
+
+    This filter applies exponential moving average weights
+     to the current and the previous filtered data point.
+    The smoothing factor (alpha) determines the weight given to the most recent data point
+    compared to the previous filtered value.
+
+    :ivar alpha: The smoothing factor. Must be between 0 and 1 (inclusive).
+    :type alpha: float
+    """
+    def __init__(self, alpha: float):
+        super().__init__(window_size=1)
+        if not 0 <= alpha <= 1:
+            raise ValueError("Alpha must be between 0 and 1")
+
+        self.alpha = alpha
+        self.__inverted_alpha = 1 - alpha
+        self.latest_filtered_value: float | int = 0.0
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        if not self.latest_filtered_value:
+            self.latest_filtered_value = buffer[0]
+            return buffer[0]
+
+        self.latest_filtered_value = ((self.alpha * buffer[0])
+                                      + (self.__inverted_alpha * self.latest_filtered_value))
+        return self.latest_filtered_value
+
+
+class CumulativeMovingAverageFilter1D(Filter1D):
+    """
+    Implements a one-dimensional cumulative moving average filter.
+
+    This filter computes the cumulative average of the input data points
+    as they are processed, updating the average with each new data point.
+
+    :ivar cumulative_average: The current cumulative average of the input data.
+    :type cumulative_average: float | int
+    """
+    def __init__(self):
+        super().__init__(window_size=1)
+        self.cumulative_average = 0.0
+        self.count = 0
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        self.count += 1
+        self.cumulative_average += (buffer[0] - self.cumulative_average) / self.count
+        return self.cumulative_average
+
+
+class FixationSmoothFilter1D(Filter1D):
+    """
+    A filter class to smooth fixation-like data in 1D. This is a type of deadband filter.
+
+    It uses a weighted averaging mechanism in conjunction with standard deviation-based
+    thresholding to determine whether to maintain or update the fixation value. The purpose
+    of this filter is to smooth out noise while preserving significant data trends.
+
+    The noise will be reduced by checking the standard deviation of the data in the buffer
+    and comparing the latest data value with the current fixation value. If both checks pass,
+    the current fixation value is returned. Otherwise, a new fixation value is computed
+    using a weighted average of the data in the buffer.
+
+    Note that this filter cuts out noise totally. It will not smooth out noise.
+
+    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.
+
+    :ivar window_size: The size of the sliding window for the filter.
+    :type window_size: int
+    :ivar threshold: The threshold value used for standard deviation and fixation value difference
+                     checks.
+    :type threshold: float
+    :ivar fixation_value: The current fixation value being tracked by the filter.
+    :type fixation_value: float
+    :ivar average_weights: A numpy array of weights used for computing weighted averages
+                           over the input data buffer.
+    :type average_weights: numpy.ndarray
+    """
+    def __init__(self, window_size: int, threshold: float):
+        super().__init__(window_size)
+        self.threshold = threshold
+        self.fixation_value = 0.0
+        self.average_weights = np.linspace(0.2, 1.0, window_size)
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        std_dev = np.std(buffer)
+        latest_data_value = buffer[-1]
+
+        if (abs(std_dev) <= self.threshold
+                and abs(self.fixation_value - latest_data_value) <= self.threshold):
+            return self.fixation_value
+
+        if len(buffer) < self.window_size:
+            offset = self.window_size - len(buffer)
+            self.fixation_value = np.average(buffer, weights=self.average_weights[offset:])
+        else:
+            self.fixation_value = np.average(buffer, weights=self.average_weights)
+        return latest_data_value
+
+
+class MultiPassMovingAverage1D(Filter1D):
+    """
+    This class implements a one-dimensional multi-pass moving average filter.
+
+    The MultiPassMovingAverage1D class applies a user-defined number of passes
+    over the data using the specified moving average filter type. It allows
+    different types of moving averages, such as simple, weighted, Gaussian,
+    and median.
+
+    :param window_size: The size of the sliding window for the filter.
+    :type window_size: int
+    :param num_passes: Number of passes to apply to the moving average filter.
+    :type num_passes: int
+    :param average_filter_type: The type of moving average filter to use.
+    :type average_filter_type: MovingAverageType
+    """
+    def __init__(self, window_size: int, num_passes: int,
+                 average_filter_type: MovingAverageType = MovingAverageType.SIMPLE):
+        super().__init__(window_size=1)
+        if num_passes <= 0:
+            raise ValueError("num_passes must be greater than 0")
+
+        self.num_passes = num_passes
+        self.average_filter_type = average_filter_type
+
+        smoother = (
+            SmootherBuilder()
+                .one_dimensional()
+                .continuous()
+            )
+        for _ in range(num_passes):
+            if average_filter_type == MovingAverageType.SIMPLE:
+                smoother.attach_filter(SimpleMovingAverageFilter1D(window_size))
+            elif average_filter_type == MovingAverageType.WEIGHTED:
+                smoother.attach_filter(WeightedMovingAverageFilter1D(window_size))
+            elif average_filter_type == MovingAverageType.GAUSSIAN:
+                smoother.attach_filter(GaussianAverageFilter1D(window_size,
+                                                               std_dev=window_size / 3))
+            elif average_filter_type == MovingAverageType.MEDIAN:
+                smoother.attach_filter(MedianAverageFilter1D(window_size))
+            else:
+                raise ValueError(f"Unsupported average filter type: {average_filter_type}")
+        self.smoother = smoother.build()
+
+    def _process_next(self, buffer: np.array) -> float | int:
+        return self.smoother.add_and_get(buffer[0])

smoothiepy/filter/filter2d.py

@@ -0,0 +1,41 @@
+"""
+Contains the two-dimensional filters used for signal processing.
+"""
+
+import numpy as np
+
+from smoothiepy.filter.basefilter import Filter2D
+
+
+class OffsetFilter2D(Filter2D):
+    """
+    A 2D filter that applies a fixed offset to input data on both x and y axes.
+    Can be used in scenarios where a shift in data coordinates is required.
+
+    :param offset: Offset value to be applied to the x-axis data.
+        If `offset_y` is not provided, it will be set to the same value as `offset`.
+    :type offset: int | float
+    :param offset_y: Offset value to be applied to the y-axis data.
+        If not provided, it defaults to the same value as `offset`.
+    :type offset_y: int | float
+    """
+    def __init__(self, offset, offset_y = None):
+        if offset_y is None:
+            offset_y = offset
+        super().__init__(window_size_x=1, window_size_y=1)
+        self.offset_x = offset
+        self.offset_y = offset_y
+
+    def _process_next(self, buffer_x: np.array, buffer_y: np.array) \
+            -> tuple[float | int, float | int]:
+        """
+        Processes the next data point by applying an offset to the input buffers.
+
+        :param buffer_x: The current buffer data for the x-axis.
+        :type buffer_x: np.array
+        :param buffer_y: The current buffer data for the y-axis.
+        :type buffer_y: np.array
+        :return: A tuple containing the processed values for x and y axes.
+        :rtype: tuple[float | int, float | int]
+        """
+        return buffer_x[0] + self.offset_x, buffer_y[0] + self.offset_y