001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math3.stat.descriptive.summary;
018
019 import java.io.Serializable;
020
021 import org.apache.commons.math3.exception.MathIllegalArgumentException;
022 import org.apache.commons.math3.exception.NullArgumentException;
023 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
024 import org.apache.commons.math3.util.FastMath;
025 import org.apache.commons.math3.util.MathUtils;
026
027 /**
028 * Returns the sum of the natural logs for this collection of values.
029 * <p>
030 * Uses {@link org.apache.commons.math3.util.FastMath#log(double)} to compute the logs.
031 * Therefore,
032 * <ul>
033 * <li>If any of values are < 0, the result is <code>NaN.</code></li>
034 * <li>If all values are non-negative and less than
035 * <code>Double.POSITIVE_INFINITY</code>, but at least one value is 0, the
036 * result is <code>Double.NEGATIVE_INFINITY.</code></li>
037 * <li>If both <code>Double.POSITIVE_INFINITY</code> and
038 * <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
039 * <code>NaN.</code></li>
040 * </ul></p>
041 * <p>
042 * <strong>Note that this implementation is not synchronized.</strong> If
043 * multiple threads access an instance of this class concurrently, and at least
044 * one of the threads invokes the <code>increment()</code> or
045 * <code>clear()</code> method, it must be synchronized externally.</p>
046 *
047 * @version $Id: SumOfLogs.java 1416643 2012-12-03 19:37:14Z tn $
048 */
049 public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements Serializable {
050
051 /** Serializable version identifier */
052 private static final long serialVersionUID = -370076995648386763L;
053
054 /**Number of values that have been added */
055 private int n;
056
057 /**
058 * The currently running value
059 */
060 private double value;
061
062 /**
063 * Create a SumOfLogs instance
064 */
065 public SumOfLogs() {
066 value = 0d;
067 n = 0;
068 }
069
070 /**
071 * Copy constructor, creates a new {@code SumOfLogs} identical
072 * to the {@code original}
073 *
074 * @param original the {@code SumOfLogs} instance to copy
075 * @throws NullArgumentException if original is null
076 */
077 public SumOfLogs(SumOfLogs original) throws NullArgumentException {
078 copy(original, this);
079 }
080
081 /**
082 * {@inheritDoc}
083 */
084 @Override
085 public void increment(final double d) {
086 value += FastMath.log(d);
087 n++;
088 }
089
090 /**
091 * {@inheritDoc}
092 */
093 @Override
094 public double getResult() {
095 return value;
096 }
097
098 /**
099 * {@inheritDoc}
100 */
101 public long getN() {
102 return n;
103 }
104
105 /**
106 * {@inheritDoc}
107 */
108 @Override
109 public void clear() {
110 value = 0d;
111 n = 0;
112 }
113
114 /**
115 * Returns the sum of the natural logs of the entries in the specified portion of
116 * the input array, or <code>Double.NaN</code> if the designated subarray
117 * is empty.
118 * <p>
119 * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
120 * <p>
121 * See {@link SumOfLogs}.</p>
122 *
123 * @param values the input array
124 * @param begin index of the first array element to include
125 * @param length the number of elements to include
126 * @return the sum of the natural logs of the values or 0 if
127 * length = 0
128 * @throws MathIllegalArgumentException if the array is null or the array index
129 * parameters are not valid
130 */
131 @Override
132 public double evaluate(final double[] values, final int begin, final int length)
133 throws MathIllegalArgumentException {
134 double sumLog = Double.NaN;
135 if (test(values, begin, length, true)) {
136 sumLog = 0.0;
137 for (int i = begin; i < begin + length; i++) {
138 sumLog += FastMath.log(values[i]);
139 }
140 }
141 return sumLog;
142 }
143
144 /**
145 * {@inheritDoc}
146 */
147 @Override
148 public SumOfLogs copy() {
149 SumOfLogs result = new SumOfLogs();
150 // No try-catch or advertised exception here because args are valid
151 copy(this, result);
152 return result;
153 }
154
155 /**
156 * Copies source to dest.
157 * <p>Neither source nor dest can be null.</p>
158 *
159 * @param source SumOfLogs to copy
160 * @param dest SumOfLogs to copy to
161 * @throws NullArgumentException if either source or dest is null
162 */
163 public static void copy(SumOfLogs source, SumOfLogs dest)
164 throws NullArgumentException {
165 MathUtils.checkNotNull(source);
166 MathUtils.checkNotNull(dest);
167 dest.setData(source.getDataRef());
168 dest.n = source.n;
169 dest.value = source.value;
170 }
171 }