Histogram

java.lang.Object
- be.tarsos.util.histogram.Histogram

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

PitchClassHistogram, PitchHistogram
```
public class Histogram
extends java.lang.Object
implements java.lang.Cloneable
```
A histogram is defined by a start value, a stop value and a number of classes. The 'key' of a class is the middle of the class. E.g. the keys of a histogram that starts at 0, stops at 5 and has 5 classes are {0.5,1.5,2.5,3.5,4.5}. The intervals for each key are {[0,1[;[1,2[;[2,3[;[3,4];[4,5[} with [0,1[ meaning the interval between 0 inclusive and 1 exclusive.
The histogram uses a red and black tree as underlying structure: Search, insert and delete are O(LOG n). The tree keeps the keys in order and makes iteration (in order) easy. Optimization is possible by replacing the tree with arrays.

The histogram uses doubles as key values. Java doubles are prone to rounding errors. To prevent rounding errors the keys are rounded to a predefined number of decimals. The number can be found in PRECISION_FACTOR. E.g. if PRECISION_FACTOR is 10000 then the number of significant decimals is 4; the minimum classWidth is 0.0001.

Author:

Joren Six

Constructor Summary

Constructors
Constructor and Description
`Histogram(double startVal, double stopVal, int totalClasses)` Create a Histogram with a certain number of classes with values in the range `]start - classWidht / 2, stop + classWidth / 2 [` if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
`Histogram(double startVal, double stopVal, int totalClasses, boolean wrapping)` Create a Histogram with a certain number of classes with values in the range `]start - classWidht / 2, stop + classWidth / 2 [` if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
`Histogram(double startVal, double stopVal, int totalClasses, boolean wrapping, boolean ignoreOutsideRange)` Create a Histogram with a certain number of classes with values in the range `]start - classWidht / 2, stop + classWidth / 2 [` if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
`Histogram(Histogram original)` Creates a new, empty histogram using the same parameters of the original histogram.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Histogram`	`add(double value)` Adds a value to the Histogram.
`Histogram`	`add(Histogram other)` Calculates the sum of two histograms.
`Histogram`	`add(Histogram other, int offset)` Calculates the sum of two histograms.
`Histogram`	`addToEachBin(long value)` Adds a number of items to each bin.
`Histogram`	`baselineHistogram()` Searches the minimum number of items in a bin and subtracts all bins with this value.
`void`	`clear()` Sets each bin to 0.
`Histogram`	`clone()`
`double`	`correlation(Histogram otherHistogram)` Return the correlation of this histogram with another one.
`double`	`correlation(Histogram otherHistogram, CorrelationMeasure correlationMeasure)` Return the correlation of this histogram with another one.
`double`	`correlationWithDisplacement(int displacement, Histogram otherHistogram)`
`double`	`correlationWithDisplacement(int displacement, Histogram otherHistogram, CorrelationMeasure correlationMeasure)`
`void`	`displace(int displacement)`
`int`	`displacementForOptimalCorrelation(Histogram otherHistogram)`
`int`	`displacementForOptimalCorrelation(Histogram otherHistogram, CorrelationMeasure correlationMeasure)` Returns the number of classes the other histogram needs to be displaced to get optimal correlation with this histogram.
`void`	`export(java.lang.String fileName)` Export the histogram data as a plain text file.
`void`	`exportMatLab(java.lang.String fileName)` Export the histogram data as a matlab text file.
`Histogram`	`gaussianSmooth(double standardDeviation)` Smooth the histogram using Gaussians.
`long`	`getAbsoluteSumFreq()` Returns the sum of all frequencies.
`double`	`getClassWidth()`
`long`	`getCount(double value)` Returns the number of values = v.
`long`	`getCountForClass(int i)` Returns the number of items in class with index bufferCount.
`long`	`getCumFreq(java.lang.Double v)` Returns the cumulative frequency of values less than or equal to v.
`double`	`getCumPct(java.lang.Double v)` Returns the cumulative percentage of values less than or equal to v (as a proportion between 0 and 1).
`double`	`getEntropy()` Returns the entropy of the histogram.
`double`	`getKeyForClass(int i)` Returns the key for class with index bufferCount.
`long`	`getMaxBinCount()`
`double`	`getMean()` Calculates the mean count of each bin.
`double`	`getMedian()` Calculates the mean count of each bin.
`int`	`getNumberOfClasses()`
`double`	`getPct(java.lang.Double v)` Returns the percentage of values that are equal to v (as a proportion between 0 and 1).
`double`	`getStart()` The starting value is not the same as the first key.
`double`	`getStop()` The stopping value is not the same as the last key.
`long`	`getSumFreq()` Returns the sum of all frequencies (bin counts).
`Histogram`	`invert()` Inverts this histograms.
`boolean`	`isWrapped()`
`java.util.Set<java.lang.Double>`	`keySet()`
`Histogram`	`max(Histogram other)` Takes the maximum of the bin value in each histogram and changes the current histogram to this maximum value.
`static Histogram`	`mean(java.util.List<Histogram> histograms)` Calculates a histogram mean of a list of histograms.
`Histogram`	`multiply(double factor)` Multiplies each class (bin) count with a factor.
`Histogram`	`normalize()` Normalizes the peaks in a histogram.
`Histogram`	`raise(double exponent)` Raises each class count to the power of exponent.
`void`	`setCount(double value, long count)` Sets the number of values for a key (bin) The value is automatically mapped to a key.
`Histogram`	`smooth(boolean isWeighted, int k)` Computes a smoothed version of the histogram.
`Histogram`	`subtract(Histogram other)` Subtracts two histograms.
`java.lang.String`	`toString()` Return a string representation of this histogram.
`java.lang.String`	`toString(boolean asciiArt)` Returns a string representation of the histogram.
`protected void`	`valueAddedHook(double value)` A hook to intercept added values.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Histogram
```
public Histogram(double startVal,
                 double stopVal,
                 int totalClasses,
                 boolean wrapping,
                 boolean ignoreOutsideRange)
```
    Create a Histogram with a certain number of classes with values in the range ]start - classWidht / 2, stop + classWidth / 2 [ if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
    
    Parameters:
    
    startVal - the starting value of the histogram. The starting value is not the same as the first class middle. The starting value is equal to the first class middle - classWidth / 2
    
    stopVal - the stopping value of the histogram. The stopping value is not the same as the last class middle. The stopping value is equal to the last class middle + classWidth / 2
    
    totalClasses - the number of classes between the starting and stopping values. Also defines the classWidth.
    
    wrapping - indicates if the histogram wraps around the edges. More formal: If the histogram wraps values outside the range ]start - classWidht / 2, stop + classWidth / 2 [ are mapped to values inside the range using a modulo calculation.
    
    ignoreOutsideRange - if true values outside the valid range are ignored. Otherwise if a value outside the valid range is added an IllegalArgumentException is thrown.
  - Histogram
```
public Histogram(Histogram original)
```
    Creates a new, empty histogram using the same parameters of the original histogram. The parameter being start, wraps and stop and number of classes.
    
    Parameters:
    
    original - the original histogram
  - Histogram
```
public Histogram(double startVal,
                 double stopVal,
                 int totalClasses)
```
    Create a Histogram with a certain number of classes with values in the range ]start - classWidht / 2, stop + classWidth / 2 [ if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
    
    Parameters:
    
    startVal - the starting value of the histogram. The starting value is not the same as the first class middle. The starting value is equal to the first class middle - classWidth / 2
    
    stopVal - the stopping value of the histogram. The stopping value is not the same as the last class middle. The stopping value is equal to the last class middle + classWidth / 2
    
    totalClasses - the number of classes between the starting and stopping values. Also defines the classWidth.
  - Histogram
```
public Histogram(double startVal,
                 double stopVal,
                 int totalClasses,
                 boolean wrapping)
```
    Create a Histogram with a certain number of classes with values in the range ]start - classWidht / 2, stop + classWidth / 2 [ if the histogram wraps otherwise values outside the range are mapped to values inside using a modulo calculation.
    
    Parameters:
    
    startVal - the starting value of the histogram. The starting value is not the same as the first class middle. The starting value is equal to the first class middle - classWidth / 2
    
    stopVal - the stopping value of the histogram. The stopping value is not the same as the last class middle. The stopping value is equal to the last class middle + classWidth / 2
    
    totalClasses - the number of classes between the starting and stopping values. Also defines the classWidth.
    
    wrapping - indicates if the histogram wraps around the edges. More formal: If the histogram wraps values outside the range ]start - classWidht / 2, stop + classWidth / 2 [ are mapped to values inside the range using a modulo calculation.
- Method Detail
  - getKeyForClass
```
public final double getKeyForClass(int i)
```
    Returns the key for class with index bufferCount.
    
    Parameters:
    
    i - a class index. If bufferCount lays outside the interval [0,getNumberOfClasses()[ it is mapped to a value inside the interval using a modulo calculation.
    
    Returns:
    
    the key for class with index bufferCount
  - getCountForClass
```
public final long getCountForClass(int i)
```
    Returns the number of items in class with index bufferCount.
    
    Parameters:
    
    i - A class index. If bufferCount lays outside the interval [0,getNumberOfClasses()[ it is mapped to a value inside the interval using a modulo calculation.
    
    Returns:
    
    the number of items in bin with index bufferCount
  - keySet
```
public final java.util.Set<java.lang.Double> keySet()
```
    Returns:
    
    the set with histogram keys; Do not add keys to the set directly. Use histogram methods instead. For performance reasons it is not wrapped in an immutable set so handle with care.
  - add
```
public final Histogram add(double value)
```
    Adds a value to the Histogram. Assigns the value to the right bin automatically.
    
    Parameters:
    
    value - The value to add.
    
    Returns:
    
    This histogram with the added value.
    
    Throws:
    
    java.lang.IllegalArgumentException - when the value is not in the range of the histogram.
  - valueAddedHook
```
protected void valueAddedHook(double value)
```
    A hook to intercept added values.
    
    Parameters:
    
    value - The value added
  - getCount
```
public final long getCount(double value)
```
    Returns the number of values = v.
    
    Parameters:
    
    value - the value to lookup.
    
    Returns:
    
    the frequency of v.
  - setCount
```
public final void setCount(double value,
                           long count)
```
    Sets the number of values for a key (bin) The value is automatically mapped to a key.
    
    Parameters:
    
    value - the value mapped to a key of the class to set the count for.
    
    count - the number of items in the bin
  - getClassWidth
```
public final double getClassWidth()
```
    Returns:
    
    the width of a class (bin)
  - getNumberOfClasses
```
public final int getNumberOfClasses()
```
    Returns:
    
    the number of classes
  - getStart
```
public final double getStart()
```
    The starting value is not the same as the first key. It is equal to firstKey - classWidth / 2.0
    
    Returns:
    
    the starting value
  - getStop
```
public double getStop()
```
    The stopping value is not the same as the last key. It is equal to lastKey + classWidth / 2.0
    
    Returns:
    
    the stop value
  - isWrapped
```
public boolean isWrapped()
```
    Returns:
    
    true if values outside the interval are wrapped, false otherwise.
  - getCumFreq
```
public long getCumFreq(java.lang.Double v)
```
    Returns the cumulative frequency of values less than or equal to v.
    Returns 0 if v is not comparable to the values set.
    
    Uses code from Apache Commons Math" licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
    
    Parameters:
    
    v - the value to lookup.
    
    Returns:
    
    the proportion of values equal to v
  - getCumPct
```
public double getCumPct(java.lang.Double 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.
    
    Parameters:
    
    v - the value to lookup
    
    Returns:
    
    the proportion of values less than or equal to v
  - getSumFreq
```
public long getSumFreq()
```
    Returns the sum of all frequencies (bin counts). If there are negative bin counts the sum is smaller than getAbsoluteSumFreq()
    
    Returns:
    
    the total frequency count.
  - getAbsoluteSumFreq
```
public long getAbsoluteSumFreq()
```
    Returns the sum of all frequencies. The absolute values of the bin counts are used.
    
    Returns:
    
    the total frequency count.
  - getPct
```
public double getPct(java.lang.Double 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.
    
    Parameters:
    
    v - the value to lookup
    
    Returns:
    
    the proportion of values equal to v
  - getEntropy
```
public double getEntropy()
```
    Returns the entropy of the histogram.
    The histogram entropy is defined to be the negation of the sum of the products of the probability associated with each bin with the base-2 LOG of the probability.
    
    Uses code from https://jai-core.dev.java.net/ The source code for the core Java Advanced Imaging API reference implementation is licensed under the Java Research License (JRL) for non-commercial use. The JRL allows users to download, build, and modify the source code in the jai-core project for research use, subject to the terms of the license.
    
    Returns:
    
    The entropy of the histogram.
  - getMean
```
public double getMean()
```
    Calculates the mean count of each bin. It iterates over each bin, stores the bin count temporarily and returns the mean bin count. It does not cache the result.
    
    Returns:
    
    the mean bin count.
  - getMedian
```
public double getMedian()
```
    Calculates the mean count of each bin. It iterates over each bin, stores the bin count temporarily and returns the mean bin count. It does not cache the result.
    
    Returns:
    
    the mean bin count.
  - toString
```
public java.lang.String toString()
```
    Return a string representation of this histogram.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a string representation.
  - toString
```
public java.lang.String toString(boolean asciiArt)
```
    Returns a string representation of the histogram.
    Uses code from Apache Commons Math" licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
    
    Parameters:
    
    asciiArt - If true it generates an ascii representation of a histogram, otherwise it generates a frequency table
    
    Returns:
    
    a string representation.
  - normalize
```
public Histogram normalize()
```
    Normalizes the peaks in a histogram. Every peak is reduced to it's relative weight (percent).
    Changes the current histogram and returns it so it is possible to chain modifications. E.g. histo.normalize().addToEachBin(10)
    
    Returns:
    
    a Histogram with normalized peak.
  - addToEachBin
```
public Histogram addToEachBin(long value)
```
    Adds a number of items to each bin. Use a negative number to subtract a value from each bin.
    Changes the current histogram and returns it so it is possible to chain modifications. E.g. histo.normalize().addToEachBin(10)
    
    Parameters:
    
    value - the number of items to add.
    
    Returns:
    
    returns the current histogram so it is possible to chain modifications.
  - baselineHistogram
```
public Histogram baselineHistogram()
```
    Searches the minimum number of items in a bin and subtracts all bins with this value.
```
 *
 * *              *
 * *   *          * *
 * * * *    =>    * *   *
 -------          -------
 
```
    Changes the current histogram and returns it so it is possible to chain modifications. E.g. histo.normalize().addToEachBin(10)
    Returns:
    
    a baselined histogram
  - add
```
public Histogram add(Histogram other)
```
    Calculates the sum of two histograms. The value for each bin of other is added to the corresponding bin of this histogram. The other histogram must have the same start, stop and binWidth otherwise adding histograms makes no sense!
    Changes the current histogram and returns it so it is possible to chain modifications. E.g.histo.normalize().addToEachBin(10)
    
    Parameters:
    
    other - The other histogram
    
    Returns:
    
    the changed histogram with more (or the same) number of items in the bins.
  - add
```
public Histogram add(Histogram other,
                     int offset)
```
    Calculates the sum of two histograms. The value for each bin of other is added to the corresponding bin of this histogram. The other histogram must have the same start, stop and binWidth otherwise adding histograms makes no sense!
    Changes the current histogram and returns it so it is possible to chain modifications. E.g.histo.normalize().addToEachBin(10)
    
    Parameters:
    
    other - The other histogram
    
    offset - The offset.
    
    Returns:
    
    the changed histogram with more (or the same) number of items in the bins.
  - max
```
public Histogram max(Histogram other)
```
    Takes the maximum of the bin value in each histogram and changes the current histogram to this maximum value.
    
    Parameters:
    
    other - Another histogram with the same number of bins.
    
    Returns:
    
    A histogram with the maximum values. It is the changed current histogram, not a new one.
  - subtract
```
public Histogram subtract(Histogram other)
```
    Subtracts two histograms. The value for each bin of other is removed to the corresponding bin of this histogram. The other histogram must have the same start, stop and binWidth otherwise subtracting histograms makes no sense!
    Changes the current histogram and returns it so it is possible to chain modifications. E.g.histo.normalize().addToEachBin(10)
    
    Parameters:
    
    other - The other histogram
    
    Returns:
    
    The changed histogram with less (or the same) number of items in the bins.
  - invert
```
public Histogram invert()
```
    Inverts this histograms. The value for each bin is multiplied with -1.
    Changes the current histogram and returns it so it is possible to chain modifications. E.g.histo.normalize().addToEachBin(10)
    
    Returns:
    
    The changed histogram with each bin multiplied with -1.
  - multiply
```
public Histogram multiply(double factor)
```
    Multiplies each class (bin) count with a factor.
    Changes the current histogram and returns it so it is possible to chain modifications. E.g. histo.normalize().addToEachBin(10)
    
    Parameters:
    
    factor - the factor to multiply each bin value with.
    
    Returns:
    
    histogram with each bin value multiplied by the factor.
  - raise
```
public Histogram raise(double exponent)
```
    Raises each class count to the power of exponent.
    Changes the current histogram and returns it so it is possible to chain modifications. E.g. histo.normalize().addToEachBin(10)
    
    Parameters:
    
    exponent - The exponent to raise each bincount with.
    
    Returns:
    
    Histogram with each bin count raised with exponent.
  - clone
```
public Histogram clone()
                throws java.lang.CloneNotSupportedException
```
    Overrides:
    
    clone in class java.lang.Object
    
    Throws:
    
    java.lang.CloneNotSupportedException
  - mean
```
public static Histogram mean(java.util.List<Histogram> histograms)
```
    Calculates a histogram mean of a list of histograms. All histograms must have the same start, stop and binWidth otherwise the mean histogram makes no sense!
    
    Parameters:
    
    histograms - a list of histograms
    
    Returns:
    
    a histogram with the mean values. If the list is empty it returns null.
  - smooth
```
public Histogram smooth(boolean isWeighted,
                        int k)
```
    Computes a smoothed version of the histogram.
    The histogram is smoothed by averaging over a moving window of a size specified by the method parameter: if the value of the parameter is k then the width of the window is 2*k + 1. If the window runs off the end of the histogram only those values which intersect the histogram are taken into consideration. The smoothing may optionally be weighted to favor the central value using a "triangular" weighting. For example, for a value of k equal to 2 the central bin would have weight 1/3, the adjacent bins 2/9, and the next adjacent bins 1/9.
    Changes the current histogram and returns it so it is possible to chain modification e.g. histo.normalize().addToEachBin(10)
    
    Uses code from https://jai-core.dev.java.net/ The source code for the core Java Advanced Imaging API reference implementation is licensed under the Java Research License (JRL) for non-commercial use. The JRL allows users to download, build, and modify the source code in the jai-core project for research use, subject to the terms of the license.
    
    Parameters:
    
    isWeighted - Whether bins will be weighted using a triangular weighting scheme favoring bins near the central bin.
    
    k - The smoothing parameter which must be non-negative or an IllegalArgumentException will be thrown. If zero, the histogram object will be returned with no smoothing applied.
    
    Returns:
    
    A smoothed version of the histogram.
  - gaussianSmooth
```
public Histogram gaussianSmooth(double standardDeviation)
```
    Smooth the histogram using Gaussians.
    Each band of the histogram is smoothed by discrete convolution with a kernel approximating a Gaussian impulse response with the specified standard deviation.
    Changes the current histogram and returns it so it is possible to chain modification e.g. histo.normalize().addToEachBin(10)
    
    Uses code from https://jai-core.dev.java.net/ The source code for the core Java Advanced Imaging API reference implementation is licensed under the Java Research License (JRL) for non-commercial use. The JRL allows users to download, build, and modify the source code in the JAI-core project for research use, subject to the terms of the license.
    
    Parameters:
    
    standardDeviation - The standard deviation of the Gaussian smoothing kernel which must be non-negative or an IllegalArgumentException will be thrown. If zero, the histogram object will be returned with no smoothing applied.
    
    Returns:
    
    A Gaussian smoothed version of the histogram.
  - displacementForOptimalCorrelation
```
public int displacementForOptimalCorrelation(Histogram otherHistogram)
```
  - displace
```
public void displace(int displacement)
```
  - correlationWithDisplacement
```
public double correlationWithDisplacement(int displacement,
                                          Histogram otherHistogram,
                                          CorrelationMeasure correlationMeasure)
```
  - correlationWithDisplacement
```
public double correlationWithDisplacement(int displacement,
                                          Histogram otherHistogram)
```
  - correlation
```
public double correlation(Histogram otherHistogram,
                          CorrelationMeasure correlationMeasure)
```
    Return the correlation of this histogram with another one.
    
    Parameters:
    
    otherHistogram -
    
    correlationMeasure -
    
    Returns:
    
    the correlation between this histogram with another histogram.
  - correlation
```
public double correlation(Histogram otherHistogram)
```
    Return the correlation of this histogram with another one. By default it uses the INTERSECTION correlation measure.
    
    Parameters:
    
    otherHistogram - the other histogram
    
    Returns:
    
    the correlation the computed correlation
  - displacementForOptimalCorrelation
```
public int displacementForOptimalCorrelation(Histogram otherHistogram,
                                             CorrelationMeasure correlationMeasure)
```
    Returns the number of classes the other histogram needs to be displaced to get optimal correlation with this histogram. The correlation is defined by the chosen correlation measure.
    
    Parameters:
    
    otherHistogram - The other histogram.
    
    correlationMeasure - The correlation strategy.
    
    Returns:
    
    Returns the number of classes the other histogram needs to be displaced to get optimal correlation with this histogram.
  - export
```
public final void export(java.lang.String fileName)
```
    Export the histogram data as a plain text file. The format uses ; to separate keys from values.
    
    Parameters:
    
    fileName - Where to save the text file.
  - exportMatLab
```
public final void exportMatLab(java.lang.String fileName)
```
    Export the histogram data as a matlab text file. The format can be read using octave or MatLab.
    
    Parameters:
    
    fileName - Where to save the matlab (.m) file.
  - getMaxBinCount
```
public final long getMaxBinCount()
```
    Returns:
    
    The maximum bin count.
  - clear
```
public void clear()
```
    Sets each bin to 0.

Class Histogram

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Histogram

Histogram

Histogram

Histogram

Method Detail

getKeyForClass

getCountForClass

keySet

add

valueAddedHook

getCount

setCount

getClassWidth

getNumberOfClasses

getStart

getStop

isWrapped

getCumFreq

getCumPct

getSumFreq

getAbsoluteSumFreq

getPct

getEntropy

getMean

getMedian

toString

toString

normalize

addToEachBin

baselineHistogram

add

add

max

subtract

invert

multiply

raise

clone

mean

smooth

gaussianSmooth

displacementForOptimalCorrelation

displace

correlationWithDisplacement

correlationWithDisplacement

correlation

correlation

displacementForOptimalCorrelation

export

exportMatLab

getMaxBinCount

clear