View Javadoc

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