Package net.algart.arrays

Class SummingHistogram

java.lang.Object
net.algart.arrays.Histogram
net.algart.arrays.SummingHistogram
public abstract class SummingHistogram extends Histogram

Summing histogram: an extension of Histogram class, allowing quick calculation of sums of all elements of the sorted source array A[k] with indexes, lying in some range r1≤k≤r2, or with values, lying in some range v1≤A[k]≤v2.

This class is an inheritor of Histogram class, so any summing histogram is also a usual histogram: an array of non-negative integer numbers b[v], 0≤v<M, where every element b[v] represents the number of occurrence of the value v in some source array A, consisting of integer elements in 0..M−1 range. As in Histogram class, the integer values v in the source array are 31-bit: 0≤M<231, the bars of the histogram b[v] and their sum N are 63-bit: 0≤N<263, and the source array A is always supposed to be sorted in increasing order: A[0]≤A[1]≤...≤A[N−1], where N=b[0]+b[1]+...+b[M−1] is the number of elements in A.

The difference from usual histograms is that this class implement several additional methods, which allow efficient solving two additional tasks. Namely, in addition to (1) finding the percentile v(r) and (2) finding the rank r(v) (see the beginning of the comment to the Histogram class), this class provide efficient solution of the following tasks:

  1. to find the sum Z(r) = Σ 0≤k<rA[k] of r first elements of the sorted source array A[k], if we know the index r in this array;
  2. to find the sum z(v) = Σ A[k]<vA[k] = Σ 0≤j<vj*b[j] of all elements of the source array A, less then the given value v.

Obviously, it allows to find the sum of all elements lying in a range of indexes in the sorted source array r1≤r≤r2: it is Z(r2)−Z(r1), or in a range of values of the elements in the source array v1≤v≤v2: it is it is z(v2)−z(v1).

Like Histogram, this class does not store and does not try to sort the source array A, it stores only the histogram b and solves all tasks on the base of it. The price of the additional features is less performance: the methods of this class work little slower than the methods of more simple Histogram class.

Like Histogram, this class generalizes the concept of sum of elements to the floating-point case. Below is the formal definition of the real S and s functions, calculated by this class.

Definition of floating-point summing functions S(r) and s(v)

Let b[0..M−1] be an array of non-negative integer numbers, called the histogram (and stored by this class), and let N be the sum of all these elements (the length of the supposed, but not stored source sorted array A). Let v(r), 0.0≤r≤N, and r(v), 0.0≤v≤M, are the percentile and the rank real functions, formally defined in the comments to Histogram class.

This class allow to calculate two additional real functions: S(r), where r is a real number in range 0.0≤r≤N, and s(v), where v is a real number in range 0.0≤v≤M. Like v(r) and r(v), the S(r) and s(v) functions are different in different histogram models: simple and precise (see comments to Histogram class). Namely, these functions are defined via the following definite integrals:

Simple histogram model

Generalization of Z(r), which is an sum of elements A[r] with integer indexes, to the real function S(r) is very simple: we use a definite integral of the function v(r) with a real argument. After this, we just define s(v) as S(r(v)).

  1. S(r) = ∫0≤x≤r v(x) dx;
  2. s(v) = S(r(v)) = ∫0≤x≤r(v) v(x) dx.
    Note: according this definition, s(v)=S(0)=0 when v<v(0) and s(v)=S(N) when v>v(N).

In the simple histogram model, there is a simple relation between s(v) function and the more simple concept of z(v) sum, defined above in integer terms. Namely, if v0 is integer, then

s(v0) = Σ 0≤j<v0(j+0.5)*b[j] = z(v0) + r(v0)/2
Precise histogram model

In this case, the behaviour of v(r) and r(v) is more complicated and calculating the integral is little more difficult. To allow this class optimization of algorithms, we little change the definition of S(r) and s(v). Namely, in the precise histogram model, these functions also depend on some constant C, the value of which is undocumented and can be chosen by this class to provide the maximal performance:

  1. S(r) = C + ∫0≤x≤r v(x) dx, where C is some constant, the value of which is undocumented;
  2. s(v) = S(r(v)) = C + ∫0≤x≤r(v) v(x) dx.
    Note: according this definition, s(v)=S(0)=C when v<v(0) and s(v)=S(N) when v>v(N).

Though this definition includes some unknown constant C, is is not important if you need to calculate the difference S(r2)−S(r1) or s(v2)−s(v1): such differences do not contain C constant. If you really need to calculate the integral from the right sides of the formulas above, you can calculate it as S(r)−S(0) or s(v)−s(0).

The value of the constant C depends on the histogram bars b[k]: in this class, for example, it can vary when you add or remove elements by include / exclude methods.

Like Histogram, this class is optimized for the case, when we already know some corresponding pair r (rank) and v (percentile), and we need to slightly change the situation: add or remove several A elements, increase or decrease the known rank r or the value v. But in addition to the current value v, current simple rank rS and current precise rank rP, this class supports two new parameters:

  • the current simple integral SS = S(rS), where rS is the current simple rank and S(r) function is defined in terms of the simple histogram model; this integral can be got by currentIntegral() method;
  • the current precise integral SP = S(rP), where rP is the current precise rank and S(r) function is defined in terms of the precise histogram model; this integral can be got by currentPreciseIntegral() method.

Unlike v, rS and rP, which can be set and read, the SS and SP parameters are read-only: they can be only read according the current values of v, rS and rP.

If you want to get the simple sum of elements of the source A array in integer terms, you also can use currentSum() method, which just returns z(v0) = Σ 0≤j<v0j*b[j] for integer v0=currentIValue().

You can create an instance of this class by the following methods:

This class is often used for calculating differences S(r2)−S(r1) or s(v2)−s(v1), when we need to recalculate the difference after little changes of the histogram and of each from two ranks r1, r2 or two values v1, v2. In this situation, it is convenient to share the histogram between two instances of this object and set the 1nd necessary rank r1 (or value v1) in the 1st instance and the 2nd necessary rank r2 (or value v2) in the 2nd instance. The difference between currentIntegral() or currentPreciseIntegral(), calculated in two instances, will contain the necessary result. Because this situation is often enough, there are special methods currentIntegralBetweenSharing() and currentPreciseIntegralBetweenSharing() for this task.

This class also provides static methods for calculating S(r2)−S(r1) or s(v2)−s(v1) differences: correspondingly integralBetweenRanks(long[], double, double) / integralBetweenRanks(int[], double, double) and integralBetweenValues(long[], double, double, CountOfValues) / integralBetweenValues(int[], double, double, CountOfValues) for the simple histogram model, preciseIntegralBetweenRanks(long[], double, double) / preciseIntegralBetweenRanks(int[], double, double) and preciseIntegralBetweenValues(long[], double, double, CountOfValues) / preciseIntegralBetweenValues(int[], double, double, CountOfValues) for the precise histogram model. These methods can be useful if you need to process the given histogram only once.

There is no guarantee that the same results, got by different ways (for example, by static methods and by creating an instance of this class and using its methods) are absolutely identical: little mismatches in the last digits after the decimal point are possible.

This class does not implement own equals and hashCode methods. So, this class does not provide a mechanism for comparing different histograms.

This class is not thread-safe, but is thread-compatible and can be synchronized manually, if multithread access is necessary.

Author:
Daniel Alievsky

  • Method Details

    • newSummingLongHistogram

      public static SummingHistogram newSummingLongHistogram(int histogramLength, int... bitLevelsOfPyramid)
      Equivalent to newSummingLongHistogram(histogramLength, false, bitLevelsOfPyramid).
      Parameters:
      histogramLength - the number M of bars of the new histogram.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new summing histogram with zero (empty) bars b[k]=0.
      Throws:
      NullPointerException - if bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if histogramLength<0, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingLongHistogram

      public static SummingHistogram newSummingLongHistogram(int histogramLength, boolean optimizeSimpleIntegral, int... bitLevelsOfPyramid)
      Creates new histogram, consisting of M=histogramLength empty bars. It is an analog of Histogram.newLongHistogram(int, int...) method; the only difference is that this method creates an instance of SummingHistogram class.

      The optimizeSimpleIntegral argument allows to provide maximal performance if you are going to use the created instance for calculating only the simple current integral SS and do not need to calculate the precise integral SP (see the comments to this class). Namely, if this argument is false, this class provides good performance for calculating both integrals: all methods of this class usually require O(1) operations. If it is true, then include, exclude and all moveTo... methods will work rather more quickly, because they will not recalculate some internal invariants necessary for calculating the current precise integral SP. But, as a result, the methods currentPreciseIntegral() and currentPreciseIntegralBetweenSharing(), calculating SP, and also currentNumberOfDifferentValues() method will work more slowly. Namely, they can require O(M) operations, even in a case of using the histogram pyramid (see comments to bitLevelsOfPyramid argument in Histogram.newLongHistogram(int, int...) method).

      Parameters:
      histogramLength - the number M of bars of the new histogram.
      optimizeSimpleIntegral - whether the created instance should be optimized for calculating the current simple integral SS.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new summing histogram with zero (empty) bars b[k]=0.
      Throws:
      NullPointerException - if bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if histogramLength<0, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingLongHistogram

      public static SummingHistogram newSummingLongHistogram(long[] histogram, int... bitLevelsOfPyramid)
      Equivalent to newSummingLongHistogram(histogram, false, bitLevelsOfPyramid).
      Parameters:
      histogram - initial values of the bars b[k] of the histogram.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new histogram with bars b[k]=histogram[k].
      Throws:
      NullPointerException - if histogram or bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if some of histogram elements are negative (<0), or if sum of all bars (elements of histogram array) is greater than Long.MAX_VALUE, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingLongHistogram

      public static SummingHistogram newSummingLongHistogram(long[] histogram, boolean optimizeSimpleIntegral, int... bitLevelsOfPyramid)
      Creates new histogram, consisting of M=histogram.length bars, equal to elements of the given array. It is an analog of Histogram.newLongHistogram(long[], int...) method; the only difference is that this method creates an instance of SummingHistogram class.

      The optimizeSimpleIntegral argument allows to provide maximal performance if you are going to use the created instance for calculating only the simple current integral SS and do not need to calculate the precise integral SP (see the comments to this class). Namely, if this argument is false, this class provides good performance for calculating both integrals: all methods of this class usually require O(1) operations. If it is true, then include, exclude and all moveTo... methods will work rather more quickly, because they will not recalculate some internal invariants necessary for calculating the current precise integral SP. But, as a result, the methods currentPreciseIntegral() and currentPreciseIntegralBetweenSharing(), calculating SP, and also currentNumberOfDifferentValues() method will work more slowly. Namely, they can require O(M) operations, even in a case of using the histogram pyramid (see comments to bitLevelsOfPyramid argument in Histogram.newLongHistogram(long[], int...) method).

      Parameters:
      histogram - initial values of the bars b[k] of the histogram.
      optimizeSimpleIntegral - whether the created instance should be optimized for calculating the current simple integral SS.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new histogram with bars b[k]=histogram[k].
      Throws:
      NullPointerException - if histogram or bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if some of histogram elements are negative (<0), or if sum of all bars (elements of histogram array) is greater than Long.MAX_VALUE, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingIntHistogram

      public static SummingHistogram newSummingIntHistogram(int histogramLength, int... bitLevelsOfPyramid)
      Equivalent to newSummingIntHistogram(histogramLength, false, bitLevelsOfPyramid).
      Parameters:
      histogramLength - the number M of bars of the new histogram.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new summing histogram with zero (empty) bars b[k]=0.
      Throws:
      NullPointerException - if bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if histogramLength<0, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingIntHistogram

      public static SummingHistogram newSummingIntHistogram(int histogramLength, boolean optimizeSimpleIntegral, int... bitLevelsOfPyramid)
      Creates new histogram, consisting of M=histogramLength empty bars. It is an analog of Histogram.newIntHistogram(int, int...) method; the only difference is that this method creates an instance of SummingHistogram class.

      The optimizeSimpleIntegral argument allows to provide maximal performance if you are going to use the created instance for calculating only the simple current integral SS and do not need to calculate the precise integral SP (see the comments to this class). Namely, if this argument is false, this class provides good performance for calculating both integrals: all methods of this class usually require O(1) operations. If it is true, then include, exclude and all moveTo... methods will work rather more quickly, because they will not recalculate some internal invariants necessary for calculating the current precise integral SP. But, as a result, the methods currentPreciseIntegral() and currentPreciseIntegralBetweenSharing(), calculating SP, and also currentNumberOfDifferentValues() method will work more slowly. Namely, they can require O(M) operations, even in a case of using the histogram pyramid (see comments to bitLevelsOfPyramid argument in Histogram.newIntHistogram(int, int...) method).

      Parameters:
      histogramLength - the number M of bars of the new histogram.
      optimizeSimpleIntegral - whether the created instance should be optimized for calculating the current simple integral SS.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new summing histogram with zero (empty) bars b[k]=0.
      Throws:
      NullPointerException - if bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if histogramLength<0, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingIntHistogram

      public static SummingHistogram newSummingIntHistogram(int[] histogram, int... bitLevelsOfPyramid)
      Equivalent to newSummingIntHistogram(histogram, false, bitLevelsOfPyramid).
      Parameters:
      histogram - initial values of the bars b[k] of the histogram.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new histogram with bars b[k]=histogram[k].
      Throws:
      NullPointerException - if histogram or bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if some of histogram elements are negative (<0), or if sum of all bars (elements of histogram array) is greater than Integer.MAX_VALUE, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • newSummingIntHistogram

      public static SummingHistogram newSummingIntHistogram(int[] histogram, boolean optimizeSimpleIntegral, int... bitLevelsOfPyramid)
      Creates new histogram, consisting of M=histogram.length bars, equal to elements of the given array. It is an analog of Histogram.newIntHistogram(int[], int...) method; the only difference is that this method creates an instance of SummingHistogram class.

      The optimizeSimpleIntegral argument allows to provide maximal performance if you are going to use the created instance for calculating only the simple current integral SS and do not need to calculate the precise integral SP (see the comments to this class). Namely, if this argument is false, this class provides good performance for calculating both integrals: all methods of this class usually require O(1) operations. If it is true, then include, exclude and all moveTo... methods will work rather more quickly, because they will not recalculate some internal invariants necessary for calculating the current precise integral SP. But, as a result, the methods currentPreciseIntegral() and currentPreciseIntegralBetweenSharing(), calculating SP, and also currentNumberOfDifferentValues() method will work more slowly. Namely, they can require O(M) operations, even in a case of using the histogram pyramid (see comments to bitLevelsOfPyramid argument in Histogram.newIntHistogram(int[], int...) method).

      Parameters:
      histogram - initial values of the bars b[k] of the histogram.
      optimizeSimpleIntegral - whether the created instance should be optimized for calculating the current simple integral SS.
      bitLevelsOfPyramid - the bit levels: binary logarithms of widths of bars in the sub-histograms in the "histogram pyramid"; can be empty, then will be ignored (the histogram pyramid will not be used).
      Returns:
      the new histogram with bars b[k]=histogram[k].
      Throws:
      NullPointerException - if histogram or bitLevelsOfPyramid argument is null.
      IllegalArgumentException - if some of histogram elements are negative (<0), or if sum of all bars (elements of histogram array) is greater than Integer.MAX_VALUE, or if bitLevelsOfPyramid.length>30, or if some of elements bitLevelsOfPyramid is not in 1..31 range, or if bitLevelsOfPyramid[k] >= bitLevelsOfPyramid[k+1] for some k.

    • nextSharing

      public abstract SummingHistogram nextSharing()
      Description copied from class: Histogram
      Returns the next instance of this class, sharing the histogram array b[k] with this instance.

      All instances, created by Histogram.share() method, are connected into a circular list, and this method returns the next element in this list. For example, if the instance h1 was created by Histogram.newLongHistogram(int, int...) method and, after this, the instance h2 was created as h2=h1.Histogram.share(), then this method in h1 object returns h2 and in h2 object returns h1. If there are no sharing instances, this method returns the reference to this instance.

      You can get all instances, sharing the same array b[k] with the given histogram hist, by the following loop: 

       Histogram h = hist.nextSharing();
 do {
     // some processing h instance
     h = h.nextSharing();
 } while (h != hist);

      See comments to Histogram class for more details.

      Specified by:
      nextSharing in class Histogram
      Returns:
      the next instance sharing the histogram array b[k] with this instance, or the reference to this instance if you did not use Histogram.share() method.
      See Also:

    • share

      public abstract SummingHistogram share()
      Description copied from class: Histogram
      Creates new instance of this class, which uses the same arrays of bars b[k]. The returned instance will share the histogram b[k] with this instance: any modification of b array by include / exclude methods will be immediately reflected in all shared instances. However, the created sharing instance has an independent set of current value, current simple rank and current precise rank, and they are initially set to 0.

      The returned instance has the absolutely same behaviour as this one: it uses the same set of bit levels (see comments to Histogram.newLongHistogram(int, int...) method), it is 32-bit if and only if this instance is 32-bit, it is a SummingHistogram if and only if this instance is a SummingHistogram, etc.

      See comments to Histogram class for more details.

      Specified by:
      share in class Histogram
      Returns:
      newly created instance sharing the histogram array b[k] with this instance.
      See Also:

    • currentNumberOfDifferentValues

      public abstract int currentNumberOfDifferentValues()
      Returns the number of non-zero bars b[k] with indexes k<currentIValue(). In other words, it is the count of different elements of the source array A, less than currentIValue().

      This method works quickly (it just returns an internal variable, supported by all methods of this class) only if this class was not created by newSummingLongHistogram(int, boolean, int...), newSummingLongHistogram(long[], boolean, int...), newSummingIntHistogram(int, boolean, int...), newSummingIntHistogram(int[], boolean, int...) methods with the argument optimizeSimpleIntegral=true. In this case, the internal value, returned by this method, is also used for calculating the current precise integral SP. If this class was created with the flag optimizeSimpleIntegral=true, this method just performs a simple loop on all b[k], k=0,1,...,currentIValue()−1, and therefore works slowly.

      Returns:
      the number of non-zero bars b[k] with indexes k<currentIValue().
      See Also:

    • currentSum

      public abstract double currentSum()
      Returns the sum of all elements of the source array A, less than v0=currentIValue(): z(v0) = Σ A[k]<vA[k] = Σ 0≤j<vj*b[j]. See the comments to this class for more details.

      Note: if the current value is integer, for example, after moveToIValue(v0) call, the currentIntegral() SS is equal to this sum plus 0.5*currentRank():

      SS = s(v0) = Σ 0≤j<v0(j+0.5)*b[j] = z(v0) + 0.5 * Σ 0≤j<v0b[j] = z(v0) + r(v0)/2
      Returns:
      the sum of all elements, less than currentIValue().
      See Also:

    • currentIntegral

      public final double currentIntegral()
      Returns the current simple integral SS. See the comments to this class for more details.
      Returns:
      the current simple integral.
      See Also:

    • currentPreciseIntegral

      public final double currentPreciseIntegral()
      Returns the current precise integral SP. See the comments to this class for more details.
      Returns:
      the current precise integral.
      See Also:

    • currentIntegralBetweenSharing

      public final double currentIntegralBetweenSharing()
      Equivalent to nextSharing().currentIntegral() - thisInstance.currentIntegral(), but probably works little faster.
      Returns:
      the difference between the current simple integrals SS, calculated in two instances, sharing the same histogram b[k].

    • currentPreciseIntegralBetweenSharing

      public final double currentPreciseIntegralBetweenSharing()
      Equivalent to nextSharing().currentPreciseIntegral() - thisInstance.currentPreciseIntegral(), but probably works little faster.
      Returns:
      the difference between the current precise integrals SP, calculated in two instances, sharing the same histogram b[k].

    • moveToIRank

      public abstract SummingHistogram moveToIRank(long rank)
      Description copied from class: Histogram
      Sets the current simple rank rS and precise rank rP to be equal of the rank argument. (Because the argument is integer, both rS and rP ranks are the same.) If the rank argument is negative, it is replaced with 0 (minimal possible rank); if rank>N=Histogram.total(), it is replaced with N (maximal possible rank). The current value v automatically changes in accordance to the new rank. See comments to Histogram class for more details.

      In the special case N=0 (all bars of the histograms are zero), both simple and precise ranks are always zero, not depending on calls of this method: rS=rP=0 (because r(v) is a zero constant by definition). But v(r) function (unlike r(v)) is not defined in this case, so, if N=0, the current value v after calling this method is not documented — there is the only guarantee that 0≤v≤M.

      This method works little faster than equivalent calls moveToRank(rank) and moveToPreciseRank(rank).

      Specified by:
      moveToIRank in class Histogram
      Parameters:
      rank - new rank rS=rP.
      Returns:
      the reference to this object.
      See Also:

    • moveToIValue

      public abstract SummingHistogram moveToIValue(int value)
      Description copied from class: Histogram
      Sets the current value v to be equal of the value argument. If the value argument is negative, it is replaced with 0 (minimal possible value); if value>M=Histogram.length(), it is replaced with M (maximal possible value). The current simple rank rS and the current precise rank rP automatically change in accordance to the new value. See comments to Histogram class for more details.

      This methods works little faster than the equivalent call moveToValue(value).

      Specified by:
      moveToIValue in class Histogram
      Parameters:
      value - new current value (percentile).
      Returns:
      the reference to this object.
      See Also:

    • moveToPreciseRank

      public SummingHistogram moveToPreciseRank(double rank)
      Description copied from class: Histogram
      Sets the current precise rank rP to be equal of the rank argument. If the rank argument is negative, it is replaced with 0 (minimal possible rank); if rank>N=Histogram.total(), it is replaced with N (maximal possible rank). The current simple rank rS and the current value v automatically change in accordance to the new precise rank. See comments to Histogram class for more details.

      In the special case N=0 (all bars of the histograms are zero), both simple and precise ranks are always zero, not depending on calls of this method: rS=rP=0 (because r(v) is a zero constant by definition). But v(r) function (unlike r(v)) is not defined in this case, so, if N=0, the current value v after calling this method is not documented — there is the only guarantee that 0≤v≤M.

      Overrides:
      moveToPreciseRank in class Histogram
      Parameters:
      rank - new precise rank rP.
      Returns:
      the reference to this object.
      See Also:

    • moveToValue

      public SummingHistogram moveToValue(double value)
      Description copied from class: Histogram
      Sets the current value v to be equal of the value argument. If the value argument is negative, it is replaced with 0 (minimal possible value); if value>M=Histogram.length(), it is replaced with M (maximal possible value). The current simple rank rS and the current precise rank rP automatically change in accordance to the new value. See comments to Histogram class for more details.
      Overrides:
      moveToValue in class Histogram
      Parameters:
      value - new current value (percentile).
      Returns:
      the reference to this object.
      See Also:

    • integralBetweenRanks

      public static double integralBetweenRanks(long[] histogram, double fromRank, double toRank)

      Returns the difference S(toRank)−S(fromRank), where S(r) is the summing function, defined in terms of the simple histogram model for the histogram b[k], passed via histogram argument. In other words, this method returns the definite integral of v(r) function, defined in terms of the simple histogram model, between r=fromRank and r=toRank. The fromRank argument should be not greater than toRank; in other case this method returns 0.0. See the comments to this class for more details.

      If fromRank<=toRank, the result of this method is equal to the result of the following operators: 

           SummingHistogram hist = SummingHistogram.newSummingLongHistogram(histogram);
      double fromIntegral = hist.moveToRank(fromRank).currentIntegral();
      double toIntegral = hist.moveToRank(toRank).currentIntegral();
      double result = toIntegral - fromIntegral;

      but this method works little faster.

      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      fromRank - the start rank.
      toRank - the end rank.
      Returns:
      the definite integral of v(r) function, defined in terms of the simple histogram model, between r=fromRank and r=toRank.
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(fromRank) or Double.isNaN(toRank).

    • integralBetweenRanks

      public static double integralBetweenRanks(int[] histogram, double fromRank, double toRank)
      Precise equivalent of integralBetweenRanks(long[], double, double) for a case of int[] type of the histogram.
      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      fromRank - the start rank.
      toRank - the end rank.
      Returns:
      the definite integral of v(r) function, defined in terms of the simple histogram model, between r=fromRank and r=toRank.
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(fromRank) or Double.isNaN(toRank).

    • preciseIntegralBetweenRanks

      public static double preciseIntegralBetweenRanks(long[] histogram, double fromRank, double toRank)

      Returns the difference S(toRank)−S(fromRank), where S(r) is the summing function, defined in terms of the precise histogram model for the histogram b[k], passed via histogram argument. In other words, this method returns the definite integral of v(r) function, defined in terms of the precise histogram model, between r=fromRank and r=toRank. The fromRank argument should be not greater than toRank; in other case this method returns 0.0. See the comments to this class for more details.

      If fromRank<=toRank, the result of this method is equal to the result of the following operators: 

           SummingHistogram hist = SummingHistogram.newSummingLongHistogram(histogram);
      double fromIntegral = hist.moveToPreciseRank(fromRank).currentPreciseIntegral();
      double toIntegral = hist.moveToPreciseRank(toRank).currentPreciseIntegral();
      double result = toIntegral - fromIntegral;

      but this method works little faster.

      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      fromRank - the start rank.
      toRank - the end rank.
      Returns:
      the definite integral of v(r) function, defined in terms of the precise histogram model, between r=fromRank and r=toRank.
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(fromRank) or Double.isNaN(toRank).

    • preciseIntegralBetweenRanks

      public static double preciseIntegralBetweenRanks(int[] histogram, double fromRank, double toRank)
      Precise equivalent of preciseIntegralBetweenRanks(long[], double, double) for a case of int[] type of the histogram.
      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      fromRank - the start rank.
      toRank - the end rank.
      Returns:
      the definite integral of v(r) function, defined in terms of the precise histogram model, between r=fromRank and r=toRank.
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(fromRank) or Double.isNaN(toRank).

    • integralBetweenValues

      public static double integralBetweenValues(long[] histogram, double minValue, double maxValue, SummingHistogram.CountOfValues countOfValues)

      Returns the difference s(maxValue)−s(minValue), where s(v) is the summing function, defined in terms of the simple histogram model for the histogram b[k], passed via histogram argument. In other words, this method returns the definite integral of v(r) function, defined in terms of the simple histogram model, between r=r(minValue) and r=r(maxValue). The minValue argument should be not greater than maxValue; in other case this method returns 0.0. See the comments to this class for more details.

      If minValue<=maxValue, the result of this method is equal to the result of the following operators: 

           SummingHistogram hist = SummingHistogram.newSummingLongHistogram(histogram);
     hist.moveToValue(minValue);
     double fromRank = hist.currentRank();
     double fromIntegral = hist.currentIntegral();
     hist.moveToValue(maxValue);
     double toRank = hist.currentRank();
     double toIntegral = hist.currentIntegral();
     double result = toIntegral - fromIntegral;

      but this method works little faster.

      The countOfValue argument, if it is not null, is filled by this method by some additional information. Namely:

      • countOfValue.count() will be equal to the difference r(maxValue)−r(minValue), where r(v) is the rank function, defined in terms of of the simple histogram model, or 0.0 if minValue>maxValue (see the comments to Histogram class); in the code example, listed above, it will be equal to toRank-fromRank;
      • countOfValue.isLeftBound() will be true if minValue<maxValue and r(maxValue)=r(minValue)=0 — in other words, if minValue..maxValue range fully lies to the left from the minimal element of the source array A[k]; the analogous information can be got by hist.leftFromNonZeroPart() method after hist.moveToValue(maxValue) call;
      • countOfValue.isRightBound() will be true if minValue<maxValue and r(maxValue)=r(minValue)=N — in other words, if minValue..maxValue range fully lies to the right from the maximal element of the source array A[k]; the analogous information can be got by hist.rightFromNonZeroPart() method after hist.moveToValue(minValue) call.

      Note: in the special case N=0 (all bars b[k] are zero), the countOfValue.isLeftBound() and countOfValue.isRightBound() values can be any: they are not specified. It is the only exception from the rules specified above.

      This information, for example, allows to calculate the mean of all elements of the source array A[k], lying in range minValue..maxValue, with generalization to the floating-point case: it is result_of_this_method/countOfValues.count().

      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      minValue - the minimal value.
      maxValue - the maximal value.
      countOfValues - some additional information filled by this method; may be null, then will be ignored.
      Returns:
      the definite integral of v(r) function, defined in terms of the simple histogram model, between r=r(minValue) and r=r(maxValue).
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(minValue) or Double.isNaN(maxValue).

    • integralBetweenValues

      public static double integralBetweenValues(int[] histogram, double minValue, double maxValue, SummingHistogram.CountOfValues countOfValues)
      Precise equivalent of integralBetweenValues(long[], double, double, CountOfValues) for a case of int[] type of the histogram.
      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      minValue - the minimal value.
      maxValue - the maximal value.
      countOfValues - some additional information filled by this method; may be null, then will be ignored.
      Returns:
      the definite integral of v(r) function, defined in terms of the simple histogram model, between r=r(minValue) and r=r(maxValue).
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(minValue) or Double.isNaN(maxValue).

    • preciseIntegralBetweenValues

      public static double preciseIntegralBetweenValues(long[] histogram, double minValue, double maxValue, SummingHistogram.CountOfValues countOfValues)

      Returns the difference s(maxValue)−s(minValue), where s(v) is the summing function, defined in terms of the precise histogram model for the histogram b[k], passed via histogram argument. In other words, this method returns the definite integral of v(r) function, defined in terms of the precise histogram model, between r=r(minValue) and r=r(maxValue). The minValue argument should be not greater than maxValue; in other case this method returns 0.0. See the comments to this class for more details.

      If minValue<=maxValue, the result of this method is equal to the result of the following operators: 

           SummingHistogram hist = SummingHistogram.newSummingLongHistogram(histogram);
     hist.moveToValue(minValue);
     double fromRank = hist.currentPreciseRank();
     double fromIntegral = hist.currentPreciseIntegral();
     hist.moveToValue(maxValue);
     double toRank = hist.currentPreciseRank();
     double toIntegral = hist.currentPreciseIntegral();
     double result = toIntegral - fromIntegral;

      but this method works little faster.

      The countOfValue argument, if it is not null, is filled by this method by some additional information. Namely:

      • countOfValue.count() will be equal to the difference r(maxValue)−r(minValue), where r(v) is the rank function, defined in terms of of the precise histogram model, or 0.0 if minValue>maxValue (see the comments to Histogram class); in the code example, listed above, it will be equal to toRank-fromRank;
      • countOfValue.isLeftBound() will be true if minValue<maxValue and r(maxValue)=r(minValue)=0 — in other words, if minValue..maxValue range fully lies to the left from the minimal element of the source array A[k]; the analogous information can be got by hist.leftFromNonZeroPart() method after hist.moveToValue(maxValue) call;
      • countOfValue.isRightBound() will be true if minValue<maxValue and r(maxValue)=r(minValue)=N — in other words, if minValue..maxValue range fully lies to the right from the maximal element of the source array A[k]; the analogous information can be got by hist.rightFromNonZeroPart() method after hist.moveToValue(minValue) call.

      Note: in the special case N=0 (all bars b[k] are zero), the countOfValue.isLeftBound() and countOfValue.isRightBound() values can be any: they are not specified. It is the only exception from the rules specified above.

      This information, for example, allows to calculate the mean of all elements of the source array A[k], lying in range minValue..maxValue, with generalization to the floating-point case: it is result_of_this_method/countOfValues.count().

      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      minValue - the minimal value.
      maxValue - the maximal value.
      countOfValues - some additional information filled by this method; may be null, then will be ignored.
      Returns:
      the definite integral of v(r) function, defined in terms of the precise histogram model, between r=r(minValue) and r=r(maxValue).
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(minValue) or Double.isNaN(maxValue).

    • preciseIntegralBetweenValues

      public static double preciseIntegralBetweenValues(int[] histogram, double minValue, double maxValue, SummingHistogram.CountOfValues countOfValues)
      Precise equivalent of preciseIntegralBetweenValues(long[], double, double, CountOfValues) for a case of int[] type of the histogram.
      Parameters:
      histogram - histogram[k]=b[k] is the number of elements in the source array that are equal to k. All histogram[k] must be non-negative; in other case, IllegalArgumentException can be thrown (but also can be not thrown).
      minValue - the minimal value.
      maxValue - the maximal value.
      countOfValues - some additional information filled by this method; may be null, then will be ignored.
      Returns:
      the definite integral of v(r) function, defined in terms of the precise histogram model, between r=r(minValue) and r=r(maxValue).
      Throws:
      NullPointerException - if histogram argument is null.
      IllegalArgumentException - if Double.isNaN(minValue) or Double.isNaN(maxValue).