hep.aida.bin
Class MightyStaticBin1D

java.lang.Object
  extended by cern.colt.PersistentObject
      extended by hep.aida.bin.AbstractBin
          extended by hep.aida.bin.AbstractBin1D
              extended by hep.aida.bin.StaticBin1D
                  extended by hep.aida.bin.MightyStaticBin1D
All Implemented Interfaces:
DoubleBufferConsumer, java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
QuantileBin1D

public class MightyStaticBin1D
extends StaticBin1D

Static and the same as its superclass, except that it can do more: Additionally computes moments of arbitrary integer order, harmonic mean, geometric mean, etc. Constructors need to be told what functionality is required for the given use case. Only maintains aggregate measures (incrementally) - the added elements themselves are not kept.

Author:
wolfgang.hoschek@cern.ch
See Also:
Serialized Form

Field Summary
protected  boolean hasSumOfInversions
           
protected  boolean hasSumOfLogarithms
           
protected  double sumOfInversions
           
protected  double sumOfLogarithms
           
protected  double[] sumOfPowers
           
 
Fields inherited from class hep.aida.bin.StaticBin1D
arguments, max, min, size, sum, sum_xx
 
Fields inherited from class cern.colt.PersistentObject
serialVersionUID
 
Constructor Summary
MightyStaticBin1D()
          Constructs and returns an empty bin with limited functionality but good performance; equivalent to MightyStaticBin1D(false,false,4).
MightyStaticBin1D(boolean hasSumOfLogarithms, boolean hasSumOfInversions, int maxOrderForSumOfPowers)
          Constructs and returns an empty bin with the given capabilities.
 
Method Summary
 void addAllOfFromTo(DoubleArrayList list, int from, int to)
          Adds the part of the specified list between indexes from (inclusive) and to (inclusive) to the receiver.
protected  void clearAllMeasures()
          Resets the values of all measures.
 java.lang.Object clone()
          Returns a deep copy of the receiver.
 java.lang.String compareWith(AbstractBin1D other)
          Computes the deviations from the receiver's measures to another bin's measures.
 double geometricMean()
          Returns the geometric mean, which is Product( x[i] )1.0/size().
 int getMaxOrderForSumOfPowers()
          Returns the maximum order k for which sums of powers are retrievable, as specified upon instance construction.
 int getMinOrderForSumOfPowers()
          Returns the minimum order k for which sums of powers are retrievable, as specified upon instance construction.
 double harmonicMean()
          Returns the harmonic mean, which is size() / Sum( 1/x[i] ).
 boolean hasSumOfInversions()
          Returns whether sumOfInversions() can return meaningful results.
 boolean hasSumOfLogarithms()
          Tells whether sumOfLogarithms() can return meaningful results.
 boolean hasSumOfPowers(int k)
          Tells whether sumOfPowers(k) can return meaningful results.
 double kurtosis()
          Returns the kurtosis (aka excess), which is -3 + moment(4,mean()) / standardDeviation()4.
 double moment(int k, double c)
          Returns the moment of k-th order with value c, which is Sum( (x[i]-c)k ) / size().
 double product()
          Returns the product, which is Prod( x[i] ).
protected  void setMaxOrderForSumOfPowers(int max_k)
          Sets the range of orders in which sums of powers are to be computed.
 double skew()
          Returns the skew, which is moment(3,mean()) / standardDeviation()3.
 double sumOfInversions()
          Returns the sum of inversions, which is Sum( 1 / x[i] ).
 double sumOfLogarithms()
          Returns the sum of logarithms, which is Sum( Log(x[i]) ).
 double sumOfPowers(int k)
          Returns the k-th order sum of powers, which is Sum( x[i]k ).
 java.lang.String toString()
          Returns a String representation of the receiver.
protected  void xcheckOrder(int k)
           
protected  boolean xequals(java.lang.Object object)
          Returns whether two bins are equal; They are equal if the other object is of the same class or a subclass of this class and both have the same size, minimum, maximum, sum, sumOfSquares, sumOfInversions and sumOfLogarithms.
protected  boolean xhasSumOfPowers(int fromK, int toK)
          Tells whether sumOfPowers(fromK) ..
protected  boolean xisLegalOrder(int k)
          Returns getMinOrderForSumOfPowers() <= k && k <= getMaxOrderForSumOfPowers().
 
Methods inherited from class hep.aida.bin.StaticBin1D
add, clear, isRebinnable, max, min, size, sum, sumOfSquares
 
Methods inherited from class hep.aida.bin.AbstractBin1D
addAllOf, buffered, equals, mean, relError, rms, standardDeviation, standardError, trimToSize, variance
 
Methods inherited from class hep.aida.bin.AbstractBin
center, center, error, error, offset, offset, value, value
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

hasSumOfLogarithms

protected boolean hasSumOfLogarithms

sumOfLogarithms

protected double sumOfLogarithms

hasSumOfInversions

protected boolean hasSumOfInversions

sumOfInversions

protected double sumOfInversions

sumOfPowers

protected double[] sumOfPowers
Constructor Detail

MightyStaticBin1D

public MightyStaticBin1D()
Constructs and returns an empty bin with limited functionality but good performance; equivalent to MightyStaticBin1D(false,false,4).


MightyStaticBin1D

public MightyStaticBin1D(boolean hasSumOfLogarithms,
                         boolean hasSumOfInversions,
                         int maxOrderForSumOfPowers)
Constructs and returns an empty bin with the given capabilities.

Parameters:
hasSumOfLogarithms - Tells whether sumOfLogarithms() can return meaningful results. Set this parameter to false if measures of sum of logarithms, geometric mean and product are not required.

hasSumOfInversions - Tells whether sumOfInversions() can return meaningful results. Set this parameter to false if measures of sum of inversions, harmonic mean and sumOfPowers(-1) are not required.

maxOrderForSumOfPowers - The maximum order k for which sumOfPowers(int) can return meaningful results. Set this parameter to at least 3 if the skew is required, to at least 4 if the kurtosis is required. In general, if moments are required set this parameter at least as large as the largest required moment. This method always substitutes Math.max(2,maxOrderForSumOfPowers) for the parameter passed in. Thus, sumOfPowers(0..2) always returns meaningful results.
See Also:
hasSumOfPowers(int), moment(int,double)
Method Detail

addAllOfFromTo

public void addAllOfFromTo(DoubleArrayList list,
                           int from,
                           int to)
Adds the part of the specified list between indexes from (inclusive) and to (inclusive) to the receiver.

Overrides:
addAllOfFromTo in class StaticBin1D
Parameters:
list - the list of which elements shall be added.
from - the index of the first element to be added (inclusive).
to - the index of the last element to be added (inclusive).
Throws:
java.lang.IndexOutOfBoundsException - if list.size()>0 && (from<0 || from>to || to>=list.size()).

clearAllMeasures

protected void clearAllMeasures()
Resets the values of all measures.

Overrides:
clearAllMeasures in class StaticBin1D

clone

public java.lang.Object clone()
Returns a deep copy of the receiver.

Overrides:
clone in class PersistentObject
Returns:
a deep copy of the receiver.

compareWith

public java.lang.String compareWith(AbstractBin1D other)
Computes the deviations from the receiver's measures to another bin's measures.

Overrides:
compareWith in class AbstractBin1D
Parameters:
other - the other bin to compare with
Returns:
a summary of the deviations.

geometricMean

public double geometricMean()
Returns the geometric mean, which is Product( x[i] )1.0/size(). This method tries to avoid overflows at the expense of an equivalent but somewhat inefficient definition: geoMean = exp( Sum( Log(x[i]) ) / size()). Note that for a geometric mean to be meaningful, the minimum of the data sequence must not be less or equal to zero.

Returns:
the geometric mean; Double.NaN if !hasSumOfLogarithms().

getMaxOrderForSumOfPowers

public int getMaxOrderForSumOfPowers()
Returns the maximum order k for which sums of powers are retrievable, as specified upon instance construction.

See Also:
hasSumOfPowers(int), sumOfPowers(int)

getMinOrderForSumOfPowers

public int getMinOrderForSumOfPowers()
Returns the minimum order k for which sums of powers are retrievable, as specified upon instance construction.

See Also:
hasSumOfPowers(int), sumOfPowers(int)

harmonicMean

public double harmonicMean()
Returns the harmonic mean, which is size() / Sum( 1/x[i] ). Remember: If the receiver contains at least one element of 0.0, the harmonic mean is 0.0.

Returns:
the harmonic mean; Double.NaN if !hasSumOfInversions().
See Also:
hasSumOfInversions()

hasSumOfInversions

public boolean hasSumOfInversions()
Returns whether sumOfInversions() can return meaningful results.

Returns:
false if the bin was constructed with insufficient parametrization, true otherwise. See the constructors for proper parametrization.

hasSumOfLogarithms

public boolean hasSumOfLogarithms()
Tells whether sumOfLogarithms() can return meaningful results.

Returns:
false if the bin was constructed with insufficient parametrization, true otherwise. See the constructors for proper parametrization.

hasSumOfPowers

public boolean hasSumOfPowers(int k)
Tells whether sumOfPowers(k) can return meaningful results. Defined as hasSumOfPowers(k) <==> getMinOrderForSumOfPowers() <= k && k <= getMaxOrderForSumOfPowers(). A return value of true implies that hasSumOfPowers(k-1) .. hasSumOfPowers(0) will also return true. See the constructors for proper parametrization.

Details: hasSumOfPowers(0..2) will always yield true. hasSumOfPowers(-1) <==> hasSumOfInversions().

Returns:
false if the bin was constructed with insufficient parametrization, true otherwise.
See Also:
getMinOrderForSumOfPowers(), getMaxOrderForSumOfPowers()

kurtosis

public double kurtosis()
Returns the kurtosis (aka excess), which is -3 + moment(4,mean()) / standardDeviation()4.

Returns:
the kurtosis; Double.NaN if !hasSumOfPowers(4).
See Also:
hasSumOfPowers(int)

moment

public double moment(int k,
                     double c)
Returns the moment of k-th order with value c, which is Sum( (x[i]-c)k ) / size().

Parameters:
k - the order; must be greater than or equal to zero.
c - any number.
Returns:
Double.NaN if !hasSumOfPower(k).
Throws:
java.lang.IllegalArgumentException - if k < 0.

product

public double product()
Returns the product, which is Prod( x[i] ). In other words: x[0]*x[1]*...*x[size()-1].

Returns:
the product; Double.NaN if !hasSumOfLogarithms().
See Also:
hasSumOfLogarithms()

setMaxOrderForSumOfPowers

protected void setMaxOrderForSumOfPowers(int max_k)
Sets the range of orders in which sums of powers are to be computed. In other words, sumOfPower(k) will return Sum( x[i]^k ) if min_k <= k <= max_k || 0 <= k <= 2 and throw an exception otherwise.

See Also:
#isLegalOrder(int), sumOfPowers(int), #getRangeForSumOfPowers()

skew

public double skew()
Returns the skew, which is moment(3,mean()) / standardDeviation()3.

Returns:
the skew; Double.NaN if !hasSumOfPowers(3).
See Also:
hasSumOfPowers(int)

sumOfInversions

public double sumOfInversions()
Returns the sum of inversions, which is Sum( 1 / x[i] ).

Returns:
the sum of inversions; Double.NaN if !hasSumOfInversions().
See Also:
hasSumOfInversions()

sumOfLogarithms

public double sumOfLogarithms()
Returns the sum of logarithms, which is Sum( Log(x[i]) ).

Returns:
the sum of logarithms; Double.NaN if !hasSumOfLogarithms().
See Also:
hasSumOfLogarithms()

sumOfPowers

public double sumOfPowers(int k)
Returns the k-th order sum of powers, which is Sum( x[i]k ).

Parameters:
k - the order of the powers.
Returns:
the sum of powers; Double.NaN if !hasSumOfPowers(k).
See Also:
hasSumOfPowers(int)

toString

public java.lang.String toString()
Returns a String representation of the receiver.

Overrides:
toString in class AbstractBin1D

xcheckOrder

protected void xcheckOrder(int k)
Throws:
IllegalOperationException - if ! isLegalOrder(k).

xequals

protected boolean xequals(java.lang.Object object)
Returns whether two bins are equal; They are equal if the other object is of the same class or a subclass of this class and both have the same size, minimum, maximum, sum, sumOfSquares, sumOfInversions and sumOfLogarithms.


xhasSumOfPowers

protected boolean xhasSumOfPowers(int fromK,
                                  int toK)
Tells whether sumOfPowers(fromK) .. sumOfPowers(toK) can return meaningful results.

Returns:
false if the bin was constructed with insufficient parametrization, true otherwise. See the constructors for proper parametrization.
Throws:
java.lang.IllegalArgumentException - if fromK > toK.

xisLegalOrder

protected boolean xisLegalOrder(int k)
Returns getMinOrderForSumOfPowers() <= k && k <= getMaxOrderForSumOfPowers().