hep.aida.ref.histogram

Class Histogram3D

java.lang.Object

hep.aida.ref.event.AIDAObservable

hep.aida.ref.ManagedObject

hep.aida.ref.histogram.AbstractBaseHistogram

hep.aida.ref.histogram.Histogram

hep.aida.ref.histogram.Histogram3D

All Implemented Interfaces:

IDevManagedObject, IBaseHistogram, IHistogram, IHistogram3D, IManagedObject, Connectable, IsObservable, java.io.Serializable

Direct Known Subclasses:

H3D

public class Histogram3D
extends Histogram
implements IHistogram3D, java.io.Serializable

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Histogram3D() Create a 3-dimensional Histogram.
Histogram3D(java.lang.String name, java.lang.String title, IAxis xAxis, IAxis yAxis, IAxis zAxis) Create a 3-dimensional Histogram.
Histogram3D(java.lang.String name, java.lang.String title, IAxis xAxis, IAxis yAxis, IAxis zAxis, java.lang.String options) Create a 3-dimensional Histogram.

Method Summary

Modifier and Type	Method and Description
void	add(IHistogram3D hist) Modifies this histogram by adding the contents of h to it.
int	binEntries(int indexX, int indexY, int indexZ) Number of entries in the corresponding bin (ie the number of times fill was called for this bin).
int	binEntriesX(int indexX) Number of entries with a given x bin number (ie the number of times fill was called for these bins).
int	binEntriesY(int indexY) Number of entries with a given x bin number (ie the number of times fill was called for these bins).
int	binEntriesZ(int indexZ) Number of entries with a given x bin number (ie the number of times fill was called for these bins).
double	binError(int indexX, int indexY, int indexZ) The error on this bin.
double	binHeight(int indexX, int indexY, int indexZ) Total height of the corresponding bin.
double	binHeightX(int indexX) Total height of the corresponding x bin along y and z.
double	binHeightY(int indexY) Total height of the corresponding y bin along x and z.
double	binHeightZ(int indexZ) Total height of the corresponding z bin along x and y.
double	binMeanX(int indexX, int indexY, int indexZ) Get the mean of a bin along the x axis.
double	binMeanY(int indexX, int indexY, int indexZ) Get the mean of a bin along the y axis.
double	binMeanZ(int indexX, int indexY, int indexZ) Get the mean of a bin along the z axis.
double	binRmsX(int indexX, int indexY, int indexZ) Get the RMS of a bin along the x axis.
double	binRmsY(int indexX, int indexY, int indexZ) Get the RMS of a bin along the y axis.
double	binRmsZ(int indexX, int indexY, int indexZ) Get the RMS of a bin along the z axis.
int	coordToIndexX(double coordX) Convenience method, equivalent to xAxis().coordToIndex(coord).
int	coordToIndexY(double coordY) Convenience method, equivalent to yAxis().coordToIndex(coord).
int	coordToIndexZ(double coordZ) Convenience method, equivalent to zAxis().coordToIndex(coord).
int	extraEntries() Get the number of entries in the underflow and overflow bins.
void	fill(double x, double y, double z) Fill the Histogram with unit weight.
void	fill(double x, double y, double z, double weight) Fill the Histogram.
void	initHistogram3D(IAxis xAxis, IAxis yAxis, IAxis zAxis, java.lang.String options)
double	maxBinHeight() Get the maximum height of in-range bins in the Histogram.
double	meanX() Get the mean of the whole Histogram as projected on the x axis.
double	meanY() Get the mean of the whole Histogram as projected on the y axis.
double	meanZ() Get the mean of the whole Histogram as projected on the z axis.
double	minBinHeight() Get the minimum height of in-range bins in the Histogram.
void	reset() Reset the Histogram.
double	rmsX() Get the RMS of the whole Histogram as projected on the x axis.
double	rmsY() Get the RMS of the whole Histogram as projected on the y axis.
double	rmsZ() Get the RMS of the whole Histogram as projected on the z axis.
void	scale(double scaleFactor) Scale the weights and the errors by a given factor.
void	setBinError(int indexX, int indexY, int indexZ, double error) Set the error on this bin.
void	setContents(double[][][] heights, double[][][] errors, int[][][] entries, double[][][] meanXs, double[][][] rmsXs, double[][][] meanYs, double[][][] rmsYs, double[][][] meanZs, double[][][] rmsZs) Set the content of the whole Histogram at once.
void	setMeanX(double meanX) All the non-AIDA methods should go below this point.
void	setMeanY(double meanY)
void	setMeanZ(double meanZ)
void	setRmsX(double rmsX)
void	setRmsY(double rmsY)
void	setRmsZ(double rmsZ)
double	sumAllBinHeights() Get the sum of the bin heights for all the entries, in-range and out-range ones.
double	sumExtraBinHeights() Get the sum of the bin heights for all the entries outside the Histogram's range.
IAxis	xAxis() Get the X axis.
IAxis	yAxis() Get the Y axis.
IAxis	zAxis() Get the Z axis.

Methods inherited from class hep.aida.ref.histogram.Histogram

allEntries, entries, equivalentBinEntries, isMeanAndRmsSet, nanEntries, setNEntries, setValidEntries, sumBinHeights

Methods inherited from class hep.aida.ref.histogram.AbstractBaseHistogram

annotation, dimension, mapBinNumber, setAnnotation, setTitle, title

Methods inherited from class hep.aida.ref.ManagedObject

isFillable, name, setFillable, setName, type, typeForClass

Methods inherited from class hep.aida.ref.event.AIDAObservable

addListener, isConnected, removeAllListeners, removeListener, setConnected, setValid, setValidForAll

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface hep.aida.IHistogram

allEntries, equivalentBinEntries, sumBinHeights

Methods inherited from interface hep.aida.IBaseHistogram

annotation, dimension, entries, nanEntries, setTitle, title

Methods inherited from interface hep.aida.ref.event.IsObservable

addListener, removeAllListeners, removeListener, setValid

Methods inherited from interface hep.aida.ref.event.Connectable

isConnected, setConnected

Constructor Detail

Histogram3D

public Histogram3D()

Create a 3-dimensional Histogram.

Histogram3D

public Histogram3D(java.lang.String name,
                   java.lang.String title,
                   IAxis xAxis,
                   IAxis yAxis,
                   IAxis zAxis)

Create a 3-dimensional Histogram.

Parameters:

name - The name of the Histogram as a ManagedObject.

title - The title of the Histogram.

xAxis - The x-axis of the Histogram.

yAxis - The y-axis of the Histogram.

zAxis - The z-axis of the Histogram.

Histogram3D

public Histogram3D(java.lang.String name,
                   java.lang.String title,
                   IAxis xAxis,
                   IAxis yAxis,
                   IAxis zAxis,
                   java.lang.String options)

Create a 3-dimensional Histogram.

Parameters:

name - The name of the Histogram as a ManagedObject.

title - The title of the Histogram.

xAxis - The x-axis of the Histogram.

yAxis - The y-axis of the Histogram.

zAxis - The z-axis of the Histogram.

options - The options of the Histogram.

Method Detail

fill

public void fill(double x,
                 double y,
                 double z)

Fill the Histogram with unit weight.

Specified by:

fill in interface IHistogram3D

Parameters:

x - The x value to be filled.

y - The y value to be filled.

z - The z value to be filled.

fill

public void fill(double x,
                 double y,
                 double z,
                 double weight)

Fill the Histogram.

Specified by:

fill in interface IHistogram3D

Parameters:

x - The x value to be filled.

y - The y value to be filled.

z - The z value to be filled.

weight - The weight for this entry.

reset

public void reset()

Reset the Histogram. After calling this method the Histogram is as it was just created.

Specified by:

reset in interface IBaseHistogram

Overrides:

reset in class Histogram

extraEntries

public int extraEntries()

Get the number of entries in the underflow and overflow bins.

Specified by:

extraEntries in interface IHistogram

Specified by:

extraEntries in class Histogram

Returns:

The number of entries outside the range of the Histogram.

sumAllBinHeights

public double sumAllBinHeights()

Get the sum of the bin heights for all the entries, in-range and out-range ones.

Specified by:

sumAllBinHeights in interface IHistogram

Specified by:

sumAllBinHeights in class Histogram

Returns:

The sum of all the bin's heights.

sumExtraBinHeights

public double sumExtraBinHeights()

Get the sum of the bin heights for all the entries outside the Histogram's range.

Specified by:

sumExtraBinHeights in interface IHistogram

Specified by:

sumExtraBinHeights in class Histogram

Returns:

The sum of the out of range bin's heights.

minBinHeight

public double minBinHeight()

Get the minimum height of in-range bins in the Histogram.

Specified by:

minBinHeight in interface IHistogram

Specified by:

minBinHeight in class Histogram

Returns:

The minimum bin height for in range bins.

maxBinHeight

public double maxBinHeight()

Get the maximum height of in-range bins in the Histogram.

Specified by:

maxBinHeight in interface IHistogram

Specified by:

maxBinHeight in class Histogram

Returns:

The maximum bin height for in range bins.

binEntries

public int binEntries(int indexX,
                      int indexY,
                      int indexZ)

Number of entries in the corresponding bin (ie the number of times fill was called for this bin).

Specified by:

binEntries in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The number of entries for the corresponding bin.

binEntriesX

public int binEntriesX(int indexX)

Number of entries with a given x bin number (ie the number of times fill was called for these bins). Equivalent to projectionXY().binEntriesX(indexX).

Specified by:

binEntriesX in interface IHistogram3D

Parameters:

indexX - the x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The number of entries for the corresponding bins.

binEntriesY

public int binEntriesY(int indexY)

Number of entries with a given x bin number (ie the number of times fill was called for these bins). Equivalent to projectionXY().binEntriesY(indexY).

Specified by:

binEntriesY in interface IHistogram3D

Parameters:

indexY - the y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The number of entries for the corresponding bins.

binEntriesZ

public int binEntriesZ(int indexZ)

Number of entries with a given x bin number (ie the number of times fill was called for these bins). Equivalent to projectionXZ().binEntriesZ(indexZ).

Specified by:

binEntriesZ in interface IHistogram3D

Parameters:

indexZ - the z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The number of entries for the corresponding bins.

binHeight

public double binHeight(int indexX,
                        int indexY,
                        int indexZ)

Total height of the corresponding bin.

Specified by:

binHeight in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The bin height for the corresponding bin.

binHeightX

public double binHeightX(int indexX)

Total height of the corresponding x bin along y and z. Equivalent to projectionXY().binHeightX(indexX).

Specified by:

binHeightX in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The bin height for the corresponding bin.

binHeightY

public double binHeightY(int indexY)

Total height of the corresponding y bin along x and z. Equivalent to projectionXY().binHeightY(indexY).

Specified by:

binHeightY in interface IHistogram3D

Parameters:

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The bin height for the corresponding bin.

binHeightZ

public double binHeightZ(int indexZ)

Total height of the corresponding z bin along x and y. Equivalent to projectionXZ().binHeightZ(indexZ).

Specified by:

binHeightZ in interface IHistogram3D

Parameters:

indexZ - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The bin height for the corresponding bin.

binError

public double binError(int indexX,
                       int indexY,
                       int indexZ)

The error on this bin.

Specified by:

binError in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The error on the corresponding bin.

meanX

public double meanX()

Get the mean of the whole Histogram as projected on the x axis. It includes all the entries (in and out of range).

Specified by:

meanX in interface IHistogram3D

Returns:

The mean of the Histogram on the x axis.

meanY

public double meanY()

Get the mean of the whole Histogram as projected on the y axis. It includes all the entries (in and out of range).

Specified by:

meanY in interface IHistogram3D

Returns:

The mean of the Histogram on the y axis.

meanZ

public double meanZ()

Get the mean of the whole Histogram as projected on the z axis. It includes all the entries (in and out of range).

Specified by:

meanZ in interface IHistogram3D

Returns:

The mean of the Histogram on the z axis.

rmsX

public double rmsX()

Get the RMS of the whole Histogram as projected on the x axis. It includes all the entries (in and out of range).

Specified by:

rmsX in interface IHistogram3D

Returns:

The RMS of the Histogram on the x axis.

rmsY

public double rmsY()

Get the RMS of the whole Histogram as projected on the y axis. It includes all the entries (in and out of range).

Specified by:

rmsY in interface IHistogram3D

Returns:

The RMS of the Histogram on the y axis.

rmsZ

public double rmsZ()

Get the RMS of the whole Histogram as projected on the z axis. It includes all the entries (in and out of range).

Specified by:

rmsZ in interface IHistogram3D

Returns:

The RMS of the Histogram on the z axis.

xAxis

public IAxis xAxis()

Get the X axis.

Specified by:

xAxis in interface IHistogram3D

Returns:

The x axis.

yAxis

public IAxis yAxis()

Get the Y axis.

Specified by:

yAxis in interface IHistogram3D

Returns:

The y axis.

zAxis

public IAxis zAxis()

Get the Z axis.

Specified by:

zAxis in interface IHistogram3D

Returns:

The z axis.

coordToIndexX

public int coordToIndexX(double coordX)

Convenience method, equivalent to xAxis().coordToIndex(coord).

Specified by:

coordToIndexX in interface IHistogram3D

Parameters:

coordX - The coordinalte along the x axis.

Returns:

The bin's index along the x axis corresponding to the position coordX.

See Also:

IAxis.coordToIndex(double)

coordToIndexY

public int coordToIndexY(double coordY)

Convenience method, equivalent to yAxis().coordToIndex(coord).

Specified by:

coordToIndexY in interface IHistogram3D

Parameters:

coordY - The coordinalte along the y axis.

Returns:

The bin's index along the y axis corresponding to the position coordY.

See Also:

IAxis.coordToIndex(double)

coordToIndexZ

public int coordToIndexZ(double coordZ)

Convenience method, equivalent to zAxis().coordToIndex(coord).

Specified by:

coordToIndexZ in interface IHistogram3D

Parameters:

coordZ - The coordinalte along the z axis.

Returns:

The bin's index along the z axis corresponding to the position coordY.

See Also:

IAxis.coordToIndex(double)

scale

public void scale(double scaleFactor)
           throws java.lang.IllegalArgumentException

Scale the weights and the errors by a given factor.

Specified by:

scale in interface IHistogram

Specified by:

scale in class Histogram

Parameters:

scaleFactor - The scale factor.

Throws:

java.lang.IllegalArgumentException - If the scale factor is negative.

add

public void add(IHistogram3D hist)
         throws java.lang.IllegalArgumentException

Modifies this histogram by adding the contents of h to it.

Specified by:

add in interface IHistogram3D

Parameters:

hist - The histogram to be added to this histogram

Throws:

java.lang.IllegalArgumentException - if histogram binnings are incompatible

setMeanX

public void setMeanX(double meanX)

All the non-AIDA methods should go below this point.

setRmsX

public void setRmsX(double rmsX)

setMeanY

public void setMeanY(double meanY)

setRmsY

public void setRmsY(double rmsY)

setMeanZ

public void setMeanZ(double meanZ)

setRmsZ

public void setRmsZ(double rmsZ)

binMeanX

public double binMeanX(int indexX,
                       int indexY,
                       int indexZ)

Get the mean of a bin along the x axis.

Specified by:

binMeanX in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The mean of the corresponding bin along x. If the bin has zero height, zero is returned.

binMeanY

public double binMeanY(int indexX,
                       int indexY,
                       int indexZ)

Get the mean of a bin along the y axis.

Specified by:

binMeanY in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The mean of the corresponding bin along y. If the bin has zero height, zero is returned.

binMeanZ

public double binMeanZ(int indexX,
                       int indexY,
                       int indexZ)

Get the mean of a bin along the z axis.

Specified by:

binMeanZ in interface IHistogram3D

Parameters:

indexX - The x bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation: (0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The mean of the corresponding bin along z. If the bin has zero height, zero is returned.

binRmsX

public double binRmsX(int indexX,
                      int indexY,
                      int indexZ)

Get the RMS of a bin along the x axis.

Parameters:

indexX - The x bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The RMS of the corresponding bin along x. If the bin has zero height, zero is returned.

binRmsY

public double binRmsY(int indexX,
                      int indexY,
                      int indexZ)

Get the RMS of a bin along the y axis.

Parameters:

indexX - The x bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The RMS of the corresponding bin along y. If the bin has zero height, zero is returned.

binRmsZ

public double binRmsZ(int indexX,
                      int indexY,
                      int indexZ)

Get the RMS of a bin along the z axis.

Parameters:

indexX - The x bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexY - The y bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - The z bin number in the external representation:(0...N-1) or OVERFLOW or UNDERFLOW.

Returns:

The RMS of the corresponding bin along z. If the bin has zero height, zero is returned.

setBinError

public void setBinError(int indexX,
                        int indexY,
                        int indexZ,
                        double error)

Set the error on this bin.

Parameters:

indexX - the bin number (0...N-1) or OVERFLOW or UNDERFLOW.

indexY - the bin number (0...N-1) or OVERFLOW or UNDERFLOW.

indexZ - the bin number (0...N-1) or OVERFLOW or UNDERFLOW.

setContents

public void setContents(double[][][] heights,
                        double[][][] errors,
                        int[][][] entries,
                        double[][][] meanXs,
                        double[][][] rmsXs,
                        double[][][] meanYs,
                        double[][][] rmsYs,
                        double[][][] meanZs,
                        double[][][] rmsZs)

Set the content of the whole Histogram at once. This is a convenience method for saving/restoring Histograms. Of the arguments below the heights array cannot be null. The errors array should in general be non-null, but this depends on the specific binner. The entries array can be null, in which case the entry of a bin is taken to be the integer part of the height. If the means array is null, the mean is defaulted to the geometric center of the bin. If the rms array is null, the rms is taken to be the bin width over the root of 12.

Parameters:

heights - The bin heights

errors - The bin errors

entries - The bin entries

meanXs - The means of the bin along the x axis

rmsXs - The rmss of the bin along the x axis

meanYs - The means of the bin along the y axis

rmsYs - The rmss of the bin along the y axis

meanZs - The means of the bin along the z axis

rmsZs - The rmss of the bin along the z axis

initHistogram3D

public void initHistogram3D(IAxis xAxis,
                            IAxis yAxis,
                            IAxis zAxis,
                            java.lang.String options)