#include <histogram.h>
Inheritance diagram for Histo::OneDBinList< Count, Value >:
This class is designed to include some classes which are not, strictly speaking, histograms, e.g. if their total counts are less than the sum of the individual counts, or if individual counts are less than zero.
Definition at line 37 of file histogram.h.
Summary access functions | |
| Report statistics about the whole histogram. | |
| size_type | num_bins () const |
| Value | sum_value () const |
| The sum of the current values. | |
| Count | sum_count () const |
| The sum of the current counts. | |
| Value | average_value () const |
| The arithmetic mean of the current values. | |
| Value | max_value () const |
| The largest value() of any bin. | |
| Value | min_value () const |
| Count | max_count () const |
| Count | min_count () const |
| size_type | max_value_bin () const |
| The bin_number with the largest value. | |
| Magnitude | relative_selectivity () const |
| Returns value(max_value_bin()) as a proportion of the sum_value(), scaled to 0.0 to 1.0. | |
| Value | weighted_sum () const |
| Returns the sum of each value times its bin number. | |
| Magnitude | weighted_average () const |
| Returns the average bin_number as a number from 0.0 to 1.0, weighting each bin by its value. | |
| Value | total_value () const |
| The sum of all of the values ever provided for each bin. | |
| Count | total_count () const |
| The total number of values that have ever been provided for each bin. | |
| size_type | undefined_values () |
| Returns the number of times that undefined values have been returned from calculations for any instance of this class, e.g. | |
| void | undefined_values_reset (size_type val=0) |
Public Types | |
|
typedef std::vector< Value >::size_type | size_type |
| typedef Value | value_type |
| typedef Bounded::Magnitude | Magnitude |
| A value whose nominal range is 0..1.0. | |
| typedef std::complex< Value > | Vector |
| For vector averages; complex acts like a geometrical vector and is universally available so it is used here. | |
Public Methods | |
| OneDBinList (const size_type num_bins=num_bins_default) | |
| To avoid divide-by-zero errors in various member functions, requires that num_bins>0. | |
| OneDBinList & | add (size_type bin, Value val=1) |
| Add the specified value to the histogram bin specified. | |
| OneDBinList & | keep_peak (size_type bin, Value val) |
| Store the given value as the value for the given bin if it's the highest value seen so far. | |
Vector summary functions | |
Summary functions computed from the vector_sum(). | |
| Vector | vector_sum () const |
| Returns the vector sum of all the values indexed by their bin_number. | |
| Vector | vector_average () const |
| Returns the vector_average of all the values indexed by their bin_number, i.e. | |
| Magnitude | vector_direction () const |
| Returns the direction of the vector_sum() on a scale from 0 to 1.0. | |
| Magnitude | vector_selectivity () const |
| Returns abs(vector_sum())/sum_value(), i.e. | |
Element access functions | |
Return the value of a single bin in the histogram.
The _mag functions return the value as a portion of the total_value() or total_count(). | |
| Value | value (size_type i) const |
| Count | count (size_type i) const |
| Magnitude | value_mag (size_type i) const |
| Magnitude | count_mag (size_type i) const |
| Magnitude | relative_value (size_type bin) const |
| Returns the value of the given bin as a proportion of the sum_value(). | |
Helper functions | |
| size_type | bin_number (Magnitude binmag) |
| Converts a binmag (a value from 0 to 1.0) into the corresponding bin_number, assuming an exclusive upper bound. | |
| size_type | bin_number_inclusive (Magnitude binmag) |
| Converts a binmag (a value from 0 to 1.0) into the corresponding bin_number, assuming an inclusive upper bound. | |
| Magnitude | bin_mag (size_type bin) |
| Converts an integer bin_number into the corresponding Magnitude, a number from 0 to 1.0. | |
Static Public Attributes | |
| size_type | num_bins_default = 1 |
| Arbitrary default value. | |
Protected Attributes | |
| std::vector< Count > | counts |
| std::vector< Value > | values |
| Count | total_c |
| Value | total_v |
Friends | |
| template<class C, class V> OneDBinList< C, V > | operator- (const OneDBinList< C, V > &A, const OneDBinList< C, V > &B) |
|
||||||||||
|
Converts a binmag (a value from 0 to 1.0) into the corresponding bin_number, assuming an exclusive upper bound. (I.e., assumes that the highest bin number corresponds to 1.0-(1/num_bins()) instead of 1.0). A tiny constant float_adjust is added to the binmag after the binmag is scaled into the range num_bins(), to correct for any floating-point truncation errors during previous calculations. Such errors can be significant for binmags that were originally integer bin values (e.g. bin 1 out of 3), because when they are transformed back into bin_values here, any slight floating-point error can cause a full bin's worth of error (e.g. choosing bin 0 instead of bin 1). For any num_bins() likely to fit into memory there should be no effect on the accuracy for magnitudes arising from other, continuous sources. Definition at line 329 of file histogram.h. References Generic::crop(). |
|
||||||||||
|
Converts a binmag (a value from 0 to 1.0) into the corresponding bin_number, assuming an inclusive upper bound. (I.e., assumes that the highest bin number corresponds to 1.0 instead of 1.0-(1/num_bins())). See bin_number(). Definition at line 339 of file histogram.h. References Generic::crop(). |
|
||||||||||||||||
|
Store the given value as the value for the given bin if it's the highest value seen so far. Useful for maintaining a distribution of maxiumum values for different bins, as opposed to the summations typical to histogram bins. Note that each call will increase the total_value() and total_count() (and thus decrease the value_mag() and count_mag()) even if the value doesn't happen to be the maximum seen so far, since each data point still helps improve the sampling and thus the confidence. Definition at line 93 of file histogram.h. |
|
|||||||||
|
Returns value(max_value_bin()) as a proportion of the sum_value(), scaled to 0.0 to 1.0. This quantity is a measure of the how strongly the histogram is biased towards the max_value_bin(). For smooth, single-lobed distributions with an inclusive, non-cyclic range, this quantity is an analog to vector_selectivity. To be a precise analog for arbitrary distributions, it would need to compute some measure of the selectivity that works like the weighted_average() instead of the max_value_bin(). The scaling is such that if all bins are identical, the selectivity is 0.0, and if all bins but one are zero, the selectivity is 1.0. Definition at line 155 of file histogram.h. References Generic::crop(), Histo::OneDBinList< Count, Value >::Magnitude, Bounded::Magnitude, Histo::OneDBinList< Count, Value >::max_value_bin(), and Histo::OneDBinList< Count, Value >::sum_value(). |
|
||||||||||
|
Returns the value of the given bin as a proportion of the sum_value(). This quantity is on a scale from 0.0 (the specified bin is zero and others are nonzero) to 1.0 (the specified bin is the only nonzero bin). If the histogram is empty the result is undefined; in such a case zero is returned and the value returned by undefined_values() is incremented. Definition at line 306 of file histogram.h. References Bounded::Magnitude, and Histo::OneDBinList< Count, Value >::sum_value(). |
|
|||||||||
|
The sum of the current values. The result is cached when first computed, and the cached value is used unless the total_count() changes (i.e. unless new values have been added since the sum was computed.) Thus this routine may be called multiple times, e.g. for computation of other quantities such as average_value(), with no performance penalty. Definition at line 116 of file histogram.h. References ISEQ, and Histo::OneDBinList< Count, Value >::total_count(). Referenced by Histo::OneDBinList< Count, Value >::average_value(), Histo::OneDBinList< Count, Value >::relative_selectivity(), Histo::OneDBinList< Count, Value >::relative_value(), Histo::OneDBinList< Count, Value >::vector_selectivity(), and Histo::OneDBinList< Count, Value >::weighted_average(). |
|
|||||||||
|
The total number of values that have ever been provided for each bin. For a simple histogram this will be the same as sum_counts(), but for other OneDBinList types it often differs. Definition at line 198 of file histogram.h. Referenced by Histo::OneDBinList< Count, Value >::sum_value(), and Histo::OneDBinList< Count, Value >::vector_sum(). |
|
|||||||||
|
The sum of all of the values ever provided for each bin. For a simple histogram this will be the same as sum_value(), but for other OneDBinList types it often differs from sum_value(). Definition at line 192 of file histogram.h. |
|
|||||||||
|
Returns the number of times that undefined values have been returned from calculations for any instance of this class, e.g. calls to vector_direction() or vector_selectivity() when no value is non-zero. Useful for warning users when the values are not meaningful. Definition at line 186 of file histogram.h. |
|
|||||||||
|
Returns the vector_average of all the values indexed by their bin_number, i.e. the vector_sum()/num_bins(). Definition at line 242 of file histogram.h. References Histo::OneDBinList< Count, Value >::vector_sum(). |
|
|||||||||
|
Returns the direction of the vector_sum() on a scale from 0 to 1.0. This quantity is a continuous measure of the max_value_bin() of the distribution, assuming the distribution wraps around from the high bin to the low bin. It has more precision than the bin_number of the peak (i.e. bin_mag(max_value_bin())) because it is computed from the entire distribution instead of just the bin_number of the peak bin. However, it requires uniform sampling for correct results, which is not always possible. The vector_direction() is not meaningful when abs(vector_sum())==0, since a zero-length vector has no direction. To find out whether such cases occurred, you can compare the value of undefined_values() before and after a series of calls to this function. Definition at line 260 of file histogram.h. References Bounded::Magnitude, Histo::OneDBinList< Count, Value >::vector_sum(), and Generic::wrap(). |
|
|||||||||
|
Returns abs(vector_sum())/sum_value(), i.e. the ratio of the length of the vector sum to the sum of the vector lengths. This is a vector-based measure of the peakedness of the histogram. If only a single bin has a non-zero value(), the selectivity will be 1.0, and if all bins have the same value() then the selectivity will be 0.0. Other distributions will result in intermediate values. For a histogram with a sum_value() of zero (i.e. all bins empty), the selectivity is undefined. Assuming that one will usually be looking for high selectivity, we return zero in such a case so that high selectivity will not mistakenly be claimed. To find out whether such cases occurred, you can compare the value of undefined_values() before and after a series of calls to this function. Definition at line 281 of file histogram.h. References Bounded::Magnitude, Histo::OneDBinList< Count, Value >::sum_value(), and Histo::OneDBinList< Count, Value >::vector_sum(). |
|
|||||||||
|
Returns the vector sum of all the values indexed by their bin_number. A vector is constructed from each bin: the length is the value() of the bin, and the angle is the bin_number as a percentage of a circle, i.e. 2*PI*bin_number()/num_bins(). The result is cached when first computed, and the cached value is used unless the total_count() changes (i.e. unless new values have been added since the sum was computed.) Thus this routine may be called multiple times, e.g. for the other vector quantities such as vector_average(), with no performance penalty. Definition at line 220 of file histogram.h. References ISEQ, Histo::OneDBinList< Count, Value >::total_count(), and Histo::OneDBinList< Count, Value >::Vector. Referenced by Histo::OneDBinList< Count, Value >::vector_average(), Histo::OneDBinList< Count, Value >::vector_direction(), and Histo::OneDBinList< Count, Value >::vector_selectivity(). |
|
|||||||||
|
Returns the average bin_number as a number from 0.0 to 1.0, weighting each bin by its value. This quantity is a continuous measure of the max_value_bin() of the distribution for a non-wrapping distribution, i.e. one whose upper and lower bounds are distinct. Definition at line 177 of file histogram.h. References Bounded::Magnitude, Histo::OneDBinList< Count, Value >::sum_value(), and Histo::OneDBinList< Count, Value >::weighted_sum(). |
1.3-rc2