    001/* ===========================================================
    002 * JFreeChart : a free chart library for the Java(tm) platform
    003 * ===========================================================
    004 *
    005 * (C) Copyright 2000-2011, 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 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates.
    025 * Other names may be trademarks of their respective owners.]
    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
    049package org.jfree.data.statistics;
    050
    051import java.util.ArrayList;
    052import java.util.Collection;
    053import java.util.Collections;
    054import java.util.Iterator;
    055import java.util.List;
    056
    057/**
    058 * A utility class that provides some common statistical functions.
    059 */
    060public 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}