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 &lt; 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    }