KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > math > stat > StatUtils


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.apache.commons.math.stat;
17
18 import org.apache.commons.math.stat.descriptive.UnivariateStatistic;
19 import org.apache.commons.math.stat.descriptive.moment.GeometricMean;
20 import org.apache.commons.math.stat.descriptive.moment.Mean;
21 import org.apache.commons.math.stat.descriptive.moment.Variance;
22 import org.apache.commons.math.stat.descriptive.rank.Max;
23 import org.apache.commons.math.stat.descriptive.rank.Min;
24 import org.apache.commons.math.stat.descriptive.rank.Percentile;
25 import org.apache.commons.math.stat.descriptive.summary.Product;
26 import org.apache.commons.math.stat.descriptive.summary.Sum;
27 import org.apache.commons.math.stat.descriptive.summary.SumOfLogs;
28 import org.apache.commons.math.stat.descriptive.summary.SumOfSquares;
29
30 /**
31  * StatUtils provides static methods for computing statistics based on data
32  * stored in double[] arrays.
33  *
34  * @version $Revision$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $
35  */

36 public final class StatUtils {
37
38     /** sum */
39     private static UnivariateStatistic sum = new Sum();
40
41     /** sumSq */
42     private static UnivariateStatistic sumSq = new SumOfSquares();
43
44     /** prod */
45     private static UnivariateStatistic prod = new Product();
46
47     /** sumLog */
48     private static UnivariateStatistic sumLog = new SumOfLogs();
49
50     /** min */
51     private static UnivariateStatistic min = new Min();
52
53     /** max */
54     private static UnivariateStatistic max = new Max();
55
56     /** mean */
57     private static UnivariateStatistic mean = new Mean();
58
59     /** variance */
60     private static Variance variance = new Variance();
61
62     /** percentile */
63     private static Percentile percentile = new Percentile();
64     
65     /** geometric mean */
66     private static GeometricMean geometricMean = new GeometricMean();
67
68     /**
69      * Private Constructor
70      */

71     private StatUtils() {
72     }
73
74     /**
75      * Returns the sum of the values in the input array, or
76      * <code>Double.NaN</code> if the array is empty.
77      * <p>
78      * Throws <code>IllegalArgumentException</code> if the input array
79      * is null.
80      *
81      * @param values array of values to sum
82      * @return the sum of the values or <code>Double.NaN</code> if the array
83      * is empty
84      * @throws IllegalArgumentException if the array is null
85      */

86     public static double sum(final double[] values) {
87         return sum.evaluate(values);
88     }
89
90     /**
91      * Returns the sum of the entries in the specified portion of
92      * the input array, or <code>Double.NaN</code> if the designated subarray
93      * is empty.
94      * <p>
95      * Throws <code>IllegalArgumentException</code> if the array is null.
96      *
97      * @param values the input array
98      * @param begin index of the first array element to include
99      * @param length the number of elements to include
100      * @return the sum of the values or Double.NaN if length = 0
101      * @throws IllegalArgumentException if the array is null or the array index
102      * parameters are not valid
103      */

104     public static double sum(final double[] values, final int begin,
105             final int length) {
106         return sum.evaluate(values, begin, length);
107     }
108
109     /**
110      * Returns the sum of the squares of the entries in the input array, or
111      * <code>Double.NaN</code> if the array is empty.
112      * <p>
113      * Throws <code>IllegalArgumentException</code> if the array is null.
114      *
115      * @param values input array
116      * @return the sum of the squared values or <code>Double.NaN</code> if the
117      * array is empty
118      * @throws IllegalArgumentException if the array is null
119      */

120     public static double sumSq(final double[] values) {
121         return sumSq.evaluate(values);
122     }
123
124     /**
125      * Returns the sum of the squares of the entries in the specified portion of
126      * the input array, or <code>Double.NaN</code> if the designated subarray
127      * is empty.
128      * <p>
129      * Throws <code>IllegalArgumentException</code> if the array is null.
130      *
131      * @param values the input array
132      * @param begin index of the first array element to include
133      * @param length the number of elements to include
134      * @return the sum of the squares of the values or Double.NaN if length = 0
135      * @throws IllegalArgumentException if the array is null or the array index
136      * parameters are not valid
137      */

138     public static double sumSq(final double[] values, final int begin,
139             final int length) {
140         return sumSq.evaluate(values, begin, length);
141     }
142
143     /**
144      * Returns the product of the entries in the input array, or
145      * <code>Double.NaN</code> if the array is empty.
146      * <p>
147      * Throws <code>IllegalArgumentException</code> if the array is null.
148      *
149      * @param values the input array
150      * @return the product of the values or Double.NaN if the array is empty
151      * @throws IllegalArgumentException if the array is null
152      */

153     public static double product(final double[] values) {
154         return prod.evaluate(values);
155     }
156
157     /**
158      * Returns the product of the entries in the specified portion of
159      * the input array, or <code>Double.NaN</code> if the designated subarray
160      * is empty.
161      * <p>
162      * Throws <code>IllegalArgumentException</code> if the array is null.
163      *
164      * @param values the input array
165      * @param begin index of the first array element to include
166      * @param length the number of elements to include
167      * @return the product of the values or Double.NaN if length = 0
168      * @throws IllegalArgumentException if the array is null or the array index
169      * parameters are not valid
170      */

171     public static double product(final double[] values, final int begin,
172             final int length) {
173         return prod.evaluate(values, begin, length);
174     }
175
176     /**
177      * Returns the sum of the natural logs of the entries in the input array, or
178      * <code>Double.NaN</code> if the array is empty.
179      * <p>
180      * Throws <code>IllegalArgumentException</code> if the array is null.
181      * <p>
182      * See {@link org.apache.commons.math.stat.descriptive.summary.SumOfLogs}.
183      *
184      * @param values the input array
185      * @return the sum of the natural logs of the values or Double.NaN if
186      * the array is empty
187      * @throws IllegalArgumentException if the array is null
188      */

189     public static double sumLog(final double[] values) {
190         return sumLog.evaluate(values);
191     }
192
193     /**
194      * Returns the sum of the natural logs of the entries in the specified portion of
195      * the input array, or <code>Double.NaN</code> if the designated subarray
196      * is empty.
197      * <p>
198      * Throws <code>IllegalArgumentException</code> if the array is null.
199      * <p>
200       * See {@link org.apache.commons.math.stat.descriptive.summary.SumOfLogs}.
201      *
202      * @param values the input array
203      * @param begin index of the first array element to include
204      * @param length the number of elements to include
205      * @return the sum of the natural logs of the values or Double.NaN if
206      * length = 0
207      * @throws IllegalArgumentException if the array is null or the array index
208      * parameters are not valid
209      */

210     public static double sumLog(final double[] values, final int begin,
211             final int length) {
212         return sumLog.evaluate(values, begin, length);
213     }
214
215     /**
216      * Returns the arithmetic mean of the entries in the input array, or
217      * <code>Double.NaN</code> if the array is empty.
218      * <p>
219      * Throws <code>IllegalArgumentException</code> if the array is null.
220      * <p>
221      * See {@link org.apache.commons.math.stat.descriptive.moment.Mean} for
222      * details on the computing algorithm.
223      *
224      * @param values the input array
225      * @return the mean of the values or Double.NaN if the array is empty
226      * @throws IllegalArgumentException if the array is null
227      */

228     public static double mean(final double[] values) {
229         return mean.evaluate(values);
230     }
231
232     /**
233      * Returns the arithmetic mean of the entries in the specified portion of
234      * the input array, or <code>Double.NaN</code> if the designated subarray
235      * is empty.
236      * <p>
237      * Throws <code>IllegalArgumentException</code> if the array is null.
238      * <p>
239      * See {@link org.apache.commons.math.stat.descriptive.moment.Mean} for
240      * details on the computing algorithm.
241      *
242      * @param values the input array
243      * @param begin index of the first array element to include
244      * @param length the number of elements to include
245      * @return the mean of the values or Double.NaN if length = 0
246      * @throws IllegalArgumentException if the array is null or the array index
247      * parameters are not valid
248      */

249     public static double mean(final double[] values, final int begin,
250             final int length) {
251         return mean.evaluate(values, begin, length);
252     }
253     
254     /**
255      * Returns the geometric mean of the entries in the input array, or
256      * <code>Double.NaN</code> if the array is empty.
257      * <p>
258      * Throws <code>IllegalArgumentException</code> if the array is null.
259      * <p>
260      * See {@link org.apache.commons.math.stat.descriptive.moment.GeometricMean}
261      * for details on the computing algorithm.
262      *
263      * @param values the input array
264      * @return the geometric mean of the values or Double.NaN if the array is empty
265      * @throws IllegalArgumentException if the array is null
266      */

267     public static double geometricMean(final double[] values) {
268         return geometricMean.evaluate(values);
269     }
270
271     /**
272      * Returns the geometric mean of the entries in the specified portion of
273      * the input array, or <code>Double.NaN</code> if the designated subarray
274      * is empty.
275      * <p>
276      * Throws <code>IllegalArgumentException</code> if the array is null.
277      * <p>
278      * See {@link org.apache.commons.math.stat.descriptive.moment.GeometricMean}
279      * for details on the computing algorithm.
280      *
281      * @param values the input array
282      * @param begin index of the first array element to include
283      * @param length the number of elements to include
284      * @return the geometric mean of the values or Double.NaN if length = 0
285      * @throws IllegalArgumentException if the array is null or the array index
286      * parameters are not valid
287      */

288     public static double geometricMean(final double[] values, final int begin,
289             final int length) {
290         return geometricMean.evaluate(values, begin, length);
291     }
292     
293
294     /**
295      * Returns the variance of the entries in the input array, or
296      * <code>Double.NaN</code> if the array is empty.
297      * <p>
298      * See {@link org.apache.commons.math.stat.descriptive.moment.Variance} for
299      * details on the computing algorithm.
300      * <p>
301      * Returns 0 for a single-value (i.e. length = 1) sample.
302      * <p>
303      * Throws <code>IllegalArgumentException</code> if the array is null.
304      *
305      * @param values the input array
306      * @return the variance of the values or Double.NaN if the array is empty
307      * @throws IllegalArgumentException if the array is null
308      */

309     public static double variance(final double[] values) {
310         return variance.evaluate(values);
311     }
312
313     /**
314      * Returns the variance of the entries in the specified portion of
315      * the input array, or <code>Double.NaN</code> if the designated subarray
316      * is empty.
317      * <p>
318      * See {@link org.apache.commons.math.stat.descriptive.moment.Variance} for
319      * details on the computing algorithm.
320      * <p>
321      * Returns 0 for a single-value (i.e. length = 1) sample.
322      * <p>
323      * Throws <code>IllegalArgumentException</code> if the array is null or the
324      * array index parameters are not valid.
325      *
326      * @param values the input array
327      * @param begin index of the first array element to include
328      * @param length the number of elements to include
329      * @return the variance of the values or Double.NaN if length = 0
330      * @throws IllegalArgumentException if the array is null or the array index
331      * parameters are not valid
332      */

333     public static double variance(final double[] values, final int begin,
334             final int length) {
335         return variance.evaluate(values, begin, length);
336     }
337     
338     /**
339      * Returns the variance of the entries in the specified portion of
340      * the input array, using the precomputed mean value. Returns
341      * <code>Double.NaN</code> if the designated subarray is empty.
342      * <p>
343      * See {@link org.apache.commons.math.stat.descriptive.moment.Variance} for
344      * details on the computing algorithm.
345      * <p>
346      * The formula used assumes that the supplied mean value is the arithmetic
347      * mean of the sample data, not a known population parameter. This method
348      * is supplied only to save computation when the mean has already been
349      * computed.
350      * <p>
351      * Returns 0 for a single-value (i.e. length = 1) sample.
352      * <p>
353      * Throws <code>IllegalArgumentException</code> if the array is null or the
354      * array index parameters are not valid.
355      *
356      * @param values the input array
357      * @param mean the precomputed mean value
358      * @param begin index of the first array element to include
359      * @param length the number of elements to include
360      * @return the variance of the values or Double.NaN if length = 0
361      * @throws IllegalArgumentException if the array is null or the array index
362      * parameters are not valid
363      */

364     public static double variance(final double[] values, final double mean,
365             final int begin, final int length) {
366         return variance.evaluate(values, mean, begin, length);
367     }
368     
369     /**
370      * Returns the variance of the entries in the input array, using the
371      * precomputed mean value. Returns <code>Double.NaN</code> if the array
372      * is empty.
373      * <p>
374      * See {@link org.apache.commons.math.stat.descriptive.moment.Variance} for
375      * details on the computing algorithm.
376      * <p>
377      * The formula used assumes that the supplied mean value is the arithmetic
378      * mean of the sample data, not a known population parameter. This method
379      * is supplied only to save computation when the mean has already been
380      * computed.
381      * <p>
382      * Returns 0 for a single-value (i.e. length = 1) sample.
383      * <p>
384      * Throws <code>IllegalArgumentException</code> if the array is null.
385      *
386      * @param values the input array
387      * @param mean the precomputed mean value
388      * @return the variance of the values or Double.NaN if the array is empty
389      * @throws IllegalArgumentException if the array is null
390      */

391     public static double variance(final double[] values, final double mean) {
392         return variance.evaluate(values, mean);
393     }
394
395     /**
396      * Returns the maximum of the entries in the input array, or
397      * <code>Double.NaN</code> if the array is empty.
398      * <p>
399      * Throws <code>IllegalArgumentException</code> if the array is null.
400      * <p>
401      * <ul>
402      * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
403      * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
404      * <li>If any of the values equals <code>Double.POSITIVE_INFINITY</code>,
405      * the result is <code>Double.POSITIVE_INFINITY.</code></li>
406      * </ul>
407      *
408      * @param values the input array
409      * @return the maximum of the values or Double.NaN if the array is empty
410      * @throws IllegalArgumentException if the array is null
411      */

412     public static double max(final double[] values) {
413         return max.evaluate(values);
414     }
415
416     /**
417      * Returns the maximum of the entries in the specified portion of
418      * the input array, or <code>Double.NaN</code> if the designated subarray
419      * is empty.
420      * <p>
421      * Throws <code>IllegalArgumentException</code> if the array is null or
422      * the array index parameters are not valid.
423      * <p>
424      * <ul>
425      * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
426      * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
427      * <li>If any of the values equals <code>Double.POSITIVE_INFINITY</code>,
428      * the result is <code>Double.POSITIVE_INFINITY.</code></li>
429      * </ul>
430      *
431      * @param values the input array
432      * @param begin index of the first array element to include
433      * @param length the number of elements to include
434      * @return the maximum of the values or Double.NaN if length = 0
435      * @throws IllegalArgumentException if the array is null or the array index
436      * parameters are not valid
437      */

438     public static double max(final double[] values, final int begin,
439             final int length) {
440         return max.evaluate(values, begin, length);
441     }
442
443      /**
444      * Returns the minimum of the entries in the input array, or
445      * <code>Double.NaN</code> if the array is empty.
446      * <p>
447      * Throws <code>IllegalArgumentException</code> if the array is null.
448      * <p>
449      * <ul>
450      * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
451      * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
452      * <li>If any of the values equals <code>Double.NEGATIVE_INFINITY</code>,
453      * the result is <code>Double.NEGATIVE_INFINITY.</code></li>
454      * </ul>
455      *
456      * @param values the input array
457      * @return the minimum of the values or Double.NaN if the array is empty
458      * @throws IllegalArgumentException if the array is null
459      */

460     public static double min(final double[] values) {
461         return min.evaluate(values);
462     }
463
464      /**
465      * Returns the minimum of the entries in the specified portion of
466      * the input array, or <code>Double.NaN</code> if the designated subarray
467      * is empty.
468      * <p>
469      * Throws <code>IllegalArgumentException</code> if the array is null or
470      * the array index parameters are not valid.
471      * <p>
472      * <ul>
473      * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
474      * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
475      * <li>If any of the values equals <code>Double.NEGATIVE_INFINITY</code>,
476      * the result is <code>Double.NEGATIVE_INFINITY.</code></li>
477      * </ul>
478      *
479      * @param values the input array
480      * @param begin index of the first array element to include
481      * @param length the number of elements to include
482      * @return the minimum of the values or Double.NaN if length = 0
483      * @throws IllegalArgumentException if the array is null or the array index
484      * parameters are not valid
485      */

486     public static double min(final double[] values, final int begin,
487             final int length) {
488         return min.evaluate(values, begin, length);
489     }
490     
491     /**
492      * Returns an estimate of the <code>p</code>th percentile of the values
493      * in the <code>values</code> array.
494      * <p>
495      * <ul>
496      * <li>Returns <code>Double.NaN</code> if <code>values</code> has length
497      * <code>0</code></li>
498      * <li>Returns (for any value of <code>p</code>) <code>values[0]</code>
499      * if <code>values</code> has length <code>1</code></li>
500      * <li>Throws <code>IllegalArgumentException</code> if <code>values</code>
501      * is null or p is not a valid quantile value (p must be greater than 0
502      * and less than or equal to 100)</li>
503      * </ul>
504      * <p>
505      * See {@link org.apache.commons.math.stat.descriptive.rank.Percentile} for
506      * a description of the percentile estimation algorithm used.
507      *
508      * @param values input array of values
509      * @param p the percentile value to compute
510      * @return the percentile value or Double.NaN if the array is empty
511      * @throws IllegalArgumentException if <code>values</code> is null
512      * or p is invalid
513      */

514     public static double percentile(final double[] values, final double p) {
515             return percentile.evaluate(values,p);
516     }
517
518      /**
519      * Returns an estimate of the <code>p</code>th percentile of the values
520      * in the <code>values</code> array, starting with the element in (0-based)
521      * position <code>begin</code> in the array and including <code>length</code>
522      * values.
523      * <p>
524      * <ul>
525      * <li>Returns <code>Double.NaN</code> if <code>length = 0</code></li>
526      * <li>Returns (for any value of <code>p</code>) <code>values[begin]</code>
527      * if <code>length = 1 </code></li>
528      * <li>Throws <code>IllegalArgumentException</code> if <code>values</code>
529      * is null , <code>begin</code> or <code>length</code> is invalid, or
530      * <code>p</code> is not a valid quantile value (p must be greater than 0
531      * and less than or equal to 100)</li>
532      * </ul>
533      * <p>
534       * See {@link org.apache.commons.math.stat.descriptive.rank.Percentile} for
535       * a description of the percentile estimation algorithm used.
536      *
537      * @param values array of input values
538      * @param p the percentile to compute
539      * @param begin the first (0-based) element to include in the computation
540      * @param length the number of array elements to include
541      * @return the percentile value
542      * @throws IllegalArgumentException if the parameters are not valid or the
543      * input array is null
544      */

545     public static double percentile(final double[] values, final int begin,
546             final int length, final double p) {
547         return percentile.evaluate(values, begin, length, p);
548     }
549     
550     /**
551      * Returns the sum of the (signed) differences between corresponding elements of the
552      * input arrays -- i.e., sum(sample1[i] - sample2[i]).
553      *
554      * @param sample1 the first array
555      * @param sample2 the second array
556      * @return sum of paired differences
557      * @throws IllegalArgumentException if the arrays do not have the same
558      * (positive) length
559      */

560     public static double sumDifference(final double[] sample1, final double[] sample2)
561         throws IllegalArgumentException JavaDoc {
562         int n = sample1.length;
563         if (n != sample2.length || n < 1) {
564             throw new IllegalArgumentException JavaDoc
565                 ("Input arrays must have the same (positive) length.");
566         }
567         double result = 0;
568         for (int i = 0; i < n; i++) {
569             result += sample1[i] - sample2[i];
570         }
571         return result;
572     }
573     
574     /**
575      * Returns the mean of the (signed) differences between corresponding elements of the
576      * input arrays -- i.e., sum(sample1[i] - sample2[i]) / sample1.length.
577      *
578      * @param sample1 the first array
579      * @param sample2 the second array
580      * @return mean of paired differences
581      * @throws IllegalArgumentException if the arrays do not have the same
582      * (positive) length
583      */

584     public static double meanDifference(final double[] sample1, final double[] sample2)
585     throws IllegalArgumentException JavaDoc {
586         return sumDifference(sample1, sample2) / (double) sample1.length;
587     }
588     
589     /**
590      * Returns the variance of the (signed) differences between corresponding elements of the
591      * input arrays -- i.e., var(sample1[i] - sample2[i]).
592      *
593      * @param sample1 the first array
594      * @param sample2 the second array
595      * @param meanDifference the mean difference between corresponding entries
596      * @see #meanDifference(double[],double[])
597      * @return variance of paired differences
598      * @throws IllegalArgumentException if the arrays do not have the same
599      * length or their common length is less than 2.
600      */

601     public static double varianceDifference(final double[] sample1, final double[] sample2,
602             double meanDifference) throws IllegalArgumentException JavaDoc {
603         double sum1 = 0d;
604         double sum2 = 0d;
605         double diff = 0d;
606         int n = sample1.length;
607         if (n < 2) {
608             throw new IllegalArgumentException JavaDoc("Input array lengths must be at least 2.");
609         }
610         for (int i = 0; i < n; i++) {
611             diff = sample1[i] - sample2[i];
612             sum1 += (diff - meanDifference) *(diff - meanDifference);
613             sum2 += diff - meanDifference;
614         }
615         return (sum1 - (sum2 * sum2 / (double) n)) / (double) (n - 1);
616     }
617     
618 }
Popular Tags