Struct rgsl::types::histograms::Histogram2D

pub struct Histogram2D { /* fields omitted */ }

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).

Methods

impl Histogram2D

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.

fn set_ranges(&mut self, xrange: &[f64], yrange: &[f64]) -> 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.

fn set_ranges_uniform(
    &mut self,
    xmin: f64,
    xmax: f64,
    ymin: f64,
    ymax: f64
) -> 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.

fn copy(&self, dest: &mut Histogram2D) -> 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.

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

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

fn increment(&mut self, x: f64, y: f64) -> 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.

fn accumulate(&mut self, x: f64, y: f64, weight: f64) -> 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.

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.

fn get_xrange(&self, i: usize, xlower: &mut f64, xupper: &mut 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.

fn get_yrange(&self, j: usize, ylower: &mut f64, yupper: &mut 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.

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.

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.

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.

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.

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.

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.

fn reset(&mut self)

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

fn find(&self, x: f64, y: f64, i: &mut usize, j: &mut 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 ::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.

fn max_val(&self) -> f64

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

fn max_bin(&self, i: &mut usize, j: &mut 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.

fn min_val(&self) -> f64

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

fn min_bin(&self, i: &mut usize, j: &mut 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.

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.

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.

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.

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.

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.

fn sum(&self) -> f64

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

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.

fn add(&mut self, other: &Histogram2D) -> 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.

fn sub(&mut self, other: &Histogram2D) -> 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.

fn mul(&mut self, other: &Histogram2D) -> 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.

fn div(&mut self, other: &Histogram2D) -> 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.

fn scale(&mut self, scale: f64) -> 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.

fn shift(&mut self, offset: f64) -> 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)

A method called when the value goes out of scope.