smoothiepy 0.1.1
Smooth real-time data streams like eye tracking or sensor input with this lightweight package.
Requires Python: >=3.10.0
Keywords: smoothing, data-smoothing, signal-filter, signal-processing, noise-reduction, real-time, low-latency, live-data, online-processing, streaming-data, data-cleaning, data-filtering, preprocessing, adaptive-filter, ema, moving-average, median-filter, gaussian-smoothing, time-series, trend-analysis, rolling-average, forecasting, financial-data, stock-market, price-smoothing, volatility-reduction, algorithmic-trading, market-data, quantitative-analysis, data-denoising, eye-tracking, gaze-tracking, gaze-analysis, saccade-filtering, fixation-detection, attention-analysis, input-smoothing, cursor-smoothing, head-tracking, sensor-data, tracking-noise, motion-smoothing, imu-data, robotics, embedded-systems, wearable-sensors, biosignal-processing, hci, bci, gesture-recognition, computer-vision, biometrics, machine-learning, feature-extraction, data-preparation, computational-neuroscience, neurotechnology, psychophysics, real-time-processing, live-inference, python, smoothiepy, signal-analysis, time-series-preprocessing

<img src="https://github.com/user-attachments/assets/74e96edd-efe9-4a76-9f13-499c7f5ea551" alt="Logo SmoothiePy" width="400"/>

[![Status](https://img.shields.io/badge/status-alpha-lightblue)]()
[![PyPI version](https://img.shields.io/pypi/v/smoothiepy)](https://pypi.org/project/smoothiepy/)
[![Python versions](https://img.shields.io/pypi/pyversions/smoothiepy)](https://pypi.org/project/smoothiepy/)
[![Downloads](https://img.shields.io/pypi/dm/smoothiepy)](https://pypi.org/project/smoothiepy/)
[![License](https://img.shields.io/github/license/timoseyfarth/smoothiepy)](https://github.com/timoseyfarth/smoothiepy/blob/main/LICENSE)
[![Last Commit](https://img.shields.io/github/last-commit/timoseyfarth/smoothiepy)](https://github.com/timoseyfarth/smoothiepy/commits/main)
[![Repo Size](https://img.shields.io/github/repo-size/timoseyfarth/smoothiepy)](https://github.com/timoseyfarth/smoothiepy)

Smooth real-time data streams like eye tracking or sensor input with this lightweight package.

## 📋 Overview

SmoothiePy is a Python library designed for smoothing real-time data streams with minimal latency. 
It provides a collection of filters and smoothers that can be applied to one-dimensional and two-dimensional data, 
making it ideal for applications such as:

- Eye tracking and gaze analysis
- Sensor data processing
- Motion tracking
- Financial data analysis
- Time series preprocessing
- Signal processing

The library is built with a focus on flexibility, performance, and ease of use, allowing you to quickly implement sophisticated data smoothing pipelines.

## 🚀 Installation

```bash
pip install smoothiepy
```

SmoothiePy requires Python 3.10 or later.

## 🏁 Quick Start

Here's a simple example of how to use SmoothiePy to smooth a data stream:

```python
from smoothiepy import SmootherBuilder, ExponentialMovingAverageFilter1D

# Create a smoother with an exponential moving average filter
smoother = (
  SmootherBuilder()
  .one_dimensional()
  .continuous()
  .attach_filter(ExponentialMovingAverageFilter1D(alpha=0.2))
  .build()
)

# Process data points
smoother.add(20.0)
print(f"Smoothed value: {smoother.get()}")

smoother.add(60.0)
print(f"Smoothed value: {smoother.get()}")

# Alternatively, use add_and_get to add a value and get the result in one step
smoothed_value = smoother.add_and_get(3.0)
print(f"Smoothed value: {smoothed_value}")
```

## ✨ Features

### Available Filters

SmoothiePy provides a variety of filters:

#### One-Dimensional Filters

- **Offset Filter**: Adds a constant offset to the data
- **Simple Moving Average**: Computes the arithmetic mean over a window
- **Weighted Moving Average**: Applies linearly decreasing weights
- **Gaussian Average**: Applies a Gaussian weighting function
- **Median Average**: Computes the median of values in a window
- **Exponential Moving Average**: Applies exponential weighting
- **Cumulative Moving Average**: Computes the cumulative average
- **Fixation Smooth Filter**: Sort of Deadband filter. Specialized for fixation-like data (e.g., eye tracking)
- **Multi-Pass Moving Average**: Applies multiple passes of a specified moving average type

#### Two-Dimensional Filters

Each 1D filter is also available in a 2D version, allowing you to smooth data in two dimensions (e.g., x-y coordinates).

Many more filters are work in progress, including advanced filters like Kalman filters and more complex multidimensional filters.

### Builder Pattern

SmoothiePy uses a builder pattern to create smoothers, making it easy to configure and chain multiple filters:

```python
from smoothiepy import SmootherBuilder, SimpleMovingAverageFilter1D, GaussianAverageFilter1D

# Create a smoother with multiple filters
smoother = (
  SmootherBuilder()
  .one_dimensional()
  .continuous()
  .attach_filter(SimpleMovingAverageFilter1D(window_size=5))
  .attach_filter(GaussianAverageFilter1D(window_size=3, std_dev=1.0))
  .build()
)
```

## 📚 Documentation

For detailed documentation, visit the [GitHub Wiki](https://github.com/timoseyfarth/smoothiepy/wiki).
Work in progress...

### API Reference

#### 1D Filters

- `OffsetFilter1D`: Adds a constant offset
- `SimpleMovingAverageFilter1D`: Simple arithmetic mean
- `WeightedMovingAverageFilter1D`: Linearly decreasing weights
- `GaussianAverageFilter1D`: Gaussian weighting function
- `MedianAverageFilter1D`: Median of values
- `ExponentialMovingAverageFilter1D`: Exponential weighting
- `CumulativeMovingAverageFilter1D`: Cumulative average
- `FixationSmoothFilter1D`: For fixation-like data
- `MultiPassMovingAverage1D`: Multiple passes of a specified filter

#### 2D Filters

- `OffsetFilter2D`: Adds a constant offset in 2D
- `SimpleMovingAverageFilter2D`: Simple arithmetic mean in 2D
- `WeightedMovingAverageFilter2D`: Linearly decreasing weights in 2D
- `GaussianAverageFilter2D`: Gaussian weighting function in 2D
- `MedianAverageFilter2D`: Median of values in 2D
- `ExponentialMovingAverageFilter2D`: Exponential weighting in 2D
- `CumulativeMovingAverageFilter2D`: Cumulative average in 2D
- `FixationSmoothFilter2D`: For fixation-like data in 2D
- `MultiPassMovingAverage2D`: Multiple passes of a specified filter in 2D

#### Builder

- `SmootherBuilder`: Entry point for creating smoothers

## 📄 License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0) — see the LICENSE file in the git repo for details.

## 📬 Contact

Timo Seyfarth - timo@seyfarth.dev