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 /** 25 * Returns the sum of the available values. 26 * <p> 27 * If there are no values in the dataset, or any of the values are 28 * <code>NaN</code>, then <code>NaN</code> is returned.</p> 29 * <p> 30 * <strong>Note that this implementation is not synchronized.</strong> If 31 * multiple threads access an instance of this class concurrently, and at least 32 * one of the threads invokes the <code>increment()</code> or 33 * <code>clear()</code> method, it must be synchronized externally.</p> 34 * 35 * @version $Revision: 1006299 $ $Date: 2010-10-10 16:47:17 +0200 (dim. 10 oct. 2010) $ 36 */ 37 public class Sum extends AbstractStorelessUnivariateStatistic implements Serializable { 38 39 /** Serializable version identifier */ 40 private static final long serialVersionUID = -8231831954703408316L; 41 42 /** */ 43 private long n; 44 45 /** 46 * The currently running sum. 47 */ 48 private double value; 49 50 /** 51 * Create a Sum instance 52 */ Sum()53 public Sum() { 54 n = 0; 55 value = Double.NaN; 56 } 57 58 /** 59 * Copy constructor, creates a new {@code Sum} identical 60 * to the {@code original} 61 * 62 * @param original the {@code Sum} instance to copy 63 */ Sum(Sum original)64 public Sum(Sum original) { 65 copy(original, this); 66 } 67 68 /** 69 * {@inheritDoc} 70 */ 71 @Override increment(final double d)72 public void increment(final double d) { 73 if (n == 0) { 74 value = d; 75 } else { 76 value += d; 77 } 78 n++; 79 } 80 81 /** 82 * {@inheritDoc} 83 */ 84 @Override getResult()85 public double getResult() { 86 return value; 87 } 88 89 /** 90 * {@inheritDoc} 91 */ getN()92 public long getN() { 93 return n; 94 } 95 96 /** 97 * {@inheritDoc} 98 */ 99 @Override clear()100 public void clear() { 101 value = Double.NaN; 102 n = 0; 103 } 104 105 /** 106 * The sum of the entries in the specified portion of 107 * the input array, or <code>Double.NaN</code> if the designated subarray 108 * is empty. 109 * <p> 110 * Throws <code>IllegalArgumentException</code> if the array is null.</p> 111 * 112 * @param values the input array 113 * @param begin index of the first array element to include 114 * @param length the number of elements to include 115 * @return the sum of the values or Double.NaN if length = 0 116 * @throws IllegalArgumentException if the array is null or the array index 117 * parameters are not valid 118 */ 119 @Override evaluate(final double[] values, final int begin, final int length)120 public double evaluate(final double[] values, final int begin, final int length) { 121 double sum = Double.NaN; 122 if (test(values, begin, length)) { 123 sum = 0.0; 124 for (int i = begin; i < begin + length; i++) { 125 sum += values[i]; 126 } 127 } 128 return sum; 129 } 130 131 /** 132 * The weighted sum of the entries in the specified portion of 133 * the input array, or <code>Double.NaN</code> if the designated subarray 134 * is empty. 135 * <p> 136 * Throws <code>IllegalArgumentException</code> if any of the following are true: 137 * <ul><li>the values array is null</li> 138 * <li>the weights array is null</li> 139 * <li>the weights array does not have the same length as the values array</li> 140 * <li>the weights array contains one or more infinite values</li> 141 * <li>the weights array contains one or more NaN values</li> 142 * <li>the weights array contains negative values</li> 143 * <li>the start and length arguments do not determine a valid array</li> 144 * </ul></p> 145 * <p> 146 * Uses the formula, <pre> 147 * weighted sum = Σ(values[i] * weights[i]) 148 * </pre></p> 149 * 150 * @param values the input array 151 * @param weights the weights array 152 * @param begin index of the first array element to include 153 * @param length the number of elements to include 154 * @return the sum of the values or Double.NaN if length = 0 155 * @throws IllegalArgumentException if the parameters are not valid 156 * @since 2.1 157 */ evaluate(final double[] values, final double[] weights, final int begin, final int length)158 public double evaluate(final double[] values, final double[] weights, 159 final int begin, final int length) { 160 double sum = Double.NaN; 161 if (test(values, weights, begin, length)) { 162 sum = 0.0; 163 for (int i = begin; i < begin + length; i++) { 164 sum += values[i] * weights[i]; 165 } 166 } 167 return sum; 168 } 169 170 /** 171 * The weighted sum of the entries in the the input array. 172 * <p> 173 * Throws <code>IllegalArgumentException</code> if any of the following are true: 174 * <ul><li>the values array is null</li> 175 * <li>the weights array is null</li> 176 * <li>the weights array does not have the same length as the values array</li> 177 * <li>the weights array contains one or more infinite values</li> 178 * <li>the weights array contains one or more NaN values</li> 179 * <li>the weights array contains negative values</li> 180 * </ul></p> 181 * <p> 182 * Uses the formula, <pre> 183 * weighted sum = Σ(values[i] * weights[i]) 184 * </pre></p> 185 * 186 * @param values the input array 187 * @param weights the weights array 188 * @return the sum of the values or Double.NaN if length = 0 189 * @throws IllegalArgumentException if the parameters are not valid 190 * @since 2.1 191 */ evaluate(final double[] values, final double[] weights)192 public double evaluate(final double[] values, final double[] weights) { 193 return evaluate(values, weights, 0, values.length); 194 } 195 196 /** 197 * {@inheritDoc} 198 */ 199 @Override copy()200 public Sum copy() { 201 Sum result = new Sum(); 202 copy(this, result); 203 return result; 204 } 205 206 /** 207 * Copies source to dest. 208 * <p>Neither source nor dest can be null.</p> 209 * 210 * @param source Sum to copy 211 * @param dest Sum to copy to 212 * @throws NullPointerException if either source or dest is null 213 */ copy(Sum source, Sum dest)214 public static void copy(Sum source, Sum dest) { 215 dest.setData(source.getDataRef()); 216 dest.n = source.n; 217 dest.value = source.value; 218 } 219 220 } 221