Struct rgsl::types::histograms::Histogram2D

pub struct Histogram2D { /* private fields */ }

A two dimensional histogram consists of a set of bins which count the number of events falling in a given area of the (x,y) plane. The simplest way to use a two dimensional histogram is to record two-dimensional position information, n(x,y). Another possibility is to form a joint distribution by recording related variables. For example a detector might record both the position of an event (x) and the amount of energy it deposited E. These could be histogrammed as the joint distribution n(x,E).

Implementations

impl Histogram2D

pub fn new(nx: usize, ny: usize) -> Option<Histogram2D>

This function allocates memory for a two-dimensional histogram with nx bins in the x direction and ny bins in the y direction. The function returns a pointer to a newly created gsl_histogram2d struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code of Value::NoMem. The bins and ranges must be initialized with one of the functions below before the histogram is ready for use.

pub fn set_ranges( &mut self, xrange: &[f64], yrange: &[f64] ) -> Result<(), Value>

This function sets the ranges of the existing histogram h using the arrays xrange and yrange of size xsize and ysize respectively. The values of the histogram bins are reset to zero.

pub fn set_ranges_uniform( &mut self, xmin: f64, xmax: f64, ymin: f64, ymax: f64 ) -> Result<(), Value>

This function sets the ranges of the existing histogram h to cover the ranges xmin to xmax and ymin to ymax uniformly. The values of the histogram bins are reset to zero.

pub fn copy(&self, dest: &mut Histogram2D) -> Result<(), Value>

This function copies the histogram src into the pre-existing histogram dest, making dest into an exact copy of src. The two histograms must be of the same size.

pub fn clone(&self) -> Option<Histogram2D>

his function returns a pointer to a newly created histogram which is an exact copy of the histogram self.

pub fn increment(&mut self, x: f64, y: f64) -> Result<(), Value>

This function updates the histogram h by adding one (1.0) to the bin whose x and y ranges contain the coordinates (x,y).

If the point (x,y) lies inside the valid ranges of the histogram then the function returns zero to indicate success. If (x,y) lies outside the limits of the histogram then the function returns Value::Dom, and none of the bins are modified. The error handler is not called, since it is often necessary to compute histograms for a small range of a larger dataset, ignoring any coordinates outside the range of interest.

pub fn accumulate(&mut self, x: f64, y: f64, weight: f64) -> Result<(), Value>

This function is similar to gsl_histogram2d_increment but increases the value of the appropriate bin in the histogram h by the floating-point number weight.

pub fn get(&self, i: usize, j: usize) -> f64

This function returns the contents of the (i,j)-th bin of the histogram h. If (i,j) lies outside the valid range of indices for the histogram then the error handler is called with an error code of Value::Dom and the function returns 0.

pub fn xrange(&self, i: usize) -> Result<(f64, f64), Value>

This function finds the upper and lower range limits of the i-th and j-th bins in the x and y directions of the histogram h. The range limits are stored in xlower and xupper or ylower and yupper. The lower limits are inclusive (i.e. events with these coordinates are included in the bin) and the upper limits are exclusive (i.e. events with the value of the upper limit are not included and fall in the neighboring higher bin, if it exists). The functions return 0 to indicate success. If i or j lies outside the valid range of indices for the histogram then the error handler is called with an error code of Value::Dom.

Returns (xlower, xupper).

pub fn yrange(&self, j: usize) -> Result<(f64, f64), Value>

This function finds the upper and lower range limits of the i-th and j-th bins in the x and y directions of the histogram h. The range limits are stored in xlower and xupper or ylower and yupper. The lower limits are inclusive (i.e. events with these coordinates are included in the bin) and the upper limits are exclusive (i.e. events with the value of the upper limit are not included and fall in the neighboring higher bin, if it exists). The functions return 0 to indicate success. If i or j lies outside the valid range of indices for the histogram then the error handler is called with an error code of Value::Dom.

Returns (ylower, yupper).

pub fn xmax(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn xmin(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn nx(&self) -> usize

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn ymax(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn ymin(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn ny(&self) -> usize

This function returns the maximum upper and minimum lower range limits and the number of bins for the x and y directions of the histogram h. They provide a way of determining these values without accessing the gsl_histogram2d struct directly.

pub fn reset(&mut self)

This function resets all the bins of the histogram h to zero.

pub fn find(&self, x: f64, y: f64) -> Result<(usize, usize), Value>

This function finds and sets the indices i and j to the bin which covers the coordinates (x,y). The bin is located using a binary search. The search includes an optimization for histograms with uniform ranges, and will return the correct bin immediately in this case. If (x,y) is found then the function sets the indices (i,j) and returns crate::Value::Success. If (x,y) lies outside the valid range of the histogram then the function returns Value::Dom and the error handler is invoked.

Returns (i, j).

pub fn max_val(&self) -> f64

This function returns the maximum value contained in the histogram bins.

pub fn max_bin(&self) -> (usize, usize)

This function finds the indices of the bin containing the maximum value in the histogram h and stores the result in (i,j). In the case where several bins contain the same maximum value the first bin found is returned.

Returns (i, j).

pub fn min_val(&self) -> f64

This function returns the minimum value contained in the histogram bins.

pub fn min_bin(&self) -> (usize, usize)

This function finds the indices of the bin containing the minimum value in the histogram h and stores the result in (i,j). In the case where several bins contain the same maximum value the first bin found is returned.

Returns (i, j).

pub fn xmean(&self) -> f64

This function returns the mean of the histogrammed x variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

pub fn ymean(&self) -> f64

This function returns the mean of the histogrammed y variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

pub fn xsigma(&self) -> f64

This function returns the standard deviation of the histogrammed x variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

pub fn ysigma(&self) -> f64

This function returns the standard deviation of the histogrammed y variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

pub fn cov(&self) -> f64

This function returns the covariance of the histogrammed x and y variables, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

pub fn sum(&self) -> f64

This function returns the sum of all bin values. Negative bin values are included in the sum.

pub fn equal_bins_p(&self, other: &Histogram2D) -> bool

This function returns 1 if all the individual bin ranges of the two histograms are identical, and 0 otherwise.

pub fn add(&mut self, other: &Histogram2D) -> Result<(), Value>

This function adds the contents of the bins in histogram h2 to the corresponding bins of histogram h1, i.e. h’_1(i,j) = h_1(i,j)

• h_2(i,j). The two histograms must have identical bin ranges.

pub fn sub(&mut self, other: &Histogram2D) -> Result<(), Value>

This function subtracts the contents of the bins in histogram h2 from the corresponding bins of histogram h1, i.e. h’_1(i,j) = h_1(i,j)

• h_2(i,j). The two histograms must have identical bin ranges.

pub fn mul(&mut self, other: &Histogram2D) -> Result<(), Value>

This function multiplies the contents of the bins of histogram h1 by the contents of the corresponding bins in histogram h2, i.e. h’_1(i,j) = h_1(i,j) * h_2(i,j). The two histograms must have identical bin ranges.

pub fn div(&mut self, other: &Histogram2D) -> Result<(), Value>

This function divides the contents of the bins of histogram h1 by the contents of the corresponding bins in histogram h2, i.e. h’_1(i,j) = h_1(i,j) / h_2(i,j). The two histograms must have identical bin ranges.

pub fn scale(&mut self, scale: f64) -> Result<(), Value>

This function multiplies the contents of the bins of histogram h by the constant scale, i.e. h’_1(i,j) = h_1(i,j) scale.

pub fn shift(&mut self, offset: f64) -> Result<(), Value>

This function shifts the contents of the bins of histogram h by the constant offset, i.e. h’_1(i,j) = h_1(i,j) + offset.

Trait Implementations

impl Drop for Histogram2D

fn drop(&mut self)

Executes the destructor for this type.