Package org.apache.commons.math3.stat

Class Frequency

  • All Implemented Interfaces:
    java.io.Serializable
    public class Frequency
extends java.lang.Object
implements java.io.Serializable
    Maintains a frequency distribution.

    Accepts int, long, char or Comparable values. New values added must be comparable to those that have been added, otherwise the add method will throw an IllegalArgumentException.

    Integer values (int, long, Integer, Long) are not distinguished by type -- i.e. addValue(Long.valueOf(2)), addValue(2), addValue(2l) all have the same effect (similarly for arguments to getCount, etc.).

    NOTE: byte and short values will be implicitly converted to int values by the compiler, thus there are no explicit overloaded methods for these primitive types.

    char values are converted by addValue to Character instances. As such, these values are not comparable to integral values, so attempts to combine integral types with chars in a frequency distribution will fail.

    Float is not coerced to Double. Since they are not Comparable with each other the user must do any necessary coercion. Float.NaN and Double.NaN are not treated specially; they may occur in input and will occur in output if appropriate.

    The values are ordered using the default (natural order), unless a Comparator is supplied in the constructor.

    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Frequency.NaturalComparator<T extends java.lang.Comparable<T>>
      A Comparator that compares comparable objects using the natural order.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.SortedMap<java.lang.Comparable<?>,​java.lang.Long> freqTable
      underlying collection
      private static long serialVersionUID
      Serializable version identifier

    • Constructor Summary

      Constructors 
      Constructor Description
      Frequency()
      Default constructor.
      Frequency​(java.util.Comparator<?> comparator)
      Constructor allowing values Comparator to be specified.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addValue​(char v)
      Adds 1 to the frequency count for v.
      void addValue​(int v)
      Adds 1 to the frequency count for v.
      void addValue​(long v)
      Adds 1 to the frequency count for v.
      void addValue​(java.lang.Comparable<?> v)
      Adds 1 to the frequency count for v.
      void clear()
      Clears the frequency table
      java.util.Iterator<java.util.Map.Entry<java.lang.Comparable<?>,​java.lang.Long>> entrySetIterator()
      Return an Iterator over the set of keys and values that have been added.
      boolean equals​(java.lang.Object obj)
      long getCount​(char v)
      Returns the number of values equal to v.
      long getCount​(int v)
      Returns the number of values equal to v.
      long getCount​(long v)
      Returns the number of values equal to v.
      long getCount​(java.lang.Comparable<?> v)
      Returns the number of values equal to v.
      long getCumFreq​(char v)
      Returns the cumulative frequency of values less than or equal to v.
      long getCumFreq​(int v)
      Returns the cumulative frequency of values less than or equal to v.
      long getCumFreq​(long v)
      Returns the cumulative frequency of values less than or equal to v.
      long getCumFreq​(java.lang.Comparable<?> v)
      Returns the cumulative frequency of values less than or equal to v.
      double getCumPct​(char v)
      Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).
      double getCumPct​(int v)
      Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).
      double getCumPct​(long v)
      Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).
      double getCumPct​(java.lang.Comparable<?> v)
      Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).
      java.util.List<java.lang.Comparable<?>> getMode()
      Returns the mode value(s) in comparator order.
      double getPct​(char v)
      Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
      double getPct​(int v)
      Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
      double getPct​(long v)
      Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
      double getPct​(java.lang.Comparable<?> v)
      Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
      long getSumFreq()
      Returns the sum of all frequencies.
      int getUniqueCount()
      Returns the number of values in the frequency table.
      int hashCode()
      void incrementValue​(char v, long increment)
      Increments the frequency count for v.
      void incrementValue​(int v, long increment)
      Increments the frequency count for v.
      void incrementValue​(long v, long increment)
      Increments the frequency count for v.
      void incrementValue​(java.lang.Comparable<?> v, long increment)
      Increments the frequency count for v.
      void merge​(java.util.Collection<Frequency> others)
      Merge a Collection of Frequency objects into this instance.
      void merge​(Frequency other)
      Merge another Frequency object's counts into this instance.
      java.lang.String toString()
      Return a string representation of this frequency distribution.
      java.util.Iterator<java.lang.Comparable<?>> valuesIterator()
      Returns an Iterator over the set of values that have been added.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serializable version identifier
        See Also:
        Constant Field Values

      • freqTable

        private final java.util.SortedMap<java.lang.Comparable<?>,​java.lang.Long> freqTable
        underlying collection

    • Constructor Detail

      • Frequency

        public Frequency()
        Default constructor.

      • Frequency

        public Frequency​(java.util.Comparator<?> comparator)
        Constructor allowing values Comparator to be specified.
        Parameters:
        comparator - Comparator used to order values

    • Method Detail

      • toString

        public java.lang.String toString()
        Return a string representation of this frequency distribution.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation.

      • addValue

        public void addValue​(java.lang.Comparable<?> v)
              throws MathIllegalArgumentException
        Adds 1 to the frequency count for v.

        If other objects have already been added to this Frequency, v must be comparable to those that have already been added.

        Parameters:
        v - the value to add.
        Throws:
        MathIllegalArgumentException - if v is not comparable with previous entries

      • incrementValue

        public void incrementValue​(java.lang.Comparable<?> v,
                           long increment)
                    throws MathIllegalArgumentException
        Increments the frequency count for v.

        If other objects have already been added to this Frequency, v must be comparable to those that have already been added.

        Parameters:
        v - the value to add.
        increment - the amount by which the value should be incremented
        Throws:
        MathIllegalArgumentException - if v is not comparable with previous entries
        Since:
        3.1

      • incrementValue

        public void incrementValue​(int v,
                           long increment)
                    throws MathIllegalArgumentException
        Increments the frequency count for v.

        If other objects have already been added to this Frequency, v must be comparable to those that have already been added.

        Parameters:
        v - the value to add.
        increment - the amount by which the value should be incremented
        Throws:
        MathIllegalArgumentException - if the table contains entries not comparable to Long
        Since:
        3.3

      • incrementValue

        public void incrementValue​(long v,
                           long increment)
                    throws MathIllegalArgumentException
        Increments the frequency count for v.

        If other objects have already been added to this Frequency, v must be comparable to those that have already been added.

        Parameters:
        v - the value to add.
        increment - the amount by which the value should be incremented
        Throws:
        MathIllegalArgumentException - if the table contains entries not comparable to Long
        Since:
        3.3

      • incrementValue

        public void incrementValue​(char v,
                           long increment)
                    throws MathIllegalArgumentException
        Increments the frequency count for v.

        If other objects have already been added to this Frequency, v must be comparable to those that have already been added.

        Parameters:
        v - the value to add.
        increment - the amount by which the value should be incremented
        Throws:
        MathIllegalArgumentException - if the table contains entries not comparable to Char
        Since:
        3.3

      • clear

        public void clear()
        Clears the frequency table

      • valuesIterator

        public java.util.Iterator<java.lang.Comparable<?>> valuesIterator()
        Returns an Iterator over the set of values that have been added.

        If added values are integral (i.e., integers, longs, Integers, or Longs), they are converted to Longs when they are added, so the objects returned by the Iterator will in this case be Longs.

        Returns:
        values Iterator

      • entrySetIterator

        public java.util.Iterator<java.util.Map.Entry<java.lang.Comparable<?>,​java.lang.Long>> entrySetIterator()
        Return an Iterator over the set of keys and values that have been added. Using the entry set to iterate is more efficient in the case where you need to access respective counts as well as values, since it doesn't require a "get" for every key...the value is provided in the Map.Entry.

        If added values are integral (i.e., integers, longs, Integers, or Longs), they are converted to Longs when they are added, so the values of the map entries returned by the Iterator will in this case be Longs.

        Returns:
        entry set Iterator
        Since:
        3.1

      • getSumFreq

        public long getSumFreq()
        Returns the sum of all frequencies.
        Returns:
        the total frequency count.

      • getCount

        public long getCount​(java.lang.Comparable<?> v)
        Returns the number of values equal to v. Returns 0 if the value is not comparable.
        Parameters:
        v - the value to lookup.
        Returns:
        the frequency of v.

      • getCount

        public long getCount​(int v)
        Returns the number of values equal to v.
        Parameters:
        v - the value to lookup.
        Returns:
        the frequency of v.

      • getCount

        public long getCount​(long v)
        Returns the number of values equal to v.
        Parameters:
        v - the value to lookup.
        Returns:
        the frequency of v.

      • getCount

        public long getCount​(char v)
        Returns the number of values equal to v.
        Parameters:
        v - the value to lookup.
        Returns:
        the frequency of v.

      • getUniqueCount

        public int getUniqueCount()
        Returns the number of values in the frequency table.
        Returns:
        the number of unique values that have been added to the frequency table.
        See Also:
        valuesIterator()

      • getPct

        public double getPct​(java.lang.Comparable<?> v)
        Returns the percentage of values that are equal to v (as a proportion between 0 and 1).

        Returns Double.NaN if no values have been added. Returns 0 if at least one value has been added, but v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getPct

        public double getPct​(int v)
        Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getPct

        public double getPct​(long v)
        Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getPct

        public double getPct​(char v)
        Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getCumFreq

        public long getCumFreq​(java.lang.Comparable<?> v)
        Returns the cumulative frequency of values less than or equal to v.

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup.
        Returns:
        the proportion of values equal to v

      • getCumFreq

        public long getCumFreq​(int v)
        Returns the cumulative frequency of values less than or equal to v.

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getCumFreq

        public long getCumFreq​(long v)
        Returns the cumulative frequency of values less than or equal to v.

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getCumFreq

        public long getCumFreq​(char v)
        Returns the cumulative frequency of values less than or equal to v.

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values equal to v

      • getCumPct

        public double getCumPct​(java.lang.Comparable<?> v)
        Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).

        Returns Double.NaN if no values have been added. Returns 0 if at least one value has been added, but v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values less than or equal to v

      • getCumPct

        public double getCumPct​(int v)
        Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values less than or equal to v

      • getCumPct

        public double getCumPct​(long v)
        Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values less than or equal to v

      • getCumPct

        public double getCumPct​(char v)
        Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).

        Returns 0 if v is not comparable to the values set.

        Parameters:
        v - the value to lookup
        Returns:
        the proportion of values less than or equal to v

      • getMode

        public java.util.List<java.lang.Comparable<?>> getMode()
        Returns the mode value(s) in comparator order.
        Returns:
        a list containing the value(s) which appear most often.
        Since:
        3.3

      • merge

        public void merge​(Frequency other)
           throws NullArgumentException
        Merge another Frequency object's counts into this instance. This Frequency's counts will be incremented (or set when not already set) by the counts represented by other.
        Parameters:
        other - the other Frequency object to be merged
        Throws:
        NullArgumentException - if other is null
        Since:
        3.1

      • merge

        public void merge​(java.util.Collection<Frequency> others)
           throws NullArgumentException
        Merge a Collection of Frequency objects into this instance. This Frequency's counts will be incremented (or set when not already set) by the counts represented by each of the others.
        Parameters:
        others - the other Frequency objects to be merged
        Throws:
        NullArgumentException - if the collection is null
        Since:
        3.1

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object