Class Histogram

  • All Implemented Interfaces:
    java.lang.Comparable<AbstractStatistic>, GetNameIfc, IdentityIfc, ArraySaverIfc, CollectorIfc, GetCSVStatisticIfc, StatisticAccessorIfc

    public class Histogram
    extends AbstractStatistic
    A Histogram tabulates data into bins. The user must specify the lower limit of the first bin, the width of the bins, and the number of bins. Alternatively, the user can use the static methods makeHistogram() to specify the range of the data via a lower limit and upper limit and a desired number of bins. For a histogram that automatically specifies the bins, see CachedHistogram
    • Field Detail

      • myNumBins

        protected int myNumBins
        The number of bins for the histogram
      • myFirstBinLL

        protected double myFirstBinLL
        Lower limit of first histogram bin.
      • myLastBinUL

        protected double myLastBinUL
        Upper limit of last histogram bin.
      • myBinWidth

        protected double myBinWidth
        Width of a bin.
      • myCountData

        protected double[] myCountData
        Histogram counts.
      • myUnderFlowCount

        protected double myUnderFlowCount
        Counts of values located below first bin.
      • myOverFlowCount

        protected double myOverFlowCount
        Counts of values located above last bin.
      • myStatistic

        protected Statistic myStatistic
        Collects statistical information
    • Constructor Detail

      • Histogram

        protected Histogram()
      • Histogram

        public Histogram​(int numBins,
                         double binWidth)
        Create a histogram with the lower limit of the first bin equal to 0.0
        Parameters:
        numBins - number of bins
        binWidth - The width of each bin
      • Histogram

        public Histogram​(double firstBinLL,
                         int numBins,
                         double binWidth)
        Create a histogram
        Parameters:
        firstBinLL - lower limit of first bin
        numBins - number of bins
        binWidth - The width of each bin
      • Histogram

        public Histogram​(double firstBinLL,
                         int numBins,
                         double binWidth,
                         java.lang.String name)
        Create a histogram with the given name
        Parameters:
        firstBinLL - lower limit of first bin
        numBins - number of bins
        binWidth - The width of each bin
        name - the name of the histogram
      • Histogram

        public Histogram​(double firstBinLL,
                         int numBins,
                         double binWidth,
                         double[] values)
        Create a histogram with based on the provided values
        Parameters:
        firstBinLL - lower limit of first bin
        numBins - number of bins
        binWidth - The width of each bin
        values - an array of data values to collect on when creating the histogram
      • Histogram

        public Histogram​(double firstBinLL,
                         int numBins,
                         double binWidth,
                         java.lang.String name,
                         double[] values)
        Create a histogram with the given name based on the provided values
        Parameters:
        firstBinLL - lower limit of first bin
        numBins - number of bins
        binWidth - The width of each bin
        name - the name of the histogram
        values - an array of data values to collect on when creating the histogram
    • Method Detail

      • makeHistogram

        public static Histogram makeHistogram​(double upperLimit,
                                              int numBins)
        Create a histogram with lower limit set to zero
        Parameters:
        upperLimit - the upper limit of the last bin
        numBins - the number of bins to create
        Returns:
        the histogram
      • makeHistogram

        public static Histogram makeHistogram​(double lowerLimit,
                                              double upperLimit,
                                              int numBins)
        Create a histogram
        Parameters:
        lowerLimit - lower limit of first bin
        upperLimit - the upper limit of the last bin
        numBins - the number of bins to create
        Returns:
        the histogram
      • makeHistogram

        public static Histogram makeHistogram​(double lowerLimit,
                                              double upperLimit,
                                              int numBins,
                                              java.lang.String name)
        Create a histogram with the given name
        Parameters:
        lowerLimit - lower limit of first bin
        upperLimit - the upper limit of the last bin
        numBins - the number of bins to create
        name - the name of the histogram
        Returns:
        the histogram
      • makeHistogram

        public static Histogram makeHistogram​(double lowerLimit,
                                              double upperLimit,
                                              int numBins,
                                              java.lang.String name,
                                              double[] values)
        Create a histogram with the given name based on the provided values
        Parameters:
        lowerLimit - lower limit of first bin
        upperLimit - the upper limit of the last bin
        numBins - the number of bins to create
        name - the name of the histogram
        values - an array of data values to collect on when creating the histogram
        Returns:
        the histogram
      • collect

        public void collect​(double x)
        Description copied from interface: CollectorIfc
        Collect on the supplied value
        Parameters:
        x - a double representing the observation
      • binIndex

        protected final int binIndex​(double x)
        computes the zero based bin index for the bin that x falls within
        Parameters:
        x - the x to find
        Returns:
        the bin index
      • reset

        public void reset()
        Description copied from interface: CollectorIfc
        Resets the collector as if no observations had been collected.
      • getBinNumber

        public final int getBinNumber​(double x)
        Bins are numbered starting at 1 through the number of bins
        Parameters:
        x - double
        Returns:
        int the number of the bin where x is located
      • getUnderFlowCount

        public final double getUnderFlowCount()
        The number of observations that fell below the first bin's lower limit
        Returns:
        number of observations that fell below the first bin's lower limit
      • getOverFlowCount

        public final double getOverFlowCount()
        The number of observations that fell past the last bin's upper limit
        Returns:
        number of observations that fell past the last bin's upper limit
      • getBin

        public final Histogram.Bin getBin​(double x)
        The bin that x falls in
        Parameters:
        x - the data to check
        Returns:
        bin that x falls in
      • getBin

        public final Histogram.Bin getBin​(int binNum)
        Returns an instance of a Bin for the supplied bin number The bin does not reflect changes to the histogram after this call
        Parameters:
        binNum - the bin number to get
        Returns:
        the bin
      • getBins

        public final Histogram.Bin[] getBins()
        Returns an array of Bins based on the current state of the histogram
        Returns:
        the array of bins
      • getBinCount

        public final double getBinCount​(double x)
        Returns the current bin count for the bin associated with x
        Parameters:
        x - the data to check
        Returns:
        the bin count
      • getBinCount

        public final double getBinCount​(int binNum)
        Returns the bin count for the indicated bin
        Parameters:
        binNum - the bin number
        Returns:
        the bin count for the indicated bin
      • getBinFraction

        public final double getBinFraction​(int binNum)
        Returns the fraction of the data relative to those tabulated in the bins for the supplied bin number
        Parameters:
        binNum - the bin number
        Returns:
        the fraction of the data
      • getBinFraction

        public final double getBinFraction​(double x)
        Returns the fraction of the data relative to those tabulated in the bins for the bin number associated with the x
        Parameters:
        x - the data point
        Returns:
        the fraction
      • getCumulativeBinCount

        public final double getCumulativeBinCount​(double x)
        Returns the cumulative count of all bins up to and including the bin containing the value x
        Parameters:
        x - the data point
        Returns:
        the cumulative bin count
      • getCumulativeBinCount

        public final double getCumulativeBinCount​(int binNum)
        Returns the cumulative count of all the bins up to and including the indicated bin number
        Parameters:
        binNum - the bin number
        Returns:
        cumulative count
      • getCumulativeBinFraction

        public final double getCumulativeBinFraction​(int binNum)
        Returns the cumulatiive fraction of the data up to and including the indicated bin number
        Parameters:
        binNum - the bin number
        Returns:
        the cumulatiive fraction
      • getCumulativeBinFraction

        public final double getCumulativeBinFraction​(double x)
        Returns the cumulative fraction of the data up to and including the bin containing the value of x
        Parameters:
        x - the datum
        Returns:
        the cumulative fraction
      • getCumulativeCount

        public final double getCumulativeCount​(int binNum)
        Returns the cumulative count of all the data (including under flow and over flow) up to and including the indicated bin
        Parameters:
        binNum - the bin number
        Returns:
        the cumulative count
      • getCumulativeCount

        public final double getCumulativeCount​(double x)
        Returns the cumulative count of all the data (including under flow and over flow) for all bins up to and including the bin containing x
        Parameters:
        x - the datum
        Returns:
        the cumulative count
      • getCumulativeFraction

        public final double getCumulativeFraction​(int binNum)
        Returns the cumulative fraction of all the data up to and including the supplied bin (includes over and under flow)
        Parameters:
        binNum - the bin number
        Returns:
        the cumulative fraction
      • getCumulativeFraction

        public final double getCumulativeFraction​(double x)
        Returns the cumulative fraction of all the data up to an including the bin containing the value x, (includes over and under flow)
        Parameters:
        x - the datum
        Returns:
        the cumulative fraction
      • getTotalCount

        public final double getTotalCount()
        Total number of observations collected including overflow and underflow
        Returns:
        Total number of observations
      • getFirstBinLowerLimit

        public final double getFirstBinLowerLimit()
        The first bin's lower limit
        Returns:
        first bin's lower limit
      • getLastBinUpperLimit

        public final double getLastBinUpperLimit()
        The last bin's upper limit
        Returns:
        last bin's upper limit
      • toString

        public java.lang.String toString()
        Description copied from interface: StatisticAccessorIfc
        Returns a String representation of the Statistic
        Specified by:
        toString in interface StatisticAccessorIfc
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String with basic summary statistics
      • getAverage

        public final double getAverage()
        Description copied from interface: StatisticAccessorIfc
        Gets the unweighted average of the observations.
        Returns:
        A double representing the average or Double.NaN if no observations.
      • getCount

        public final double getCount()
        Description copied from interface: StatisticAccessorIfc
        Gets the count of the number of the observations.
        Returns:
        A double representing the count
      • getDeviationSumOfSquares

        public final double getDeviationSumOfSquares()
        Description copied from interface: StatisticAccessorIfc
        Gets the sum of squares of the deviations from the average This is the numerator in the classic sample variance formula
        Returns:
        A double representing the sum of squares of the deviations from the average
      • getHalfWidth

        public double getHalfWidth​(double alpha)
        Description copied from interface: StatisticAccessorIfc
        Gets the confidence interval half-width. Simply the generate standard error times the confidence coefficient as determined by an appropriate sampling distribution
        Parameters:
        alpha - the confidence level
        Returns:
        A double representing the half-width or Double.NaN if < 1 observation
      • getKurtosis

        public final double getKurtosis()
        Description copied from interface: StatisticAccessorIfc
        Gets the kurtosis of the data
        Returns:
        A double representing the kurtosis
      • getLag1Correlation

        public final double getLag1Correlation()
        Description copied from interface: StatisticAccessorIfc
        Gets the lag-1 generate correlation of the unweighted observations. Note: See Box, Jenkins, Reinsel, Time Series Analysis, 3rd edition, Prentice-Hall, pg 31
        Returns:
        A double representing the generate correlation or Double.NaN if <=2 observations
      • getLag1Covariance

        public final double getLag1Covariance()
        Description copied from interface: StatisticAccessorIfc
        Gets the lag-1 generate covariance of the unweighted observations. Note: See Box, Jenkins, Reinsel, Time Series Analysis, 3rd edition, Prentice-Hall, pg 31
        Returns:
        A double representing the generate covariance or Double.NaN if <=2 observations
      • getLastValue

        public final double getLastValue()
        Description copied from interface: StatisticAccessorIfc
        Gets the last observed data point
        Returns:
        A double representing the last observations
      • getMax

        public final double getMax()
        Description copied from interface: StatisticAccessorIfc
        Gets the maximum of the observations.
        Returns:
        A double representing the maximum
      • getMin

        public final double getMin()
        Description copied from interface: StatisticAccessorIfc
        Gets the minimum of the observations.
        Returns:
        A double representing the minimum
      • getObsWeightedSum

        public final double getObsWeightedSum()
        Returns the observation weighted sum of the data i.e. sum = sum + j*x where j is the observation number and x is jth observation
        Returns:
        the observation weighted sum of the data
      • getSkewness

        public final double getSkewness()
        Description copied from interface: StatisticAccessorIfc
        Gets the skewness of the data
        Returns:
        A double representing the skewness
      • getStandardDeviation

        public final double getStandardDeviation()
        Description copied from interface: StatisticAccessorIfc
        Gets the sample standard deviation of the observations. Simply the square root of getVariance()
        Returns:
        A double representing the generate standard deviation or Double.NaN if 1 or less observations.
      • getStandardError

        public final double getStandardError()
        Description copied from interface: StatisticAccessorIfc
        Gets the standard error of the observations. Simply the generate standard deviation divided by the square root of the number of observations
        Returns:
        A double representing the standard error or Double.NaN if < 1 observation
      • getSum

        public final double getSum()
        Description copied from interface: StatisticAccessorIfc
        Gets the sum of the observations.
        Returns:
        A double representing the unweighted sum
      • getVariance

        public final double getVariance()
        Description copied from interface: StatisticAccessorIfc
        Gets the sample variance of the observations.
        Returns:
        A double representing the generate variance or Double.NaN if 1 or less observations.
      • getVonNeumannLag1TestStatistic

        public final double getVonNeumannLag1TestStatistic()
        Description copied from interface: StatisticAccessorIfc
        Gets the Von Neumann Lag 1 test statistic for checking the hypothesis that the data are uncorrelated Note: See Handbook of Simulation, Jerry Banks editor, McGraw-Hill, pg 253.
        Returns:
        A double representing the Von Neumann test statistic
      • getVonNeumannLag1TestStatisticPValue

        public final double getVonNeumannLag1TestStatisticPValue()
        Description copied from interface: StatisticAccessorIfc
        Returns the asymptotic p-value for the Von Nueumann Lag-1 Test Statistic:

        Normal.stdNormalComplementaryCDF(getVonNeumannLag1TestStatistic());

        Returns:
        the p-value
      • getLeadingDigitRule

        public final int getLeadingDigitRule​(double a)
        Description copied from interface: StatisticAccessorIfc
        Computes the right most meaningful digit according to (int)Math.floor(Math.log10(a*getStandardError())) See doi 10.1287.opre.1080.0529 by Song and Schmeiser
        Parameters:
        a - the std error multiplier
        Returns:
        the meaningful digit
      • main

        public static void main​(java.lang.String[] args)