Struct Histogram 

pub struct Histogram { /* private fields */ }

A simple weighted histogram with explicit bin edges.

Implementations

impl Histogram

pub fn new(counts: Vec<f64>, bin_edges: Vec<f64>) -> LadduPhysicsResult<Self>

Construct and validate a histogram from weighted bin counts and bin edges.

The argument order matches numpy.histogram, so its result can be forwarded directly.

Errors

Returns LadduPhysicsError when counts or edges are non-finite, the edge count is inconsistent with the bins, or edges are not increasing.

pub fn new_with_flow( counts: Vec<f64>, bin_edges: Vec<f64>, underflow: f64, overflow: f64, ) -> LadduPhysicsResult<Self>

Construct a histogram including explicit underflow and overflow weights.

Errors

Returns LadduPhysicsError when counts, flow weights, or edges are non-finite, lengths are inconsistent, or edges are not increasing.

pub fn empty(bins: usize, limits: (f64, f64)) -> LadduPhysicsResult<Self>

Construct an empty, uniformly binned histogram.

Errors

Returns LadduPhysicsError when bins is zero or the limits are non-finite or not increasing.

pub fn empty_with_edges(bin_edges: Vec<f64>) -> LadduPhysicsResult<Self>

Construct an empty histogram from explicit bin edges.

Errors

Returns LadduPhysicsError when fewer than two finite, strictly increasing edges are supplied.

pub fn from_values( values: &[f64], bins: usize, limits: (f64, f64), weights: Option<&[f64]>, ) -> LadduPhysicsResult<Self>

Fill a uniformly binned histogram from values and optional weights.

Errors

Returns LadduPhysicsError when histogram geometry is invalid, weights have the wrong length, or a value or weight is non-finite.

pub fn from_values_with_edges( values: &[f64], bin_edges: Vec<f64>, weights: Option<&[f64]>, ) -> LadduPhysicsResult<Self>

Fill an explicitly binned histogram from values and optional weights.

Errors

Returns LadduPhysicsError when edges are invalid, weights have the wrong length, or a value or weight is non-finite.

pub fn set_errors(&mut self, errors: &[f64]) -> LadduPhysicsResult<()>

Replace the uncertainties on all bins.

Errors

Returns LadduPhysicsError when errors has the wrong length or contains a negative or non-finite uncertainty.

pub fn fill(&mut self, value: f64) -> LadduPhysicsResult<()>

Add one unit-weight entry.

Errors

Returns LadduPhysicsError when value is non-finite.

pub fn fill_weighted( &mut self, value: f64, weight: f64, ) -> LadduPhysicsResult<()>

Add an entry with an explicit weight.

Errors

Returns LadduPhysicsError when value or weight is non-finite.

Panics

Panics if this histogram’s validated edge list is unexpectedly empty.

pub fn fill_with_error( &mut self, value: f64, error: f64, ) -> LadduPhysicsResult<()>

Add one unit-weight entry with the given entry uncertainty.

Errors

Returns LadduPhysicsError when value is non-finite or error is negative or non-finite.

pub fn fill_weighted_with_error( &mut self, value: f64, weight: f64, error: f64, ) -> LadduPhysicsResult<()>

Add an entry with an explicit weight and uncertainty.

Errors

Returns LadduPhysicsError when value or weight is non-finite, or error is negative or non-finite.

Panics

Panics if this histogram’s validated edge list is unexpectedly empty.

pub fn counts(&self) -> &[f64]

Return the number of weighted counts in each bin.

pub fn set_counts(&mut self, counts: &[f64]) -> LadduPhysicsResult<()>

Replace the contents of all bins without changing their uncertainties.

Errors

Returns LadduPhysicsError when counts has the wrong length or contains a non-finite value.

pub fn set_count( &mut self, bin_index: usize, value: f64, ) -> LadduPhysicsResult<()>

Manually set the counts in a bin.

Errors

Returns LadduPhysicsError when bin_index is out of range or value is non-finite.

pub fn set_error( &mut self, bin_index: usize, error: f64, ) -> LadduPhysicsResult<()>

Manually set the uncertainty in a bin.

Errors

Returns LadduPhysicsError when bin_index is out of range or error is negative or non-finite.

pub fn errors(&self) -> &[f64]

Return the uncertainties on each bin.

Note

Histograms filled from values use the square root of the sum of squared weights. Histograms constructed from counts default to sqrt(abs(count)).

pub fn bin_edges(&self) -> &[f64]

Return the bin edges.

pub fn underflow(&self) -> f64

Return the accumulated underflow weight.

pub fn overflow(&self) -> f64

Return the accumulated overflow weight.

pub fn total_weight(&self) -> f64

Return the total histogram weight.

pub fn total_weight_with_flow(&self) -> f64

Return total weight including underflow and overflow.

pub fn limits(&self) -> (f64, f64)

Return the lowest and highest bin edges.

pub fn bins(&self) -> usize

Return the number of bins.

pub fn bin_index(&self, value: f64) -> Option<usize>

Return the bin index for a value.

The lower edge is inclusive and the upper edge is exclusive.

pub fn normalized(&self) -> LadduPhysicsResult<Self>

Return a normalized histogram whose in-range bin counts sum to 1.

Underflow and overflow are discarded because they are outside the histogram domain.

Negative bin counts are allowed, so this is an algebraic normalization, not necessarily a probability distribution.

Errors

Returns LadduPhysicsError when the histogram is invalid or has zero or non-finite in-range total weight.

pub fn normalized_with_flow(&self) -> LadduPhysicsResult<Self>

Return a normalized histogram whose bins plus underflow/overflow sum to 1.

Negative counts are allowed, so this is algebraic normalization, not necessarily a probability distribution.

Errors

Returns LadduPhysicsError when the histogram is invalid or has zero or non-finite total weight including flow bins.

pub fn density(&self) -> LadduPhysicsResult<Self>

Return a probability density histogram.

Requires nonnegative in-range counts. Underflow and overflow are discarded because they do not have finite bin widths.

Errors

Returns LadduPhysicsError when bin counts are negative or non-finite, or their in-range total is not positive and finite.

pub fn signed_density(&self) -> LadduPhysicsResult<Self>

Return a signed density histogram.

This allows negative weights and is useful for weighted MC, interference terms, or background-subtracted histograms. It should not be sampled from.

Errors

Returns LadduPhysicsError when the histogram is invalid or has zero or non-finite in-range total weight.

pub fn sample(&self, rng: &mut Rng) -> LadduPhysicsResult<f64>

Sample a value from the histogram, assuming counts define bin probabilities.

Samples uniformly within the selected bin.

Errors

Returns LadduPhysicsError when counts are negative or non-finite, or their total is not positive and finite.

pub fn bin_center(&self, index: usize) -> Option<f64>

Return the center of a bin.

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Histogram

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Histogram

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Histogram

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Histogram

fn eq(&self, other: &Histogram) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Histogram

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Histogram