Reference documentation for deal.II version Git 78a8940608 2021-04-17 09:24:19 -0400
Histogram Class Reference

#include <deal.II/numerics/histogram.h>

struct  Interval

## Public Types

enum  IntervalSpacing { linear, logarithmic }

## Public Member Functions

template<typename number >
void evaluate (const std::vector< Vector< number >> &values, const std::vector< double > &y_values, const unsigned int n_intervals, const IntervalSpacing interval_spacing=linear)

template<typename number >
void evaluate (const Vector< number > &values, const unsigned int n_intervals, const IntervalSpacing interval_spacing=linear)

void write_gnuplot (std::ostream &out) const

std::size_t memory_consumption () const

## Static Public Member Functions

static std::string get_interval_spacing_names ()

static IntervalSpacing parse_interval_spacing (const std::string &name)

static ::ExceptionBaseExcEmptyData ()

static ::ExceptionBaseExcIncompatibleArraySize (int arg1, int arg2)

static ::ExceptionBaseExcInvalidName (std::string arg1)

## Static Private Member Functions

template<typename number >
static bool logarithmic_less (const number n1, const number n2)

## Private Attributes

std::vector< std::vector< Interval > > intervals

std::vector< doubley_values

## Detailed Description

This class provides some facilities to generate 2d and 3d histograms. It is used by giving it one or several data sets and a rule how to break the range of values therein into intervals (e.g. linear spacing or logarithmic spacing of intervals). The values are then sorted into the different intervals and the number of values in each interval is stored for output later. In case only one data set was given, the resulting histogram will be a 2d one, while it will be a 3d one if more than one data set was given. For more than one data set, the same intervals are used for each of them anyway, to make comparison easier.

### Ways to generate the intervals

At present, the following schemes for interval spacing are implemented:

• Linear spacing: The intervals are distributed in constant steps between the minimum and maximum values of the data.
• Logarithmic spacing: The intervals are distributed in constant steps between the minimum and maximum values of the logs of the values. This scheme is only useful if the data has only positive values. Negative and zero values are sorted into the leftmost interval.

To keep programs extensible, you can use the two functions get_interval_spacing_names and parse_interval_spacing, which always give you a complete list of spacing formats presently supported and are able to generate the respective value of the enum. If you use them, you can write your program in a way such that it only needs to be recompiled to take effect of newly added formats, without changing your code.

### Output formats

At present, only GNUPLOT output is supported.

Definition at line 71 of file histogram.h.

## ◆ IntervalSpacing

Definition of several ways to arrange the spacing of intervals.

Enumerator
linear

Space intervals linearly.

logarithmic

Space intervals logarithmically.

Definition at line 77 of file histogram.h.

## ◆ evaluate() [1/2]

template<typename number >
 void Histogram::evaluate ( const std::vector< Vector< number >> & values, const std::vector< double > & y_values, const unsigned int n_intervals, const IntervalSpacing interval_spacing = linear )

Take several lists of values, each on to produce one histogram that will then be arrange one behind each other.

Using several data sets at once allows to compare them more easily, since the intervals into which the data is sorted is the same for all data sets.

The histograms will be arranged such that the computed intervals of the values[i][j] form the x-range, and the number of values in each interval will be the y-range (for 2d plots) or the z-range (for 3d plots). For 3d plots, the y_values parameter is used to assign each data set a value in the y direction, which is the depth coordinate in the resulting plot. For 2d plots, the y_values are ignored.

If you give only one data set, i.e. values.size()==1, then the resulting histogram will be a 2d one.

n_intervals denotes the number of intervals into which the data will be sorted; interval_spacing denotes the way the bounds of the intervals are computed. Refer to the general documentation for more information on this.

Definition at line 56 of file histogram.cc.

## ◆ evaluate() [2/2]

template<typename number >
 void Histogram::evaluate ( const Vector< number > & values, const unsigned int n_intervals, const IntervalSpacing interval_spacing = linear )

This function is only a wrapper to the above one in case you have only one data set.

Definition at line 211 of file histogram.cc.

## ◆ write_gnuplot()

 void Histogram::write_gnuplot ( std::ostream & out ) const

Write the histogram computed by the evaluate function to a stream in a format suitable to the GNUPLOT program. The function generates 2d or 3d histograms.

Definition at line 225 of file histogram.cc.

## ◆ get_interval_spacing_names()

 std::string Histogram::get_interval_spacing_names ( )
static

Return allowed names for the interval spacing as string. At present this is "linear|logarithmic".

Definition at line 279 of file histogram.cc.

## ◆ parse_interval_spacing()

 Histogram::IntervalSpacing Histogram::parse_interval_spacing ( const std::string & name )
static

Get a string containing one of the names returned by the above function and return the respective value of IntervalSpacing. Throw an error if the string is no valid one.

Definition at line 287 of file histogram.cc.

## ◆ memory_consumption()

 std::size_t Histogram::memory_consumption ( ) const

Determine an estimate for the memory consumption (in bytes) of this object.

Definition at line 304 of file histogram.cc.

## ◆ logarithmic_less()

template<typename number >
 bool Histogram::logarithmic_less ( const number n1, const number n2 )
staticprivate

"Less-than" operation which finds the minimal positive value by sorting zero and negative value to be larger than the largest positive number. Used to find the lower bound of the leftmost interval in the logarithmic case interval spacing scheme.

Return true, if (n1<n2, and (n1>0 or n2<0)), or (n2<n1 and n1>0 and n2<=0). This in effect sorts all negative numbers to be larger than the largest positive number.

Definition at line 30 of file histogram.cc.

## ◆ intervals

 std::vector > Histogram::intervals
private

Vector holding one set of intervals for each data set given to the evaluate function.

Definition at line 235 of file histogram.h.

## ◆ y_values

 std::vector Histogram::y_values
private

Values for the depth axis of 3d histograms. Stored in the evaluate function.

Definition at line 241 of file histogram.h.

The documentation for this class was generated from the following files: