dspx 0.1.1-alpha.0

package/src/native/core/MovingVarianceFilter.h

@@ -0,0 +1,114 @@
+#pragma once
+
+#include "../utils/CircularBufferArray.h"
+#include <utility>
+#include <vector>
+#include <cmath>
+#include <stdexcept> // for noexcept
+#include <algorithm> // for std::max
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements an efficient Moving Variance filter.
+     *
+     * This class uses a circular buffer to store the last 'N' samples
+     * and maintains a running sum AND a running sum-of-squares
+     * for O(1) variance calculation using the formula:
+     * Variance = (Mean of Squares) - (Mean)^2
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class MovingVarianceFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new Moving Variance Filter.
+         * @param window_size The number of samples to average over (N).
+         */
+        explicit MovingVarianceFilter(size_t window_size);
+
+        /**
+         * @brief Constructs a new time-aware Moving Variance Filter.
+         * @param window_size The buffer capacity in samples.
+         * @param window_duration_ms The time window duration in milliseconds.
+         */
+        explicit MovingVarianceFilter(size_t window_size, double window_duration_ms);
+
+        // Delete copy constructor and copy assignment
+        MovingVarianceFilter(const MovingVarianceFilter &) = delete;
+        MovingVarianceFilter &operator=(const MovingVarianceFilter &) = delete;
+
+        // Enable move semantics
+        MovingVarianceFilter(MovingVarianceFilter &&) noexcept = default;
+        MovingVarianceFilter &operator=(MovingVarianceFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter.
+         *
+         * This updates the running sums and the internal circular buffer.
+         * The new variance value is calculated and returned.
+         *
+         * @param newValue The new sample value to add.
+         * @return T The new moving variance.
+         */
+        T addSample(T newValue);
+
+        /**
+         * @brief Adds a new sample with timestamp (time-aware mode).
+         *
+         * Expires old samples, rebuilds statistics, then adds new sample.
+         *
+         * @param newValue The new sample value to add.
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The new moving variance.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp);
+
+        /**
+         * @brief Gets the current moving variance.
+         * @return T The variance of the samples currently in the buffer.
+         */
+        T getVariance() const;
+
+        /**
+         * @brief Clears all samples from the filter and resets the sums.
+         */
+        void clear();
+
+        /**
+         * @brief Checks if the filter's buffer is full (i.e., has N samples).
+         * @return true if the buffer is full, false otherwise.
+         */
+        bool isFull() const noexcept;
+
+        /**
+         * @brief Checks if the filter is in time-aware mode.
+         * @return true if time-aware, false otherwise.
+         */
+        bool isTimeAware() const noexcept;
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing:
+         * 1. The buffer contents (std::vector<T>)
+         * 2. A pair of sums (running_sum, running_sum_of_squares)
+         */
+        std::pair<std::vector<T>, std::pair<T, T>> getState() const;
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param bufferData The buffer contents to restore.
+         * @param sum The running sum to restore.
+         * @param sumOfSquares The running sum of squares to restore.
+         */
+        void setState(const std::vector<T> &bufferData, T sum, T sumOfSquares);
+
+    private:
+        dsp::utils::CircularBufferArray<T> buffer;
+        T running_sum;
+        T running_sum_of_squares;
+        size_t window_size;
+    };
+} // namespace dsp::core

package/src/native/core/MovingZScoreFilter.cc

@@ -0,0 +1,215 @@
+#include "MovingZScoreFilter.h"
+
+using namespace dsp::core;
+
+// -----------------------------------------------------------------------------
+// Constructor
+// -----------------------------------------------------------------------------
+template <typename T>
+MovingZScoreFilter<T>::MovingZScoreFilter(size_t window_size, T epsilon)
+    : buffer(window_size), // Initialize the circular buffer
+      running_sum(0),
+      running_sum_of_squares(0),
+      window_size(window_size),
+      m_epsilon(epsilon)
+{
+    if (window_size == 0)
+    {
+        throw std::invalid_argument("Window size must be greater than 0");
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Time-aware Constructor
+// -----------------------------------------------------------------------------
+template <typename T>
+MovingZScoreFilter<T>::MovingZScoreFilter(size_t window_size, double window_duration_ms, T epsilon)
+    : buffer(window_size, window_duration_ms), // Initialize time-aware circular buffer
+      running_sum(0),
+      running_sum_of_squares(0),
+      window_size(window_size),
+      m_epsilon(epsilon)
+{
+    if (window_size == 0)
+    {
+        throw std::invalid_argument("Window size must be greater than 0");
+    }
+    if (window_duration_ms <= 0.0)
+    {
+        throw std::invalid_argument("Window duration must be greater than 0");
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Method: addSample
+// -----------------------------------------------------------------------------
+template <typename T>
+T MovingZScoreFilter<T>::addSample(T newValue)
+{
+    T oldestValue = 0;
+
+    // If the buffer is full, get the oldest value
+    if (buffer.isFull())
+    {
+        oldestValue = buffer.peek();
+    }
+
+    // Add the new value to the buffer
+    buffer.pushOverwrite(newValue);
+
+    // Update running sums
+    T oldestValueSquared = oldestValue * oldestValue;
+    T newValueSquared = newValue * newValue;
+
+    running_sum = running_sum - oldestValue + newValue;
+    running_sum_of_squares = running_sum_of_squares - oldestValueSquared + newValueSquared;
+
+    // --- Calculate new stats ---
+    size_t count = buffer.getCount();
+    T countT = static_cast<T>(count);
+
+    // Calculate mean
+    T mean = running_sum / countT;
+
+    // Calculate mean of squares
+    T mean_of_squares = running_sum_of_squares / countT;
+
+    // Variance = E[X^2] - (E[X])^2
+    T variance = std::max(static_cast<T>(0), mean_of_squares - (mean * mean));
+
+    // Standard Deviation
+    T stddev = std::sqrt(variance);
+
+    // --- Calculate Z-Score ---
+    // Use epsilon to prevent division by zero
+    if (stddev < m_epsilon)
+    {
+        return 0; // If stddev is ~0, all values are the mean, so z-score is 0
+    }
+    else
+    {
+        return (newValue - mean) / stddev;
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Method: addSampleWithTimestamp
+// -----------------------------------------------------------------------------
+template <typename T>
+T MovingZScoreFilter<T>::addSampleWithTimestamp(T newValue, double timestamp)
+{
+    // Expire old samples
+    size_t expired_count = buffer.expireOld(timestamp);
+
+    // Rebuild running statistics if samples were expired
+    if (expired_count > 0)
+    {
+        running_sum = 0;
+        running_sum_of_squares = 0;
+
+        auto remaining = buffer.toVector();
+        for (const auto &value : remaining)
+        {
+            running_sum += value;
+            running_sum_of_squares += value * value;
+        }
+    }
+
+    // Add new sample
+    T oldestValue = 0;
+    if (buffer.isFull())
+    {
+        oldestValue = buffer.peek();
+    }
+
+    buffer.pushOverwriteWithTimestamp(newValue, timestamp);
+
+    // Update running sums
+    T oldestValueSquared = oldestValue * oldestValue;
+    T newValueSquared = newValue * newValue;
+
+    running_sum = running_sum - oldestValue + newValue;
+    running_sum_of_squares = running_sum_of_squares - oldestValueSquared + newValueSquared;
+
+    // --- Calculate new stats ---
+    size_t count = buffer.getCount();
+    T countT = static_cast<T>(count);
+
+    // Calculate mean
+    T mean = running_sum / countT;
+
+    // Calculate mean of squares
+    T mean_of_squares = running_sum_of_squares / countT;
+
+    // Variance = E[X^2] - (E[X])^2
+    T variance = std::max(static_cast<T>(0), mean_of_squares - (mean * mean));
+
+    // Standard Deviation
+    T stddev = std::sqrt(variance);
+
+    // --- Calculate Z-Score ---
+    if (stddev < m_epsilon)
+    {
+        return 0; // If stddev is ~0, all values are the mean, so z-score is 0
+    }
+    else
+    {
+        return (newValue - mean) / stddev;
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Method: clear
+// -----------------------------------------------------------------------------
+template <typename T>
+void MovingZScoreFilter<T>::clear()
+{
+    buffer.clear();
+    running_sum = 0;
+    running_sum_of_squares = 0;
+}
+
+// -----------------------------------------------------------------------------
+// Method: isFull
+// -----------------------------------------------------------------------------
+template <typename T>
+bool MovingZScoreFilter<T>::isFull() const noexcept
+{
+    return buffer.isFull();
+}
+
+// -----------------------------------------------------------------------------
+// Method: isTimeAware
+// -----------------------------------------------------------------------------
+template <typename T>
+bool MovingZScoreFilter<T>::isTimeAware() const noexcept
+{
+    return buffer.isTimeAware();
+}
+
+// -----------------------------------------------------------------------------
+// Method: getState
+// -----------------------------------------------------------------------------
+template <typename T>
+std::pair<std::vector<T>, std::pair<T, T>> MovingZScoreFilter<T>::getState() const
+{
+    return {buffer.toVector(), {running_sum, running_sum_of_squares}};
+}
+
+// -----------------------------------------------------------------------------
+// Method: setState
+// -----------------------------------------------------------------------------
+template <typename T>
+void MovingZScoreFilter<T>::setState(const std::vector<T> &bufferData, T sum, T sumOfSquares)
+{
+    buffer.fromVector(bufferData);
+    running_sum = sum;
+    running_sum_of_squares = sumOfSquares;
+}
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class MovingZScoreFilter<float>;
+    template class MovingZScoreFilter<double>;
+}

package/src/native/core/MovingZScoreFilter.h

@@ -0,0 +1,113 @@
+#pragma once
+
+#include "../utils/CircularBufferArray.h"
+#include <utility>
+#include <vector>
+#include <cmath>
+#include <stdexcept>
+#include <algorithm> // for std::max
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements an efficient Moving Z-Score normalization filter.
+     *
+     * This class uses a circular buffer to store the last 'N' samples
+     * and maintains a running sum AND a running sum-of-squares
+     * for O(1) mean and standard deviation calculation.
+     *
+     * Z-Score = (Value - Mean) / StandardDeviation
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class MovingZScoreFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new Moving Z-Score Filter.
+         * @param window_size The number of samples to average over (N).
+         * @param epsilon A small value to prevent division by zero (default 1e-6).
+         */
+        explicit MovingZScoreFilter(size_t window_size, T epsilon = 1e-6);
+
+        /**
+         * @brief Constructs a new time-aware Moving Z-Score Filter.
+         * @param window_size The buffer capacity in samples.
+         * @param window_duration_ms The time window duration in milliseconds.
+         * @param epsilon A small value to prevent division by zero (default 1e-6).
+         */
+        explicit MovingZScoreFilter(size_t window_size, double window_duration_ms, T epsilon = 1e-6);
+
+        // Delete copy constructor and copy assignment
+        MovingZScoreFilter(const MovingZScoreFilter &) = delete;
+        MovingZScoreFilter &operator=(const MovingZScoreFilter &) = delete;
+
+        // Enable move semantics
+        MovingZScoreFilter(MovingZScoreFilter &&) noexcept = default;
+        MovingZScoreFilter &operator=(MovingZScoreFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter and returns its Z-Score.
+         *
+         * This updates the running sums and the internal circular buffer.
+         * The Z-Score of the new sample is calculated based on the
+         * *new* window statistics (including the sample just added).
+         *
+         * @param newValue The new sample value to add.
+         * @return T The Z-Score of the new sample.
+         */
+        T addSample(T newValue);
+
+        /**
+         * @brief Adds a new sample with timestamp and returns its Z-Score.
+         *
+         * Expires old samples, rebuilds statistics, then adds new sample.
+         *
+         * @param newValue The new sample value to add.
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The Z-Score of the new sample.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp);
+
+        /**
+         * @brief Clears all samples from the filter and resets the sums.
+         */
+        void clear();
+
+        /**
+         * @brief Checks if the filter's buffer is full (i.e., has N samples).
+         * @return true if the buffer is full, false otherwise.
+         */
+        bool isFull() const noexcept;
+
+        /**
+         * @brief Checks if the filter is in time-aware mode.
+         * @return true if time-aware, false otherwise.
+         */
+        bool isTimeAware() const noexcept;
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing:
+         * 1. The buffer contents (std::vector<T>)
+         * 2. A pair of sums (running_sum, running_sum_of_squares)
+         */
+        std::pair<std::vector<T>, std::pair<T, T>> getState() const;
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param bufferData The buffer contents to restore.
+         * @param sum The running sum to restore.
+         * @param sumOfSquares The running sum of squares to restore.
+         */
+        void setState(const std::vector<T> &bufferData, T sum, T sumOfSquares);
+
+    private:
+        dsp::utils::CircularBufferArray<T> buffer;
+        T running_sum;
+        T running_sum_of_squares;
+        size_t window_size;
+        T m_epsilon;
+    };
+} // namespace dsp::core