guava/src/com/google/common/math/StatsAccumulator.java - platform/external/guava - Git at Google

 /*
  * Copyright (C) 2012 The Guava Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
  * in compliance with the License. You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software distributed under the License
  * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */

 package com.google.common.math;

 import static com.google.common.base.Preconditions.checkState;
 import static com.google.common.math.DoubleUtils.ensureNonNegative;
 import static com.google.common.primitives.Doubles.isFinite;
 import static java.lang.Double.NaN;
 import static java.lang.Double.isNaN;

 import com.google.common.annotations.Beta;
 import com.google.common.annotations.GwtIncompatible;
 import java.util.Iterator;

 /**
  * A mutable object which accumulates double values and tracks some basic statistics over all the
  * values added so far. The values may be added singly or in groups. This class is not thread safe.
  *
  * @author Pete Gillin
  * @author Kevin Bourrillion
  * @since 20.0
  */
 @Beta
 @GwtIncompatible
 public final class StatsAccumulator {

   // These fields must satisfy the requirements of Stats' constructor as well as those of the stat
   // methods of this class.
   private long count = 0;
   private double mean = 0.0; // any finite value will do, we only use it to multiply by zero for sum
   private double sumOfSquaresOfDeltas = 0.0;
   private double min = NaN; // any value will do
   private double max = NaN; // any value will do

   /** Adds the given value to the dataset. */
   public void add(double value) {
     if (count == 0) {
       count = 1;
       mean = value;
       min = value;
       max = value;
       if (!isFinite(value)) {
         sumOfSquaresOfDeltas = NaN;
       }
     } else {
       count++;
       if (isFinite(value) && isFinite(mean)) {
         // Art of Computer Programming vol. 2, Knuth, 4.2.2, (15) and (16)
         double delta = value - mean;
         mean += delta / count;
         sumOfSquaresOfDeltas += delta * (value - mean);
       } else {
         mean = calculateNewMeanNonFinite(mean, value);
         sumOfSquaresOfDeltas = NaN;
       }
       min = Math.min(min, value);
       max = Math.max(max, value);
     }
   }

   /**
    * Adds the given values to the dataset.
    *
    * @param values a series of values, which will be converted to {@code double} values (this may
    *     cause loss of precision)
    */
   public void addAll(Iterable<? extends Number> values) {
     for (Number value : values) {
       add(value.doubleValue());
     }
   }

   /**
    * Adds the given values to the dataset.
    *
    * @param values a series of values, which will be converted to {@code double} values (this may
    *     cause loss of precision)
    */
   public void addAll(Iterator<? extends Number> values) {
     while (values.hasNext()) {
       add(values.next().doubleValue());
     }
   }

   /**
    * Adds the given values to the dataset.
    *
    * @param values a series of values
    */
   public void addAll(double... values) {
     for (double value : values) {
       add(value);
     }
   }

   /**
    * Adds the given values to the dataset.
    *
    * @param values a series of values
    */
   public void addAll(int... values) {
     for (int value : values) {
       add(value);
     }
   }

   /**
    * Adds the given values to the dataset.
    *
    * @param values a series of values, which will be converted to {@code double} values (this may
    *     cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))
    */
   public void addAll(long... values) {
     for (long value : values) {
       add(value);
     }
   }

   /**
    * Adds the given statistics to the dataset, as if the individual values used to compute the
    * statistics had been added directly.
    */
   public void addAll(Stats values) {
     if (values.count() == 0) {
       return;
     }

     if (count == 0) {
       count = values.count();
       mean = values.mean();
       sumOfSquaresOfDeltas = values.sumOfSquaresOfDeltas();
       min = values.min();
       max = values.max();
     } else {
       count += values.count();
       if (isFinite(mean) && isFinite(values.mean())) {
         // This is a generalized version of the calculation in add(double) above.
         double delta = values.mean() - mean;
         mean += delta * values.count() / count;
         sumOfSquaresOfDeltas +=
             values.sumOfSquaresOfDeltas() + delta * (values.mean() - mean) * values.count();
       } else {
         mean = calculateNewMeanNonFinite(mean, values.mean());
         sumOfSquaresOfDeltas = NaN;
       }
       min = Math.min(min, values.min());
       max = Math.max(max, values.max());
     }
   }

   /** Returns an immutable snapshot of the current statistics. */
   public Stats snapshot() {
     return new Stats(count, mean, sumOfSquaresOfDeltas, min, max);
   }

   /** Returns the number of values. */
   public long count() {
     return count;
   }

   /**
    * Returns the <a href="http://en.wikipedia.org/wiki/Arithmetic_mean">arithmetic mean</a> of the
    * values. The count must be non-zero.
    *
    * <p>If these values are a sample drawn from a population, this is also an unbiased estimator of
    * the arithmetic mean of the population.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
    * contains both {@link Double#POSITIVE_INFINITY} and {@link Double#NEGATIVE_INFINITY} then the
    * result is {@link Double#NaN}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
    * only or {@link Double#POSITIVE_INFINITY} only, the result is {@link Double#POSITIVE_INFINITY}.
    * If it contains {@link Double#NEGATIVE_INFINITY} and finite values only or {@link
    * Double#NEGATIVE_INFINITY} only, the result is {@link Double#NEGATIVE_INFINITY}.
    *
    * @throws IllegalStateException if the dataset is empty
    */
   public double mean() {
     checkState(count != 0);
     return mean;
   }

   /**
    * Returns the sum of the values.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
    * contains both {@link Double#POSITIVE_INFINITY} and {@link Double#NEGATIVE_INFINITY} then the
    * result is {@link Double#NaN}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
    * only or {@link Double#POSITIVE_INFINITY} only, the result is {@link Double#POSITIVE_INFINITY}.
    * If it contains {@link Double#NEGATIVE_INFINITY} and finite values only or {@link
    * Double#NEGATIVE_INFINITY} only, the result is {@link Double#NEGATIVE_INFINITY}.
    */
   public final double sum() {
     return mean * count;
   }

   /**
    * Returns the <a href="http://en.wikipedia.org/wiki/Variance#Population_variance">population
    * variance</a> of the values. The count must be non-zero.
    *
    * <p>This is guaranteed to return zero if the dataset contains only exactly one finite value. It
    * is not guaranteed to return zero when the dataset consists of the same value multiple times,
    * due to numerical errors. However, it is guaranteed never to return a negative result.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
    * Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
    *
    * @throws IllegalStateException if the dataset is empty
    */
   public final double populationVariance() {
     checkState(count != 0);
     if (isNaN(sumOfSquaresOfDeltas)) {
       return NaN;
     }
     if (count == 1) {
       return 0.0;
     }
     return ensureNonNegative(sumOfSquaresOfDeltas) / count;
   }

   /**
    * Returns the <a
    * href="http://en.wikipedia.org/wiki/Standard_deviation#Definition_of_population_values">
    * population standard deviation</a> of the values. The count must be non-zero.
    *
    * <p>This is guaranteed to return zero if the dataset contains only exactly one finite value. It
    * is not guaranteed to return zero when the dataset consists of the same value multiple times,
    * due to numerical errors. However, it is guaranteed never to return a negative result.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
    * Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
    *
    * @throws IllegalStateException if the dataset is empty
    */
   public final double populationStandardDeviation() {
     return Math.sqrt(populationVariance());
   }

   /**
    * Returns the <a href="http://en.wikipedia.org/wiki/Variance#Sample_variance">unbiased sample
    * variance</a> of the values. If this dataset is a sample drawn from a population, this is an
    * unbiased estimator of the population variance of the population. The count must be greater than
    * one.
    *
    * <p>This is not guaranteed to return zero when the dataset consists of the same value multiple
    * times, due to numerical errors. However, it is guaranteed never to return a negative result.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
    * Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
    *
    * @throws IllegalStateException if the dataset is empty or contains a single value
    */
   public final double sampleVariance() {
     checkState(count > 1);
     if (isNaN(sumOfSquaresOfDeltas)) {
       return NaN;
     }
     return ensureNonNegative(sumOfSquaresOfDeltas) / (count - 1);
   }

   /**
    * Returns the <a
    * href="http://en.wikipedia.org/wiki/Standard_deviation#Corrected_sample_standard_deviation">
    * corrected sample standard deviation</a> of the values. If this dataset is a sample drawn from a
    * population, this is an estimator of the population standard deviation of the population which
    * is less biased than {@link #populationStandardDeviation()} (the unbiased estimator depends on
    * the distribution). The count must be greater than one.
    *
    * <p>This is not guaranteed to return zero when the dataset consists of the same value multiple
    * times, due to numerical errors. However, it is guaranteed never to return a negative result.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
    * Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
    *
    * @throws IllegalStateException if the dataset is empty or contains a single value
    */
   public final double sampleStandardDeviation() {
     return Math.sqrt(sampleVariance());
   }

   /**
    * Returns the lowest value in the dataset. The count must be non-zero.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
    * contains {@link Double#NEGATIVE_INFINITY} and not {@link Double#NaN} then the result is {@link
    * Double#NEGATIVE_INFINITY}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
    * only then the result is the lowest finite value. If it contains {@link
    * Double#POSITIVE_INFINITY} only then the result is {@link Double#POSITIVE_INFINITY}.
    *
    * @throws IllegalStateException if the dataset is empty
    */
   public double min() {
     checkState(count != 0);
     return min;
   }

   /**
    * Returns the highest value in the dataset. The count must be non-zero.
    *
    * <h3>Non-finite values</h3>
    *
    * <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
    * contains {@link Double#POSITIVE_INFINITY} and not {@link Double#NaN} then the result is {@link
    * Double#POSITIVE_INFINITY}. If it contains {@link Double#NEGATIVE_INFINITY} and finite values
    * only then the result is the highest finite value. If it contains {@link
    * Double#NEGATIVE_INFINITY} only then the result is {@link Double#NEGATIVE_INFINITY}.
    *
    * @throws IllegalStateException if the dataset is empty
    */
   public double max() {
     checkState(count != 0);
     return max;
   }

   double sumOfSquaresOfDeltas() {
     return sumOfSquaresOfDeltas;
   }

   /**
    * Calculates the new value for the accumulated mean when a value is added, in the case where at
    * least one of the previous mean and the value is non-finite.
    */
   static double calculateNewMeanNonFinite(double previousMean, double value) {
     /*
      * Desired behaviour is to match the results of applying the naive mean formula. In particular,
      * the update formula can subtract infinities in cases where the naive formula would add them.
      *
      * Consequently:
      * 1. If the previous mean is finite and the new value is non-finite then the new mean is that
      *    value (whether it is NaN or infinity).
      * 2. If the new value is finite and the previous mean is non-finite then the mean is unchanged
      *    (whether it is NaN or infinity).
      * 3. If both the previous mean and the new value are non-finite and...
      * 3a. ...either or both is NaN (so mean != value) then the new mean is NaN.
      * 3b. ...they are both the same infinities (so mean == value) then the mean is unchanged.
      * 3c. ...they are different infinities (so mean != value) then the new mean is NaN.
      */
     if (isFinite(previousMean)) {
       // This is case 1.
       return value;
     } else if (isFinite(value) || previousMean == value) {
       // This is case 2. or 3b.
       return previousMean;
     } else {
       // This is case 3a. or 3c.
       return NaN;
     }
   }
 }
	/*
	* Copyright (C) 2012 The Guava Authors
	*
	* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
	* in compliance with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software distributed under the License
	* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
	* or implied. See the License for the specific language governing permissions and limitations under
	* the License.
	*/

	package com.google.common.math;

	import static com.google.common.base.Preconditions.checkState;
	import static com.google.common.math.DoubleUtils.ensureNonNegative;
	import static com.google.common.primitives.Doubles.isFinite;
	import static java.lang.Double.NaN;
	import static java.lang.Double.isNaN;

	import com.google.common.annotations.Beta;
	import com.google.common.annotations.GwtIncompatible;
	import java.util.Iterator;

	/**
	* A mutable object which accumulates double values and tracks some basic statistics over all the
	* values added so far. The values may be added singly or in groups. This class is not thread safe.
	*
	* @author Pete Gillin
	* @author Kevin Bourrillion
	* @since 20.0
	*/
	@Beta
	@GwtIncompatible
	public final class StatsAccumulator {

	// These fields must satisfy the requirements of Stats' constructor as well as those of the stat
	// methods of this class.
	private long count = 0;
	private double mean = 0.0; // any finite value will do, we only use it to multiply by zero for sum
	private double sumOfSquaresOfDeltas = 0.0;
	private double min = NaN; // any value will do
	private double max = NaN; // any value will do

	/** Adds the given value to the dataset. */
	public void add(double value) {
	if (count == 0) {
	count = 1;
	mean = value;
	min = value;
	max = value;
	if (!isFinite(value)) {
	sumOfSquaresOfDeltas = NaN;
	}
	} else {
	count++;
	if (isFinite(value) && isFinite(mean)) {
	// Art of Computer Programming vol. 2, Knuth, 4.2.2, (15) and (16)
	double delta = value - mean;
	mean += delta / count;
	sumOfSquaresOfDeltas += delta * (value - mean);
	} else {
	mean = calculateNewMeanNonFinite(mean, value);
	sumOfSquaresOfDeltas = NaN;
	}
	min = Math.min(min, value);
	max = Math.max(max, value);
	}
	}

	/**
	* Adds the given values to the dataset.
	*
	* @param values a series of values, which will be converted to {@code double} values (this may
	* cause loss of precision)
	*/
	public void addAll(Iterable<? extends Number> values) {
	for (Number value : values) {
	add(value.doubleValue());
	}
	}

	/**
	* Adds the given values to the dataset.
	*
	* @param values a series of values, which will be converted to {@code double} values (this may
	* cause loss of precision)
	*/
	public void addAll(Iterator<? extends Number> values) {
	while (values.hasNext()) {
	add(values.next().doubleValue());
	}
	}

	/**
	* Adds the given values to the dataset.
	*
	* @param values a series of values
	*/
	public void addAll(double... values) {
	for (double value : values) {
	add(value);
	}
	}

	/**
	* Adds the given values to the dataset.
	*
	* @param values a series of values
	*/
	public void addAll(int... values) {
	for (int value : values) {
	add(value);
	}
	}

	/**
	* Adds the given values to the dataset.
	*
	* @param values a series of values, which will be converted to {@code double} values (this may
	* cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))
	*/
	public void addAll(long... values) {
	for (long value : values) {
	add(value);
	}
	}

	/**
	* Adds the given statistics to the dataset, as if the individual values used to compute the
	* statistics had been added directly.
	*/
	public void addAll(Stats values) {
	if (values.count() == 0) {
	return;
	}

	if (count == 0) {
	count = values.count();
	mean = values.mean();
	sumOfSquaresOfDeltas = values.sumOfSquaresOfDeltas();
	min = values.min();
	max = values.max();
	} else {
	count += values.count();
	if (isFinite(mean) && isFinite(values.mean())) {
	// This is a generalized version of the calculation in add(double) above.
	double delta = values.mean() - mean;
	mean += delta * values.count() / count;
	sumOfSquaresOfDeltas +=
	values.sumOfSquaresOfDeltas() + delta * (values.mean() - mean) * values.count();
	} else {
	mean = calculateNewMeanNonFinite(mean, values.mean());
	sumOfSquaresOfDeltas = NaN;
	}
	min = Math.min(min, values.min());
	max = Math.max(max, values.max());
	}
	}

	/** Returns an immutable snapshot of the current statistics. */
	public Stats snapshot() {
	return new Stats(count, mean, sumOfSquaresOfDeltas, min, max);
	}

	/** Returns the number of values. */
	public long count() {
	return count;
	}

	/**
	* Returns the <a href="http://en.wikipedia.org/wiki/Arithmetic_mean">arithmetic mean</a> of the
	* values. The count must be non-zero.
	*
	* <p>If these values are a sample drawn from a population, this is also an unbiased estimator of
	* the arithmetic mean of the population.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
	* contains both {@link Double#POSITIVE_INFINITY} and {@link Double#NEGATIVE_INFINITY} then the
	* result is {@link Double#NaN}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
	* only or {@link Double#POSITIVE_INFINITY} only, the result is {@link Double#POSITIVE_INFINITY}.
	* If it contains {@link Double#NEGATIVE_INFINITY} and finite values only or {@link
	* Double#NEGATIVE_INFINITY} only, the result is {@link Double#NEGATIVE_INFINITY}.
	*
	* @throws IllegalStateException if the dataset is empty
	*/
	public double mean() {
	checkState(count != 0);
	return mean;
	}

	/**
	* Returns the sum of the values.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
	* contains both {@link Double#POSITIVE_INFINITY} and {@link Double#NEGATIVE_INFINITY} then the
	* result is {@link Double#NaN}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
	* only or {@link Double#POSITIVE_INFINITY} only, the result is {@link Double#POSITIVE_INFINITY}.
	* If it contains {@link Double#NEGATIVE_INFINITY} and finite values only or {@link
	* Double#NEGATIVE_INFINITY} only, the result is {@link Double#NEGATIVE_INFINITY}.
	*/
	public final double sum() {
	return mean * count;
	}

	/**
	* Returns the <a href="http://en.wikipedia.org/wiki/Variance#Population_variance">population
	* variance</a> of the values. The count must be non-zero.
	*
	* <p>This is guaranteed to return zero if the dataset contains only exactly one finite value. It
	* is not guaranteed to return zero when the dataset consists of the same value multiple times,
	* due to numerical errors. However, it is guaranteed never to return a negative result.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
	* Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
	*
	* @throws IllegalStateException if the dataset is empty
	*/
	public final double populationVariance() {
	checkState(count != 0);
	if (isNaN(sumOfSquaresOfDeltas)) {
	return NaN;
	}
	if (count == 1) {
	return 0.0;
	}
	return ensureNonNegative(sumOfSquaresOfDeltas) / count;
	}

	/**
	* Returns the <a
	* href="http://en.wikipedia.org/wiki/Standard_deviation#Definition_of_population_values">
	* population standard deviation</a> of the values. The count must be non-zero.
	*
	* <p>This is guaranteed to return zero if the dataset contains only exactly one finite value. It
	* is not guaranteed to return zero when the dataset consists of the same value multiple times,
	* due to numerical errors. However, it is guaranteed never to return a negative result.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
	* Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
	*
	* @throws IllegalStateException if the dataset is empty
	*/
	public final double populationStandardDeviation() {
	return Math.sqrt(populationVariance());
	}

	/**
	* Returns the <a href="http://en.wikipedia.org/wiki/Variance#Sample_variance">unbiased sample
	* variance</a> of the values. If this dataset is a sample drawn from a population, this is an
	* unbiased estimator of the population variance of the population. The count must be greater than
	* one.
	*
	* <p>This is not guaranteed to return zero when the dataset consists of the same value multiple
	* times, due to numerical errors. However, it is guaranteed never to return a negative result.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
	* Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
	*
	* @throws IllegalStateException if the dataset is empty or contains a single value
	*/
	public final double sampleVariance() {
	checkState(count > 1);
	if (isNaN(sumOfSquaresOfDeltas)) {
	return NaN;
	}
	return ensureNonNegative(sumOfSquaresOfDeltas) / (count - 1);
	}

	/**
	* Returns the <a
	* href="http://en.wikipedia.org/wiki/Standard_deviation#Corrected_sample_standard_deviation">
	* corrected sample standard deviation</a> of the values. If this dataset is a sample drawn from a
	* population, this is an estimator of the population standard deviation of the population which
	* is less biased than {@link #populationStandardDeviation()} (the unbiased estimator depends on
	* the distribution). The count must be greater than one.
	*
	* <p>This is not guaranteed to return zero when the dataset consists of the same value multiple
	* times, due to numerical errors. However, it is guaranteed never to return a negative result.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains any non-finite values ({@link Double#POSITIVE_INFINITY}, {@link
	* Double#NEGATIVE_INFINITY}, or {@link Double#NaN}) then the result is {@link Double#NaN}.
	*
	* @throws IllegalStateException if the dataset is empty or contains a single value
	*/
	public final double sampleStandardDeviation() {
	return Math.sqrt(sampleVariance());
	}

	/**
	* Returns the lowest value in the dataset. The count must be non-zero.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
	* contains {@link Double#NEGATIVE_INFINITY} and not {@link Double#NaN} then the result is {@link
	* Double#NEGATIVE_INFINITY}. If it contains {@link Double#POSITIVE_INFINITY} and finite values
	* only then the result is the lowest finite value. If it contains {@link
	* Double#POSITIVE_INFINITY} only then the result is {@link Double#POSITIVE_INFINITY}.
	*
	* @throws IllegalStateException if the dataset is empty
	*/
	public double min() {
	checkState(count != 0);
	return min;
	}

	/**
	* Returns the highest value in the dataset. The count must be non-zero.
	*
	* <h3>Non-finite values</h3>
	*
	* <p>If the dataset contains {@link Double#NaN} then the result is {@link Double#NaN}. If it
	* contains {@link Double#POSITIVE_INFINITY} and not {@link Double#NaN} then the result is {@link
	* Double#POSITIVE_INFINITY}. If it contains {@link Double#NEGATIVE_INFINITY} and finite values
	* only then the result is the highest finite value. If it contains {@link
	* Double#NEGATIVE_INFINITY} only then the result is {@link Double#NEGATIVE_INFINITY}.
	*
	* @throws IllegalStateException if the dataset is empty
	*/
	public double max() {
	checkState(count != 0);
	return max;
	}

	double sumOfSquaresOfDeltas() {
	return sumOfSquaresOfDeltas;
	}

	/**
	* Calculates the new value for the accumulated mean when a value is added, in the case where at
	* least one of the previous mean and the value is non-finite.
	*/
	static double calculateNewMeanNonFinite(double previousMean, double value) {
	/*
	* Desired behaviour is to match the results of applying the naive mean formula. In particular,
	* the update formula can subtract infinities in cases where the naive formula would add them.
	*
	* Consequently:
	* 1. If the previous mean is finite and the new value is non-finite then the new mean is that
	* value (whether it is NaN or infinity).
	* 2. If the new value is finite and the previous mean is non-finite then the mean is unchanged
	* (whether it is NaN or infinity).
	* 3. If both the previous mean and the new value are non-finite and...
	* 3a. ...either or both is NaN (so mean != value) then the new mean is NaN.
	* 3b. ...they are both the same infinities (so mean == value) then the mean is unchanged.
	* 3c. ...they are different infinities (so mean != value) then the new mean is NaN.
	*/
	if (isFinite(previousMean)) {
	// This is case 1.
	return value;
	} else if (isFinite(value) \|\| previousMean == value) {
	// This is case 2. or 3b.
	return previousMean;
	} else {
	// This is case 3a. or 3c.
	return NaN;
	}
	}
	}