/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You 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 org.apache.commons.math3.stat.descriptive;
  
  import java.io.Serializable;
  
  import org.apache.commons.math3.exception.MathIllegalStateException;
  import org.apache.commons.math3.exception.NullArgumentException;
  import org.apache.commons.math3.exception.util.LocalizedFormats;
  import org.apache.commons.math3.stat.descriptive.moment.GeometricMean;
  import org.apache.commons.math3.stat.descriptive.moment.Mean;
  import org.apache.commons.math3.stat.descriptive.moment.SecondMoment;
  import org.apache.commons.math3.stat.descriptive.moment.Variance;
  import org.apache.commons.math3.stat.descriptive.rank.Max;
  import org.apache.commons.math3.stat.descriptive.rank.Min;
  import org.apache.commons.math3.stat.descriptive.summary.Sum;
  import org.apache.commons.math3.stat.descriptive.summary.SumOfLogs;
  import org.apache.commons.math3.stat.descriptive.summary.SumOfSquares;
  import org.apache.commons.math3.util.MathUtils;
  import org.apache.commons.math3.util.Precision;
  import org.apache.commons.math3.util.FastMath;
  
  /**
   * <p>
   * Computes summary statistics for a stream of data values added using the
   * {@link #addValue(double) addValue} method. The data values are not stored in
   * memory, so this class can be used to compute statistics for very large data
   * streams.
   * </p>
   * <p>
   * The {@link StorelessUnivariateStatistic} instances used to maintain summary
   * state and compute statistics are configurable via setters. For example, the
   * default implementation for the variance can be overridden by calling
   * {@link #setVarianceImpl(StorelessUnivariateStatistic)}. Actual parameters to
   * these methods must implement the {@link StorelessUnivariateStatistic}
   * interface and configuration must be completed before <code>addValue</code>
   * is called. No configuration is necessary to use the default, commons-math
   * provided implementations.
   * </p>
   * <p>
   * Note: This class is not thread-safe. Use
   * {@link SynchronizedSummaryStatistics} if concurrent access from multiple
   * threads is required.
   * </p>
   * @version $Id: SummaryStatistics.java 1416643 2012-12-03 19:37:14Z tn $
   */
  public class SummaryStatistics implements StatisticalSummary, Serializable {
  
      /** Serialization UID */
      private static final long serialVersionUID = -2021321786743555871L;
  
      /** count of values that have been added */
      private long n = 0;
  
      /** SecondMoment is used to compute the mean and variance */
      private SecondMoment secondMoment = new SecondMoment();
  
      /** sum of values that have been added */
      private Sum sum = new Sum();
  
      /** sum of the square of each value that has been added */
      private SumOfSquares sumsq = new SumOfSquares();
  
      /** min of values that have been added */
      private Min min = new Min();
  
      /** max of values that have been added */
      private Max max = new Max();
  
      /** sumLog of values that have been added */
      private SumOfLogs sumLog = new SumOfLogs();
  
      /** geoMean of values that have been added */
      private GeometricMean geoMean = new GeometricMean(sumLog);
  
      /** mean of values that have been added */
      private Mean mean = new Mean(secondMoment);
  
      /** variance of values that have been added */
      private Variance variance = new Variance(secondMoment);
  
      /** Sum statistic implementation - can be reset by setter. */
      private StorelessUnivariateStatistic sumImpl = sum;
  
      /** Sum of squares statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic sumsqImpl = sumsq;
 
     /** Minimum statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic minImpl = min;
 
     /** Maximum statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic maxImpl = max;
 
     /** Sum of log statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic sumLogImpl = sumLog;
 
     /** Geometric mean statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic geoMeanImpl = geoMean;
 
     /** Mean statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic meanImpl = mean;
 
     /** Variance statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic varianceImpl = variance;
 
     /**
      * Construct a SummaryStatistics instance
      */
     public SummaryStatistics() {
     }
 
     /**
      * A copy constructor. Creates a deep-copy of the {@code original}.
      *
      * @param original the {@code SummaryStatistics} instance to copy
      * @throws NullArgumentException if original is null
      */
     public SummaryStatistics(SummaryStatistics original) throws NullArgumentException {
         copy(original, this);
     }
 
     /**
      * Return a {@link StatisticalSummaryValues} instance reporting current
      * statistics.
      * @return Current values of statistics
      */
     public StatisticalSummary getSummary() {
         return new StatisticalSummaryValues(getMean(), getVariance(), getN(),
                 getMax(), getMin(), getSum());
     }
 
     /**
      * Add a value to the data
      * @param value the value to add
      */
     public void addValue(double value) {
         sumImpl.increment(value);
         sumsqImpl.increment(value);
         minImpl.increment(value);
         maxImpl.increment(value);
         sumLogImpl.increment(value);
         secondMoment.increment(value);
         // If mean, variance or geomean have been overridden,
         // need to increment these
         if (meanImpl != mean) {
             meanImpl.increment(value);
         }
         if (varianceImpl != variance) {
             varianceImpl.increment(value);
         }
         if (geoMeanImpl != geoMean) {
             geoMeanImpl.increment(value);
         }
         n++;
     }
 
     /**
      * Returns the number of available values
      * @return The number of available values
      */
     public long getN() {
         return n;
     }
 
     /**
      * Returns the sum of the values that have been added
      * @return The sum or <code>Double.NaN</code> if no values have been added
      */
     public double getSum() {
         return sumImpl.getResult();
     }
 
     /**
      * Returns the sum of the squares of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return The sum of squares
      */
     public double getSumsq() {
         return sumsqImpl.getResult();
     }
 
     /**
      * Returns the mean of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the mean
      */
     public double getMean() {
         return meanImpl.getResult();
     }
 
     /**
      * Returns the standard deviation of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the standard deviation
      */
     public double getStandardDeviation() {
         double stdDev = Double.NaN;
         if (getN() > 0) {
             if (getN() > 1) {
                 stdDev = FastMath.sqrt(getVariance());
             } else {
                 stdDev = 0.0;
             }
         }
         return stdDev;
     }
 
     /**
      * Returns the (sample) variance of the available values.
      *
      * <p>This method returns the bias-corrected sample variance (using {@code n - 1} in
      * the denominator).  Use {@link #getPopulationVariance()} for the non-bias-corrected
      * population variance.</p>
      *
      * <p>Double.NaN is returned if no values have been added.</p>
      *
      * @return the variance
      */
     public double getVariance() {
         return varianceImpl.getResult();
     }
 
     /**
      * Returns the <a href="http://en.wikibooks.org/wiki/Statistics/Summary/Variance">
      * population variance</a> of the values that have been added.
      *
      * <p>Double.NaN is returned if no values have been added.</p>
      *
      * @return the population variance
      */
     public double getPopulationVariance() {
         Variance populationVariance = new Variance(secondMoment);
         populationVariance.setBiasCorrected(false);
         return populationVariance.getResult();
     }
 
     /**
      * Returns the maximum of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the maximum
      */
     public double getMax() {
         return maxImpl.getResult();
     }
 
     /**
      * Returns the minimum of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the minimum
      */
     public double getMin() {
         return minImpl.getResult();
     }
 
     /**
      * Returns the geometric mean of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the geometric mean
      */
     public double getGeometricMean() {
         return geoMeanImpl.getResult();
     }
 
     /**
      * Returns the sum of the logs of the values that have been added.
      * <p>
      * Double.NaN is returned if no values have been added.
      * </p>
      * @return the sum of logs
      * @since 1.2
      */
     public double getSumOfLogs() {
         return sumLogImpl.getResult();
     }
 
     /**
      * Returns a statistic related to the Second Central Moment.  Specifically,
      * what is returned is the sum of squared deviations from the sample mean
      * among the values that have been added.
      * <p>
      * Returns <code>Double.NaN</code> if no data values have been added and
      * returns <code>0</code> if there is just one value in the data set.</p>
      * <p>
      * @return second central moment statistic
      * @since 2.0
      */
     public double getSecondMoment() {
         return secondMoment.getResult();
     }
 
     /**
      * Generates a text report displaying summary statistics from values that
      * have been added.
      * @return String with line feeds displaying statistics
      * @since 1.2
      */
     @Override
     public String toString() {
         StringBuilder outBuffer = new StringBuilder();
         String endl = "\n";
         outBuffer.append("SummaryStatistics:").append(endl);
         outBuffer.append("n: ").append(getN()).append(endl);
         outBuffer.append("min: ").append(getMin()).append(endl);
         outBuffer.append("max: ").append(getMax()).append(endl);
         outBuffer.append("mean: ").append(getMean()).append(endl);
         outBuffer.append("geometric mean: ").append(getGeometricMean())
             .append(endl);
         outBuffer.append("variance: ").append(getVariance()).append(endl);
         outBuffer.append("sum of squares: ").append(getSumsq()).append(endl);
         outBuffer.append("standard deviation: ").append(getStandardDeviation())
             .append(endl);
         outBuffer.append("sum of logs: ").append(getSumOfLogs()).append(endl);
         return outBuffer.toString();
     }
 
     /**
      * Resets all statistics and storage
      */
     public void clear() {
         this.n = 0;
         minImpl.clear();
         maxImpl.clear();
         sumImpl.clear();
         sumLogImpl.clear();
         sumsqImpl.clear();
         geoMeanImpl.clear();
         secondMoment.clear();
         if (meanImpl != mean) {
             meanImpl.clear();
         }
         if (varianceImpl != variance) {
             varianceImpl.clear();
         }
     }
 
     /**
      * Returns true iff <code>object</code> is a
      * <code>SummaryStatistics</code> instance and all statistics have the
      * same values as this.
      * @param object the object to test equality against.
      * @return true if object equals this
      */
     @Override
     public boolean equals(Object object) {
         if (object == this) {
             return true;
         }
         if (object instanceof SummaryStatistics == false) {
             return false;
         }
         SummaryStatistics stat = (SummaryStatistics)object;
         return Precision.equalsIncludingNaN(stat.getGeometricMean(), getGeometricMean()) &&
                Precision.equalsIncludingNaN(stat.getMax(),           getMax())           &&
                Precision.equalsIncludingNaN(stat.getMean(),          getMean())          &&
                Precision.equalsIncludingNaN(stat.getMin(),           getMin())           &&
                Precision.equalsIncludingNaN(stat.getN(),             getN())             &&
                Precision.equalsIncludingNaN(stat.getSum(),           getSum())           &&
                Precision.equalsIncludingNaN(stat.getSumsq(),         getSumsq())         &&
                Precision.equalsIncludingNaN(stat.getVariance(),      getVariance());
     }
 
     /**
      * Returns hash code based on values of statistics
      * @return hash code
      */
     @Override
     public int hashCode() {
         int result = 31 + MathUtils.hash(getGeometricMean());
         result = result * 31 + MathUtils.hash(getGeometricMean());
         result = result * 31 + MathUtils.hash(getMax());
         result = result * 31 + MathUtils.hash(getMean());
         result = result * 31 + MathUtils.hash(getMin());
         result = result * 31 + MathUtils.hash(getN());
         result = result * 31 + MathUtils.hash(getSum());
         result = result * 31 + MathUtils.hash(getSumsq());
         result = result * 31 + MathUtils.hash(getVariance());
         return result;
     }
 
     // Getters and setters for statistics implementations
     /**
      * Returns the currently configured Sum implementation
      * @return the StorelessUnivariateStatistic implementing the sum
      * @since 1.2
      */
     public StorelessUnivariateStatistic getSumImpl() {
         return sumImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the Sum.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param sumImpl the StorelessUnivariateStatistic instance to use for
      *        computing the Sum
      * @throws MathIllegalStateException if data has already been added (i.e if n >0)
      * @since 1.2
      */
     public void setSumImpl(StorelessUnivariateStatistic sumImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.sumImpl = sumImpl;
     }
 
     /**
      * Returns the currently configured sum of squares implementation
      * @return the StorelessUnivariateStatistic implementing the sum of squares
      * @since 1.2
      */
     public StorelessUnivariateStatistic getSumsqImpl() {
         return sumsqImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the sum of squares.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param sumsqImpl the StorelessUnivariateStatistic instance to use for
      *        computing the sum of squares
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setSumsqImpl(StorelessUnivariateStatistic sumsqImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.sumsqImpl = sumsqImpl;
     }
 
     /**
      * Returns the currently configured minimum implementation
      * @return the StorelessUnivariateStatistic implementing the minimum
      * @since 1.2
      */
     public StorelessUnivariateStatistic getMinImpl() {
         return minImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the minimum.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param minImpl the StorelessUnivariateStatistic instance to use for
      *        computing the minimum
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setMinImpl(StorelessUnivariateStatistic minImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.minImpl = minImpl;
     }
 
     /**
      * Returns the currently configured maximum implementation
      * @return the StorelessUnivariateStatistic implementing the maximum
      * @since 1.2
      */
     public StorelessUnivariateStatistic getMaxImpl() {
         return maxImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the maximum.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param maxImpl the StorelessUnivariateStatistic instance to use for
      *        computing the maximum
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setMaxImpl(StorelessUnivariateStatistic maxImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.maxImpl = maxImpl;
     }
 
     /**
      * Returns the currently configured sum of logs implementation
      * @return the StorelessUnivariateStatistic implementing the log sum
      * @since 1.2
      */
     public StorelessUnivariateStatistic getSumLogImpl() {
         return sumLogImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the sum of logs.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param sumLogImpl the StorelessUnivariateStatistic instance to use for
      *        computing the log sum
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setSumLogImpl(StorelessUnivariateStatistic sumLogImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.sumLogImpl = sumLogImpl;
         geoMean.setSumLogImpl(sumLogImpl);
     }
 
     /**
      * Returns the currently configured geometric mean implementation
      * @return the StorelessUnivariateStatistic implementing the geometric mean
      * @since 1.2
      */
     public StorelessUnivariateStatistic getGeoMeanImpl() {
         return geoMeanImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the geometric mean.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param geoMeanImpl the StorelessUnivariateStatistic instance to use for
      *        computing the geometric mean
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setGeoMeanImpl(StorelessUnivariateStatistic geoMeanImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.geoMeanImpl = geoMeanImpl;
     }
 
     /**
      * Returns the currently configured mean implementation
      * @return the StorelessUnivariateStatistic implementing the mean
      * @since 1.2
      */
     public StorelessUnivariateStatistic getMeanImpl() {
         return meanImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the mean.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param meanImpl the StorelessUnivariateStatistic instance to use for
      *        computing the mean
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setMeanImpl(StorelessUnivariateStatistic meanImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.meanImpl = meanImpl;
     }
 
     /**
      * Returns the currently configured variance implementation
      * @return the StorelessUnivariateStatistic implementing the variance
      * @since 1.2
      */
     public StorelessUnivariateStatistic getVarianceImpl() {
         return varianceImpl;
     }
 
     /**
      * <p>
      * Sets the implementation for the variance.
      * </p>
      * <p>
      * This method must be activated before any data has been added - i.e.,
      * before {@link #addValue(double) addValue} has been used to add data;
      * otherwise an IllegalStateException will be thrown.
      * </p>
      * @param varianceImpl the StorelessUnivariateStatistic instance to use for
      *        computing the variance
      * @throws MathIllegalStateException if data has already been added (i.e if n > 0)
      * @since 1.2
      */
     public void setVarianceImpl(StorelessUnivariateStatistic varianceImpl)
     throws MathIllegalStateException {
         checkEmpty();
         this.varianceImpl = varianceImpl;
     }
 
     /**
      * Throws IllegalStateException if n > 0.
      * @throws MathIllegalStateException if data has been added
      */
     private void checkEmpty() throws MathIllegalStateException {
         if (n > 0) {
             throw new MathIllegalStateException(
                 LocalizedFormats.VALUES_ADDED_BEFORE_CONFIGURING_STATISTIC, n);
         }
     }
 
     /**
      * Returns a copy of this SummaryStatistics instance with the same internal state.
      *
      * @return a copy of this
      */
     public SummaryStatistics copy() {
         SummaryStatistics result = new SummaryStatistics();
         // No try-catch or advertised exception because arguments are guaranteed non-null
         copy(this, result);
         return result;
     }
 
     /**
      * Copies source to dest.
      * <p>Neither source nor dest can be null.</p>
      *
      * @param source SummaryStatistics to copy
      * @param dest SummaryStatistics to copy to
      * @throws NullArgumentException if either source or dest is null
      */
     public static void copy(SummaryStatistics source, SummaryStatistics dest)
         throws NullArgumentException {
         MathUtils.checkNotNull(source);
         MathUtils.checkNotNull(dest);
         dest.maxImpl = source.maxImpl.copy();
         dest.minImpl = source.minImpl.copy();
         dest.sumImpl = source.sumImpl.copy();
         dest.sumLogImpl = source.sumLogImpl.copy();
         dest.sumsqImpl = source.sumsqImpl.copy();
         dest.secondMoment = source.secondMoment.copy();
         dest.n = source.n;
 
         // Keep commons-math supplied statistics with embedded moments in synch
         if (source.getVarianceImpl() instanceof Variance) {
             dest.varianceImpl = new Variance(dest.secondMoment);
         } else {
             dest.varianceImpl = source.varianceImpl.copy();
         }
         if (source.meanImpl instanceof Mean) {
             dest.meanImpl = new Mean(dest.secondMoment);
         } else {
             dest.meanImpl = source.meanImpl.copy();
         }
         if (source.getGeoMeanImpl() instanceof GeometricMean) {
             dest.geoMeanImpl = new GeometricMean((SumOfLogs) dest.sumLogImpl);
         } else {
             dest.geoMeanImpl = source.geoMeanImpl.copy();
         }
 
         // Make sure that if stat == statImpl in source, same
         // holds in dest; otherwise copy stat
         if (source.geoMean == source.geoMeanImpl) {
             dest.geoMean = (GeometricMean) dest.geoMeanImpl;
         } else {
             GeometricMean.copy(source.geoMean, dest.geoMean);
         }
         if (source.max == source.maxImpl) {
             dest.max = (Max) dest.maxImpl;
         } else {
             Max.copy(source.max, dest.max);
         }
         if (source.mean == source.meanImpl) {
             dest.mean = (Mean) dest.meanImpl;
         } else {
             Mean.copy(source.mean, dest.mean);
         }
         if (source.min == source.minImpl) {
             dest.min = (Min) dest.minImpl;
         } else {
             Min.copy(source.min, dest.min);
         }
         if (source.sum == source.sumImpl) {
             dest.sum = (Sum) dest.sumImpl;
         } else {
             Sum.copy(source.sum, dest.sum);
         }
         if (source.variance == source.varianceImpl) {
             dest.variance = (Variance) dest.varianceImpl;
         } else {
             Variance.copy(source.variance, dest.variance);
         }
         if (source.sumLog == source.sumLogImpl) {
             dest.sumLog = (SumOfLogs) dest.sumLogImpl;
         } else {
             SumOfLogs.copy(source.sumLog, dest.sumLog);
         }
         if (source.sumsq == source.sumsqImpl) {
             dest.sumsq = (SumOfSquares) dest.sumsqImpl;
         } else {
             SumOfSquares.copy(source.sumsq, dest.sumsq);
         }
     }
 }