Author: psteitz
Date: Mon Apr 27 10:51:52 2009
New Revision: 768921
URL: http://svn.apache.org/viewvc?rev=768921&view=rev
Log:
Added AggregateSummaryStatistics class to support aggregation of
SummaryStatistics.
JIRA: MATH-224
Reported by Andre Panisson
Patched by John Bollinger
Added:
commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java
(with props)
commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java
(with props)
Modified:
commons/proper/math/trunk/pom.xml
commons/proper/math/trunk/src/site/xdoc/changes.xml
Modified: commons/proper/math/trunk/pom.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/pom.xml?rev=768921&r1=768920&r2=768921&view=diff
==============================================================================
--- commons/proper/math/trunk/pom.xml (original)
+++ commons/proper/math/trunk/pom.xml Mon Apr 27 10:51:52 2009
@@ -106,6 +106,9 @@
<name>Rémi Arntzen</name>
</contributor>
<contributor>
+ <name>John Bollinger</name>
+ </contributor>
+ <contributor>
<name>Cyril Briquet</name>
</contributor>
<contributor>
Added:
commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java?rev=768921&view=auto
==============================================================================
---
commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java
(added)
+++
commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java
Mon Apr 27 10:51:52 2009
@@ -0,0 +1,245 @@
+/*
+ * 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.math.stat.descriptive;
+
+import java.io.Serializable;
+
+/**
+ * <p>
+ * A StatisticalSummary that aggregates statistics from several data sets or
+ * data set partitions. In its simplest usage mode, the client creates an
+ * instance via the zero-argument constructor, then uses
+ * {...@link #createContributingStatistics()} to obtain a {...@code
SummaryStatistics}
+ * for each individual data set / partition. The per-set statistics objects
+ * are used as normal, and at any time the aggregate statistics for all the
+ * contributors can be obtained from this object.
+ * </p><p>
+ * Clients with specialized requirements can use alternative constructors to
+ * control the statistics implementations and initial values used by the
+ * contributing and the internal aggregate {...@code SummaryStatistics}
objects.
+ * </p>
+ *
+ * @since 2.0
+ * @version $Revision:$ $Date:$
+ *
+ */
+public class AggregateSummaryStatistics implements StatisticalSummary,
+ Serializable {
+
+ /**
+ * The serialization version of this class
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * A SummaryStatistics serving as a prototype for creating
SummaryStatistics
+ * contributing to this aggregate
+ */
+ private SummaryStatistics statisticsPrototype;
+
+ /**
+ * The SummaryStatistics in which aggregate statistics are accumulated
+ */
+ private SummaryStatistics statistics;
+
+ /**
+ * Initializes a new AggregateSummaryStatistics with default statistics
+ * implementations.
+ *
+ * @see SummaryStatistics#SummaryStatistics()
+ */
+ public AggregateSummaryStatistics() {
+ this(new SummaryStatistics());
+ }
+
+ /**
+ * Initializes a new AggregateSummaryStatistics with the specified
statistics
+ * object as a prototype for contributing statistics and for the internal
+ * aggregate statistics. This provides for customized statistics
implementations
+ * to be used by contributing and aggregate statistics.
+ *
+ * @param prototypeStatistics a {...@code SummaryStatistics} serving as a
+ * prototype both for the internal aggregate statistics and for
+ * contributing statistics obtained via the
+ * {...@code createContributingStatistics()} method. Being a
prototype
+ * means that other objects are initialized by copying this object's
state.
+ * If {...@code null}, a new, default statistics object is used. Any
statistic
+ * values in the prototype are propagated to contributing statistics
+ * objects and (once) into these aggregate statistics.
+ * @see #createContributingStatistics()
+ */
+ public AggregateSummaryStatistics(SummaryStatistics prototypeStatistics) {
+ this(prototypeStatistics, (prototypeStatistics == null ? null :
+ new SummaryStatistics(prototypeStatistics)));
+ }
+
+ /**
+ * Initializes a new AggregateSummaryStatistics with the specified
statistics
+ * object as a prototype for contributing statistics and for the internal
+ * aggregate statistics. This provides for different statistics
implementations
+ * to be used by contributing and aggregate statistics and for an initial
+ * state to be supplied for the aggregate statistics.
+ *
+ * @param prototypeStatistics a {...@code SummaryStatistics} serving as a
+ * prototype both for the internal aggregate statistics and for
+ * contributing statistics obtained via the
+ * {...@code createContributingStatistics()} method. Being a
prototype
+ * means that other objects are initialized by copying this object's
state.
+ * If {...@code null}, a new, default statistics object is used. Any
statistic
+ * values in the prototype are propagated to contributing statistics
+ * objects, but not into these aggregate statistics.
+ * @param initialStatistics a {...@code SummaryStatistics} to serve as the
+ * internal aggregate statistics object. If {...@code null}, a new,
default
+ * statistics object is used.
+ * @see #createContributingStatistics()
+ */
+ public AggregateSummaryStatistics(SummaryStatistics prototypeStatistics,
+ SummaryStatistics initialStatistics) {
+ this.statisticsPrototype = ((prototypeStatistics == null) ?
+ new SummaryStatistics() : prototypeStatistics);
+ this.statistics = ((initialStatistics == null) ?
+ new SummaryStatistics() : initialStatistics);
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns the maximum over all the
aggregated
+ * data.
+ *
+ * @see StatisticalSummary#getMax()
+ */
+ public double getMax() {
+ return statistics.getMax();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns the mean of all the aggregated
data.
+ *
+ * @see StatisticalSummary#getMean()
+ */
+ public double getMean() {
+ return statistics.getMean();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns the minimum over all the
aggregated
+ * data.
+ *
+ * @see StatisticalSummary#getMin()
+ */
+ public double getMin() {
+ return statistics.getMin();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns a count of all the aggregated
data.
+ *
+ * @see StatisticalSummary#getN()
+ */
+ public long getN() {
+ return statistics.getN();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns the standard deviation of all
the
+ * aggregated data.
+ *
+ * @see StatisticalSummary#getStandardDeviation()
+ */
+ public double getStandardDeviation() {
+ return statistics.getStandardDeviation();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns a sum of all the aggregated
data.
+ *
+ * @see StatisticalSummary#getSum()
+ */
+ public double getSum() {
+ return statistics.getSum();
+ }
+
+ /**
+ * {...@inheritdoc}. This version returns the variance of all the
aggregated
+ * data.
+ *
+ * @see StatisticalSummary#getVariance()
+ */
+ public double getVariance() {
+ return statistics.getVariance();
+ }
+
+ /**
+ * Creates and returns a {...@code SummaryStatistics} whose data will be
+ * aggregated with those of this {...@code AggregateSummaryStatistics}.
+ *
+ * @return a {...@code SummaryStatistics} whose data will be aggregated
with
+ * those of this {...@code AggregateSummaryStatistics}. The initial
state
+ * is a copy of the configured prototype statistics.
+ */
+ public SummaryStatistics createContributingStatistics() {
+ SummaryStatistics contributingStatistics
+ = new AggregatingSummaryStatistics(statistics);
+
+ SummaryStatistics.copy(statisticsPrototype, contributingStatistics);
+
+ return contributingStatistics;
+ }
+
+ /**
+ * A SummaryStatistics that also forwards all values added to it to a
second
+ * {...@code SummaryStatistics} for aggregation.
+ *
+ * @since 2.0
+ */
+ private static class AggregatingSummaryStatistics extends
SummaryStatistics {
+
+ /**
+ * The serialization version of this class
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * An additional SummaryStatistics into which values added to these
+ * statistics (and possibly others) are aggregated
+ */
+ private SummaryStatistics aggregateStatistics;
+
+ /**
+ * Initializes a new AggregatingSummaryStatistics with the specified
+ * aggregate statistics object
+ *
+ * @param aggregateStatistics a {...@code SummaryStatistics} into which
+ * values added to this statistics object should be aggregated
+ */
+ public AggregatingSummaryStatistics(SummaryStatistics
aggregateStatistics) {
+ this.aggregateStatistics = aggregateStatistics;
+ }
+
+ /**
+ * {...@inheritdoc}. This version adds the provided value to the
configured
+ * aggregate after adding it to these statistics.
+ *
+ * @see SummaryStatistics#addValue(double)
+ */
+ @Override
+ public void addValue(double value) {
+ super.addValue(value);
+ aggregateStatistics.addValue(value);
+ }
+ }
+}
Propchange:
commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.java
------------------------------------------------------------------------------
svn:eol-style = native
Modified: commons/proper/math/trunk/src/site/xdoc/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/changes.xml?rev=768921&r1=768920&r2=768921&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/changes.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/changes.xml Mon Apr 27 10:51:52 2009
@@ -43,6 +43,9 @@
Added support for any type of field in linear algebra (FielxMatrix,
FieldVector,
FieldLUDecomposition)
</action>
+ <action dev="psteitz" type="add" due-to="John Bollinger">
+ Added AggregateSummaryStatistics class to support aggregation of
SummaryStatistics.
+ </action>
<action dev="luc" type="add" >
Added general Field and FieldElement interfaces to allow generic
algorithms
to operate on fields. The library already provides several
implementations:
Added:
commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java?rev=768921&view=auto
==============================================================================
---
commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java
(added)
+++
commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java
Mon Apr 27 10:51:52 2009
@@ -0,0 +1,73 @@
+/*
+ * 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.math.stat.descriptive;
+
+import junit.framework.Test;
+import junit.framework.TestCase;
+import junit.framework.TestSuite;
+
+
+/**
+ * Test cases for {...@link AggregateSummaryStatistics}
+ *
+ */
+public class AggregateSummaryStatisticsTest extends TestCase {
+
+ /**
+ * Tests the standard aggregation behavior
+ */
+ public void testAggregation() {
+ AggregateSummaryStatistics aggregate = new
AggregateSummaryStatistics();
+ SummaryStatistics setOneStats =
aggregate.createContributingStatistics();
+ SummaryStatistics setTwoStats =
aggregate.createContributingStatistics();
+
+ assertNotNull("The set one contributing stats are null", setOneStats);
+ assertNotNull("The set two contributing stats are null", setTwoStats);
+ assertNotSame("Contributing stats objects are the same", setOneStats,
setTwoStats);
+
+ setOneStats.addValue(2);
+ setOneStats.addValue(3);
+ setOneStats.addValue(5);
+ setOneStats.addValue(7);
+ setOneStats.addValue(11);
+ assertEquals("Wrong number of set one values", 5, setOneStats.getN());
+ assertEquals("Wrong sum of set one values", 28.0,
setOneStats.getSum());
+
+ setTwoStats.addValue(2);
+ setTwoStats.addValue(4);
+ setTwoStats.addValue(8);
+ assertEquals("Wrong number of set two values", 3, setTwoStats.getN());
+ assertEquals("Wrong sum of set two values", 14.0,
setTwoStats.getSum());
+
+ assertEquals("Wrong number of aggregate values", 8, aggregate.getN());
+ assertEquals("Wrong aggregate sum", 42.0, aggregate.getSum());
+ }
+
+ /**
+ * Creates and returns a {...@code Test} representing all the test cases
in this
+ * class
+ *
+ * @return a {...@code Test} representing all the test cases in this class
+ */
+ public static Test suite() {
+ TestSuite suite = new TestSuite(AggregateSummaryStatisticsTest.class);
+ suite.setName("AggregateSummaryStatistics tests");
+ return suite;
+ }
+
+}
Propchange:
commons/proper/math/trunk/src/test/org/apache/commons/math/stat/descriptive/AggregateSummaryStatisticsTest.java
------------------------------------------------------------------------------
svn:eol-style = native
