feat: add WelfordAlgorithm, online mean and variance in one pass (#7602)

Welford's recurrence keeps a running mean and the sum of squared deviations from it, so it never forms the large nearly equal intermediate values that make the textbook variance formula lose its significant digits, and it needs O(1) time per sample and O(1) memory regardless of the stream length.

Beyond the plain accumulation it supports removal, which runs the recurrence backwards and turns the accumulator into the statistics of a sliding window, and a static merge implementing Chan's parallel update so partial results from different shards combine exactly.

Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com>
Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com>

Author: alxkm

src/main/java/com/thealgorithms/streaming/WelfordAlgorithm.java

@@ -0,0 +1,245 @@
+package com.thealgorithms.streaming;
+
+/**
+ * Online (single pass) mean and variance using <b>Welford's algorithm</b>.
+ *
+ * <p>The textbook formula {@code Var = (sum(x^2) - n * mean^2) / (n - 1)} is fast but numerically
+ * treacherous: {@code sum(x^2)} and {@code n * mean^2} may be huge and nearly equal, so their
+ * difference loses most of its significant digits and can even come out negative. Welford's
+ * recurrence never forms those large intermediate values. It keeps only the running mean and the sum
+ * of squared deviations from that running mean, {@code M2}:
+ *
+ * <pre>
+ * n     &lt;- n + 1
+ * delta &lt;- x - mean
+ * mean  &lt;- mean + delta / n
+ * M2    &lt;- M2 + delta * (x - mean)   // note: the second factor uses the *updated* mean
+ * </pre>
+ *
+ * <p>Both {@link #add(double)} and {@link #remove(double)} run in O(1) time and the accumulator
+ * occupies O(1) memory no matter how many samples pass through it.
+ *
+ * <h2>Sliding windows and map-reduce</h2>
+ *
+ * <ul>
+ *   <li>{@link #remove(double)} runs the recurrence backwards, which turns the accumulator into the
+ *       statistics of a sliding window: feed the incoming sample to {@code add} and the sample that
+ *       just left the window to {@code remove}. Removal is the one operation that can degrade
+ *       accuracy over a very long run, since the value being removed no longer matches the mean it
+ *       was added to; recreate the accumulator periodically if that matters.</li>
+ *   <li>{@link #merge(WelfordAlgorithm, WelfordAlgorithm)} implements Chan's parallel update, so
+ *       partial results computed on different shards can be combined exactly.</li>
+ * </ul>
+ *
+ * <h2>Usage</h2>
+ *
+ * <pre>{@code
+ * WelfordAlgorithm stats = new WelfordAlgorithm();
+ * stats.add(2.0);
+ * stats.add(4.0);
+ * stats.add(4.0);
+ * stats.mean();                        // 3.3333...
+ * stats.populationStandardDeviation();  // 0.9428...
+ * }</pre>
+ *
+ * <p>This class is not thread-safe.
+ *
+ * @see ExponentialMovingAverage
+ * @see <a href="https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance">Algorithms for calculating variance</a>
+ */
+public final class WelfordAlgorithm {
+
+    private long count;
+    private double mean;
+    private double sumOfSquaredDeviations;
+
+    /**
+     * Creates an empty accumulator.
+     */
+    public WelfordAlgorithm() {
+        clear();
+    }
+
+    /**
+     * Incorporates one sample.
+     *
+     * @param value the sample to add
+     * @throws IllegalArgumentException if {@code value} is NaN or infinite
+     */
+    public void add(double value) {
+        requireFinite(value);
+        count++;
+        double delta = value - mean;
+        mean += delta / count;
+        sumOfSquaredDeviations += delta * (value - mean);
+    }
+
+    /**
+     * Incorporates every given sample, in order.
+     *
+     * @param values the samples to add
+     * @throws IllegalArgumentException if any value is NaN or infinite
+     * @throws NullPointerException if {@code values} is {@code null}
+     */
+    public void addAll(double... values) {
+        for (double value : values) {
+            add(value);
+        }
+    }
+
+    /**
+     * Removes a previously added sample, reversing {@link #add(double)}. This is what makes the
+     * accumulator usable for a sliding window.
+     *
+     * @param value the sample to remove; it must genuinely have been added before
+     * @throws IllegalStateException if the accumulator is empty
+     * @throws IllegalArgumentException if {@code value} is NaN or infinite
+     */
+    public void remove(double value) {
+        requireFinite(value);
+        if (count == 0) {
+            throw new IllegalStateException("Cannot remove a sample from an empty accumulator");
+        }
+        if (count == 1) {
+            clear();
+            return;
+        }
+        double previousMean = mean;
+        mean = (count * mean - value) / (count - 1);
+        sumOfSquaredDeviations -= (value - previousMean) * (value - mean);
+        count--;
+        if (sumOfSquaredDeviations < 0.0) {
+            sumOfSquaredDeviations = 0.0;
+        }
+    }
+
+    /**
+     * Combines two independently accumulated summaries using Chan's parallel variance update.
+     *
+     * @param left summary of the first batch of samples
+     * @param right summary of the second batch of samples
+     * @return a new summary describing the concatenation of both batches
+     * @throws NullPointerException if either argument is {@code null}
+     */
+    public static WelfordAlgorithm merge(WelfordAlgorithm left, WelfordAlgorithm right) {
+        WelfordAlgorithm merged = new WelfordAlgorithm();
+        merged.count = left.count + right.count;
+        if (merged.count == 0) {
+            return merged;
+        }
+        double delta = right.mean - left.mean;
+        merged.mean = left.mean + delta * right.count / merged.count;
+        merged.sumOfSquaredDeviations = left.sumOfSquaredDeviations + right.sumOfSquaredDeviations + delta * delta * left.count * right.count / merged.count;
+        return merged;
+    }
+
+    /**
+     * Returns the number of samples seen so far.
+     *
+     * @return the sample count
+     */
+    public long count() {
+        return count;
+    }
+
+    /**
+     * Tells whether any sample has been added.
+     *
+     * @return {@code true} if no sample is currently accounted for
+     */
+    public boolean isEmpty() {
+        return count == 0;
+    }
+
+    /**
+     * Returns the arithmetic mean of the samples.
+     *
+     * @return the mean, or {@link Double#NaN} if no sample has been added
+     */
+    public double mean() {
+        return count == 0 ? Double.NaN : mean;
+    }
+
+    /**
+     * Returns the sum of the samples, reconstructed from the mean.
+     *
+     * @return {@code count * mean}, or {@code 0} if no sample has been added
+     */
+    public double sum() {
+        return count == 0 ? 0.0 : mean * count;
+    }
+
+    /**
+     * Returns the sum of squared deviations from the mean, {@code M2}.
+     *
+     * @return the sum of squared deviations, {@code 0} for an empty accumulator
+     */
+    public double sumOfSquaredDeviations() {
+        return sumOfSquaredDeviations;
+    }
+
+    /**
+     * Returns the unbiased sample variance, normalised by {@code count - 1}.
+     *
+     * @return the sample variance, or {@link Double#NaN} if fewer than two samples were added
+     */
+    public double sampleVariance() {
+        return count < 2 ? Double.NaN : sumOfSquaredDeviations / (count - 1);
+    }
+
+    /**
+     * Returns the population variance, normalised by {@code count}.
+     *
+     * @return the population variance, or {@link Double#NaN} if no sample has been added
+     */
+    public double populationVariance() {
+        return count == 0 ? Double.NaN : sumOfSquaredDeviations / count;
+    }
+
+    /**
+     * Returns the square root of {@link #sampleVariance()}.
+     *
+     * @return the sample standard deviation, or {@link Double#NaN} if fewer than two samples were added
+     */
+    public double sampleStandardDeviation() {
+        return Math.sqrt(sampleVariance());
+    }
+
+    /**
+     * Returns the square root of {@link #populationVariance()}.
+     *
+     * @return the population standard deviation, or {@link Double#NaN} if no sample has been added
+     */
+    public double populationStandardDeviation() {
+        return Math.sqrt(populationVariance());
+    }
+
+    /**
+     * Returns the standard error of the mean, {@code sampleStandardDeviation / sqrt(count)}.
+     *
+     * @return the standard error, or {@link Double#NaN} if fewer than two samples were added
+     */
+    public double standardError() {
+        return sampleStandardDeviation() / Math.sqrt(count);
+    }
+
+    /**
+     * Forgets every sample.
+     */
+    public void clear() {
+        count = 0;
+        mean = 0.0;
+        sumOfSquaredDeviations = 0.0;
+    }
+
+    @Override
+    public String toString() {
+        return "WelfordAlgorithm{count=" + count + ", mean=" + mean() + ", sampleStandardDeviation=" + sampleStandardDeviation() + '}';
+    }
+
+    private static void requireFinite(double value) {
+        if (!Double.isFinite(value)) {
+            throw new IllegalArgumentException("Samples must be finite, but was " + value);
+        }
+    }
+}