001 /* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2008, by Object Refinery Limited and Contributors.
006 *
007 * Project Info: http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
022 * USA.
023 *
024 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
025 * in the United States and other countries.]
026 *
027 * ---------------
028 * Statistics.java
029 * ---------------
030 * (C) Copyright 2000-2008, by Matthew Wright and Contributors.
031 *
032 * Original Author: Matthew Wright;
033 * Contributor(s): David Gilbert (for Object Refinery Limited);
034 *
035 * Changes (from 08-Nov-2001)
036 * --------------------------
037 * 08-Nov-2001 : Added standard header and tidied Javadoc comments (DG);
038 * Moved from JFreeChart to package com.jrefinery.data.* in
039 * JCommon class library (DG);
040 * 24-Jun-2002 : Removed unnecessary local variable (DG);
041 * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
042 * 26-May-2004 : Moved calculateMean() method from BoxAndWhiskerCalculator (DG);
043 * 02-Jun-2004 : Fixed bug in calculateMedian() method (DG);
044 * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0
045 * release (DG);
046 *
047 */
048
049 package org.jfree.data.statistics;
050
051 import java.util.ArrayList;
052 import java.util.Collection;
053 import java.util.Collections;
054 import java.util.Iterator;
055 import java.util.List;
056
057 /**
058 * A utility class that provides some common statistical functions.
059 */
060 public abstract class Statistics {
061
062 /**
063 * Returns the mean of an array of numbers. This is equivalent to calling
064 * <code>calculateMean(values, true)</code>.
065 *
066 * @param values the values (<code>null</code> not permitted).
067 *
068 * @return The mean.
069 */
070 public static double calculateMean(Number[] values) {
071 return calculateMean(values, true);
072 }
073
074 /**
075 * Returns the mean of an array of numbers.
076 *
077 * @param values the values (<code>null</code> not permitted).
078 * @param includeNullAndNaN a flag that controls whether or not
079 * <code>null</code> and <code>Double.NaN</code> values are included
080 * in the calculation (if either is present in the array, the result is
081 * {@link Double#NaN}).
082 *
083 * @return The mean.
084 *
085 * @since 1.0.3
086 */
087 public static double calculateMean(Number[] values,
088 boolean includeNullAndNaN) {
089
090 if (values == null) {
091 throw new IllegalArgumentException("Null 'values' argument.");
092 }
093 double sum = 0.0;
094 double current;
095 int counter = 0;
096 for (int i = 0; i < values.length; i++) {
097 // treat nulls the same as NaNs
098 if (values[i] != null) {
099 current = values[i].doubleValue();
100 }
101 else {
102 current = Double.NaN;
103 }
104 // calculate the sum and count
105 if (includeNullAndNaN || !Double.isNaN(current)) {
106 sum = sum + current;
107 counter++;
108 }
109 }
110 double result = (sum / counter);
111 return result;
112 }
113
114 /**
115 * Returns the mean of a collection of <code>Number</code> objects.
116 *
117 * @param values the values (<code>null</code> not permitted).
118 *
119 * @return The mean.
120 */
121 public static double calculateMean(Collection values) {
122 return calculateMean(values, true);
123 }
124
125 /**
126 * Returns the mean of a collection of <code>Number</code> objects.
127 *
128 * @param values the values (<code>null</code> not permitted).
129 * @param includeNullAndNaN a flag that controls whether or not
130 * <code>null</code> and <code>Double.NaN</code> values are included
131 * in the calculation (if either is present in the array, the result is
132 * {@link Double#NaN}).
133 *
134 * @return The mean.
135 *
136 * @since 1.0.3
137 */
138 public static double calculateMean(Collection values,
139 boolean includeNullAndNaN) {
140
141 if (values == null) {
142 throw new IllegalArgumentException("Null 'values' argument.");
143 }
144 int count = 0;
145 double total = 0.0;
146 Iterator iterator = values.iterator();
147 while (iterator.hasNext()) {
148 Object object = iterator.next();
149 if (object == null) {
150 if (includeNullAndNaN) {
151 return Double.NaN;
152 }
153 }
154 else {
155 if (object instanceof Number) {
156 Number number = (Number) object;
157 double value = number.doubleValue();
158 if (Double.isNaN(value)) {
159 if (includeNullAndNaN) {
160 return Double.NaN;
161 }
162 }
163 else {
164 total = total + number.doubleValue();
165 count = count + 1;
166 }
167 }
168 }
169 }
170 return total / count;
171 }
172
173 /**
174 * Calculates the median for a list of values (<code>Number</code> objects).
175 * The list of values will be copied, and the copy sorted, before
176 * calculating the median. To avoid this step (if your list of values
177 * is already sorted), use the {@link #calculateMedian(List, boolean)}
178 * method.
179 *
180 * @param values the values (<code>null</code> permitted).
181 *
182 * @return The median.
183 */
184 public static double calculateMedian(List values) {
185 return calculateMedian(values, true);
186 }
187
188 /**
189 * Calculates the median for a list of values (<code>Number</code> objects).
190 * If <code>copyAndSort</code> is <code>false</code>, the list is assumed
191 * to be presorted in ascending order by value.
192 *
193 * @param values the values (<code>null</code> permitted).
194 * @param copyAndSort a flag that controls whether the list of values is
195 * copied and sorted.
196 *
197 * @return The median.
198 */
199 public static double calculateMedian(List values, boolean copyAndSort) {
200
201 double result = Double.NaN;
202 if (values != null) {
203 if (copyAndSort) {
204 int itemCount = values.size();
205 List copy = new ArrayList(itemCount);
206 for (int i = 0; i < itemCount; i++) {
207 copy.add(i, values.get(i));
208 }
209 Collections.sort(copy);
210 values = copy;
211 }
212 int count = values.size();
213 if (count > 0) {
214 if (count % 2 == 1) {
215 if (count > 1) {
216 Number value = (Number) values.get((count - 1) / 2);
217 result = value.doubleValue();
218 }
219 else {
220 Number value = (Number) values.get(0);
221 result = value.doubleValue();
222 }
223 }
224 else {
225 Number value1 = (Number) values.get(count / 2 - 1);
226 Number value2 = (Number) values.get(count / 2);
227 result = (value1.doubleValue() + value2.doubleValue())
228 / 2.0;
229 }
230 }
231 }
232 return result;
233 }
234
235 /**
236 * Calculates the median for a sublist within a list of values
237 * (<code>Number</code> objects).
238 *
239 * @param values the values, in any order (<code>null</code> not
240 * permitted).
241 * @param start the start index.
242 * @param end the end index.
243 *
244 * @return The median.
245 */
246 public static double calculateMedian(List values, int start, int end) {
247 return calculateMedian(values, start, end, true);
248 }
249
250 /**
251 * Calculates the median for a sublist within a list of values
252 * (<code>Number</code> objects). The entire list will be sorted if the
253 * <code>ascending</code< argument is <code>false</code>.
254 *
255 * @param values the values (<code>null</code> not permitted).
256 * @param start the start index.
257 * @param end the end index.
258 * @param copyAndSort a flag that that controls whether the list of values
259 * is copied and sorted.
260 *
261 * @return The median.
262 */
263 public static double calculateMedian(List values, int start, int end,
264 boolean copyAndSort) {
265
266 double result = Double.NaN;
267 if (copyAndSort) {
268 List working = new ArrayList(end - start + 1);
269 for (int i = start; i <= end; i++) {
270 working.add(values.get(i));
271 }
272 Collections.sort(working);
273 result = calculateMedian(working, false);
274 }
275 else {
276 int count = end - start + 1;
277 if (count > 0) {
278 if (count % 2 == 1) {
279 if (count > 1) {
280 Number value
281 = (Number) values.get(start + (count - 1) / 2);
282 result = value.doubleValue();
283 }
284 else {
285 Number value = (Number) values.get(start);
286 result = value.doubleValue();
287 }
288 }
289 else {
290 Number value1 = (Number) values.get(start + count / 2 - 1);
291 Number value2 = (Number) values.get(start + count / 2);
292 result
293 = (value1.doubleValue() + value2.doubleValue()) / 2.0;
294 }
295 }
296 }
297 return result;
298
299 }
300
301 /**
302 * Returns the standard deviation of a set of numbers.
303 *
304 * @param data the data (<code>null</code> or zero length array not
305 * permitted).
306 *
307 * @return The standard deviation of a set of numbers.
308 */
309 public static double getStdDev(Number[] data) {
310 if (data == null) {
311 throw new IllegalArgumentException("Null 'data' array.");
312 }
313 if (data.length == 0) {
314 throw new IllegalArgumentException("Zero length 'data' array.");
315 }
316 double avg = calculateMean(data);
317 double sum = 0.0;
318
319 for (int counter = 0; counter < data.length; counter++) {
320 double diff = data[counter].doubleValue() - avg;
321 sum = sum + diff * diff;
322 }
323 return Math.sqrt(sum / (data.length - 1));
324 }
325
326 /**
327 * Fits a straight line to a set of (x, y) data, returning the slope and
328 * intercept.
329 *
330 * @param xData the x-data (<code>null</code> not permitted).
331 * @param yData the y-data (<code>null</code> not permitted).
332 *
333 * @return A double array with the intercept in [0] and the slope in [1].
334 */
335 public static double[] getLinearFit(Number[] xData, Number[] yData) {
336
337 if (xData == null) {
338 throw new IllegalArgumentException("Null 'xData' argument.");
339 }
340 if (yData == null) {
341 throw new IllegalArgumentException("Null 'yData' argument.");
342 }
343 if (xData.length != yData.length) {
344 throw new IllegalArgumentException(
345 "Statistics.getLinearFit(): array lengths must be equal.");
346 }
347
348 double[] result = new double[2];
349 // slope
350 result[1] = getSlope(xData, yData);
351 // intercept
352 result[0] = calculateMean(yData) - result[1] * calculateMean(xData);
353
354 return result;
355
356 }
357
358 /**
359 * Finds the slope of a regression line using least squares.
360 *
361 * @param xData the x-values (<code>null</code> not permitted).
362 * @param yData the y-values (<code>null</code> not permitted).
363 *
364 * @return The slope.
365 */
366 public static double getSlope(Number[] xData, Number[] yData) {
367
368 if (xData == null) {
369 throw new IllegalArgumentException("Null 'xData' argument.");
370 }
371 if (yData == null) {
372 throw new IllegalArgumentException("Null 'yData' argument.");
373 }
374 if (xData.length != yData.length) {
375 throw new IllegalArgumentException("Array lengths must be equal.");
376 }
377
378 // ********* stat function for linear slope ********
379 // y = a + bx
380 // a = ybar - b * xbar
381 // sum(x * y) - (sum (x) * sum(y)) / n
382 // b = ------------------------------------
383 // sum (x^2) - (sum(x)^2 / n
384 // *************************************************
385
386 // sum of x, x^2, x * y, y
387 double sx = 0.0, sxx = 0.0, sxy = 0.0, sy = 0.0;
388 int counter;
389 for (counter = 0; counter < xData.length; counter++) {
390 sx = sx + xData[counter].doubleValue();
391 sxx = sxx + Math.pow(xData[counter].doubleValue(), 2);
392 sxy = sxy + yData[counter].doubleValue()
393 * xData[counter].doubleValue();
394 sy = sy + yData[counter].doubleValue();
395 }
396 return (sxy - (sx * sy) / counter) / (sxx - (sx * sx) / counter);
397
398 }
399
400 /**
401 * Calculates the correlation between two datasets. Both arrays should
402 * contain the same number of items. Null values are treated as zero.
403 * <P>
404 * Information about the correlation calculation was obtained from:
405 *
406 * http://trochim.human.cornell.edu/kb/statcorr.htm
407 *
408 * @param data1 the first dataset.
409 * @param data2 the second dataset.
410 *
411 * @return The correlation.
412 */
413 public static double getCorrelation(Number[] data1, Number[] data2) {
414 if (data1 == null) {
415 throw new IllegalArgumentException("Null 'data1' argument.");
416 }
417 if (data2 == null) {
418 throw new IllegalArgumentException("Null 'data2' argument.");
419 }
420 if (data1.length != data2.length) {
421 throw new IllegalArgumentException(
422 "'data1' and 'data2' arrays must have same length."
423 );
424 }
425 int n = data1.length;
426 double sumX = 0.0;
427 double sumY = 0.0;
428 double sumX2 = 0.0;
429 double sumY2 = 0.0;
430 double sumXY = 0.0;
431 for (int i = 0; i < n; i++) {
432 double x = 0.0;
433 if (data1[i] != null) {
434 x = data1[i].doubleValue();
435 }
436 double y = 0.0;
437 if (data2[i] != null) {
438 y = data2[i].doubleValue();
439 }
440 sumX = sumX + x;
441 sumY = sumY + y;
442 sumXY = sumXY + (x * y);
443 sumX2 = sumX2 + (x * x);
444 sumY2 = sumY2 + (y * y);
445 }
446 return (n * sumXY - sumX * sumY) / Math.pow((n * sumX2 - sumX * sumX)
447 * (n * sumY2 - sumY * sumY), 0.5);
448 }
449
450 /**
451 * Returns a data set for a moving average on the data set passed in.
452 *
453 * @param xData an array of the x data.
454 * @param yData an array of the y data.
455 * @param period the number of data points to average
456 *
457 * @return A double[][] the length of the data set in the first dimension,
458 * with two doubles for x and y in the second dimension
459 */
460 public static double[][] getMovingAverage(Number[] xData,
461 Number[] yData,
462 int period) {
463
464 // check arguments...
465 if (xData.length != yData.length) {
466 throw new IllegalArgumentException("Array lengths must be equal.");
467 }
468
469 if (period > xData.length) {
470 throw new IllegalArgumentException(
471 "Period can't be longer than dataset."
472 );
473 }
474
475 double[][] result = new double[xData.length - period][2];
476 for (int i = 0; i < result.length; i++) {
477 result[i][0] = xData[i + period].doubleValue();
478 // holds the moving average sum
479 double sum = 0.0;
480 for (int j = 0; j < period; j++) {
481 sum += yData[i + j].doubleValue();
482 }
483 sum = sum / period;
484 result[i][1] = sum;
485 }
486 return result;
487
488 }
489
490 }