View Javadoc

1   /*
2    * Copyright 2003-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.stat.descriptive.summary;
17  
18  import java.io.Serializable;
19  
20  import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
21  
22  /**
23   * Returns the sum of the natural logs for this collection of values.  
24   * <p>
25   * Uses {@link java.lang.Math#log(double)} to compute the logs.  Therefore,
26   * <ul>
27   * <li>If any of values are < 0, the result is <code>NaN.</code></li>
28   * <li>If all values are non-negative and less than 
29   * <code>Double.POSITIVE_INFINITY</code>,  but at least one value is 0, the
30   * result is <code>Double.NEGATIVE_INFINITY.</code></li>
31   * <li>If both <code>Double.POSITIVE_INFINITY</code> and 
32   * <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
33   * <code>NaN.</code></li>
34   * </ul>
35   * <p>
36   * <strong>Note that this implementation is not synchronized.</strong> If 
37   * multiple threads access an instance of this class concurrently, and at least
38   * one of the threads invokes the <code>increment()</code> or 
39   * <code>clear()</code> method, it must be synchronized externally.
40   * 
41   * @version $Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $
42   */
43  public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements Serializable {
44  
45      /** Serializable version identifier */
46      private static final long serialVersionUID = -370076995648386763L;    
47  
48      /**Number of values that have been added */
49      private int n;
50      
51      /**
52       * The currently running value
53       */
54      private double value;
55      
56      /**
57       * Create a SumOfLogs instance
58       */
59      public SumOfLogs() {
60         value = 0d;
61         n = 0;
62      }
63  
64      /**
65       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
66       */
67      public void increment(final double d) {
68          value += Math.log(d);
69          n++;
70      }
71  
72      /**
73       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
74       */
75      public double getResult() {
76          if (n > 0) {
77              return value;
78          } else {
79              return Double.NaN;
80          }
81      }
82  
83      /**
84       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN()
85       */
86      public long getN() {
87          return n;
88      }
89      
90      /**
91       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear()
92       */
93      public void clear() {
94          value = 0d;
95          n = 0;
96      }
97  
98      /**
99       * Returns the sum of the natural logs of the entries in the specified portion of
100      * the input array, or <code>Double.NaN</code> if the designated subarray
101      * is empty.
102      * <p>
103      * Throws <code>IllegalArgumentException</code> if the array is null.
104      * <p>
105      * See {@link SumOfLogs}.
106      * 
107      * @param values the input array
108      * @param begin index of the first array element to include
109      * @param length the number of elements to include
110      * @return the sum of the natural logs of the values or Double.NaN if 
111      * length = 0
112      * @throws IllegalArgumentException if the array is null or the array index
113      *  parameters are not valid
114      */
115     public double evaluate(final double[] values, final int begin, final int length) {
116         double sumLog = Double.NaN;
117         if (test(values, begin, length)) {
118             sumLog = 0.0;
119             for (int i = begin; i < begin + length; i++) {
120                 sumLog += Math.log(values[i]);
121             }
122         }
123         return sumLog;
124     }
125 }