Struct rgsl::types::histograms::Histogram

pub struct Histogram { /* private fields */ }

Implementations

impl Histogram

pub fn new(n: usize) -> Option<Histogram>

This function allocates memory for a histogram with n bins, and returns a pointer to a newly created gsl_histogram 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 are not initialized, and should be prepared using one of the range-setting functions below in order to make the histogram ready for use.

pub fn set_ranges(&mut self, range: &[f64]) -> Value

This function sets the ranges of the existing histogram h using the array range of size size. The values of the histogram bins are reset to zero. The range array should contain the desired bin limits. The ranges can be arbitrary, subject to the restriction that they are monotonically increasing.

The following example shows how to create a histogram with logarithmic bins with ranges [1,10), [10,100) and [100,1000).

gsl_histogram * h = gsl_histogram_alloc (3);

/* bin[0] covers the range 1 <= x < 10 */
/* bin[1] covers the range 10 <= x < 100 */
/* bin[2] covers the range 100 <= x < 1000 */

double range[4] = { 1.0, 10.0, 100.0, 1000.0 };

gsl_histogram_set_ranges (h, range, 4);

Note that the size of the range array should be defined to be one element bigger than the number of bins. The additional element is required for the upper value of the final bin.

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

This function sets the ranges of the existing histogram h to cover the range xmin to xmax uniformly. The values of the histogram bins are reset to zero. The bin ranges are shown in the table below,

bin[0] corresponds to xmin <= x < xmin + d bin[1] corresponds to xmin + d <= x < xmin + 2 d …… bin[n-1] corresponds to xmin + (n-1)d <= x < xmax where d is the bin spacing, d = (xmax-xmin)/n.

pub fn copy(&self, dest: &mut Histogram) -> Value

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

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

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

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

This function updates the self histogram by adding one (1.0) to the bin whose range contains the coordinate x.

If x lies in the valid range of the histogram then the function returns zero to indicate success. If x is less than the lower limit of the histogram then the function returns Value::Dom, and none of bins are modified. Similarly, if the value of x is greater than or equal to the upper limit of the histogram then the function returns Value::Dom, and none of the bins are modified. The error handler is not called, however, since it is often necessary to compute histograms for a small range of a larger dataset, ignoring the values outside the range of interest.

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

This function is similar to gsl_histogram_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) -> f64

This function returns the contents of the i-th bin of the histogram h. If i 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 range(&self, i: usize) -> (Value, f64, f64)

This function finds the upper and lower range limits of the i-th bin of the self histogram. If the index i is valid then the corresponding range limits are stored in lower and upper. The lower limit is inclusive (i.e. events with this coordinate are included in the bin) and the upper limit is exclusive (i.e. events with the coordinate of the upper limit are excluded and fall in the neighboring higher bin, if it exists). The function returns 0 to indicate success. If i lies outside the valid range of indices for the histogram then the error handler is called and the function returns an error code of Value::Dom.

Returns (Value, lower, upper).

pub fn max(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins of the self histogram. They provide a way of determining these values without accessing the gsl_histogram struct directly.

pub fn min(&self) -> f64

This function returns the maximum upper and minimum lower range limits and the number of bins of the self histogram. They provide a way of determining these values without accessing the gsl_histogram struct directly.

pub fn bins(&self) -> usize

This function returns the maximum upper and minimum lower range limits and the number of bins of the self histogram. They provide a way of determining these values without accessing the gsl_histogram struct directly.

pub fn reset(&mut self)

This function resets all the bins in the self histogram to zero.

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

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

Returns (Value, i).

pub fn max_val(&self) -> f64

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

pub fn max_bin(&self) -> usize

This function returns the index of the bin containing the maximum value. In the case where several bins contain the same maximum value the smallest index is returned.

pub fn min_val(&self) -> f64

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

pub fn min_bin(&self) -> usize

This function returns the index of the bin containing the minimum value. In the case where several bins contain the same maximum value the smallest index is returned.

pub fn mean(&self) -> f64

This function returns the mean of the histogrammed variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation. The accuracy of the result is limited by the bin width.

pub fn sigma(&self) -> f64

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

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: &Histogram) -> bool

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

pub fn add(&mut self, other: &Histogram) -> Value

This function adds the contents of the bins in histogram other to the corresponding bins of self histogram, i.e. h’_1(i) = h_1(i) + h_2(i). The two histograms must have identical bin ranges.

pub fn sub(&mut self, other: &Histogram) -> Value

This function subtracts the contents of the bins in histogram other from the corresponding bins of self histogram, i.e. h’_1(i) = h_1(i) - h_2(i). The two histograms must have identical bin ranges.

pub fn mul(&mut self, other: &Histogram) -> Value

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

pub fn div(&mut self, other: &Histogram) -> Value

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

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

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

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

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

pub fn print<W: Write>(&self, stream: &mut W) -> Result<Value>

Trait Implementations

impl Drop for Histogram

fn drop(&mut self)

Executes the destructor for this type.