boost_mirror/histogram
1
0
Fork 0
mirror of https://github.com/boostorg/histogram.git synced 2025-05-11 21:24:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

u

Browse Source
This commit is contained in:
Hans Dembinski 2017-10-13 18:34:17 +02:00
parent 71e4440b06
commit 929f44ffc0
1 changed files with 13 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/guide.qbk
View File

@ -4,13 +4,13 @@ How to create and work with histograms is described here. This library is design
[section Create a histogram]
This library provides a class with a simple interface, which implements a general multi-dimensional histogram for multi-dimensional input values. The histogram class comes in two variants with a common interface, see the [link histogram.rationale.histogram_types rationale] for more information. If you are unsure, pick the [classref boost::histogram::histogram<Static,...>]. You need [classref boost::histogram::histogram<Dynamic,...>] if...
This library provides a class with a simple interface, which implements a general multi-dimensional histogram for multi-dimensional input values. The histogram class comes in two variants with a common interface, see the [link histogram.rationale.histogram_types rationale] for more information. Using [classref boost::histogram::histogram<Static,...>] is recommended whenever possible. You need [classref boost::histogram::histogram<Dynamic,...>] if:
* you want to interoperate with Python, or
* you need to create histogram configurations based on input you only have at runtime
* you need a simple way to create various histogram configurations at runtime.
* you want to interoperate with Python
To create histograms in default configuration, use the factory function [funcref boost::histogram::make_static_histogram] (or [funcref boost::histogram::make_dynamic_histogram], respectively). The default configuration makes sure that the histogram just works. It is fast, memory-efficient, and safe to use.
Use the factory function [funcref boost::histogram::make_static_histogram] (or [funcref boost::histogram::make_dynamic_histogram], respectively) to make histograms with default options. The default options make sure that the histogram is safe to use, very fast, and memory efficient. If you are curious about changing these options, have a look at the expert section below.
[c++]``
#include <boost/histogram.hpp>
@ -27,7 +27,7 @@ int main() {
The function `make_static_histogram(...)` takes a variable number of axis objects as arguments. An axis object defines how input values are mapped to bins, which means that it defines the mapping function and the number bins. If you provide one axis, the histogram is one-dimensional. If you provide two, it is two-dimensional, and so on.
The library comes with a number of builtin axis classes (you can write your own, too, see [link histogram.concepts.axis_type axis concept]). Which one should you use? The [classref boost::histogram::axis::regular regular axis] should be your default choice, because it is easy to use and fast. If you have a continous range of integers, the [classref boost::histogram::axis::integer integer axis] is faster.
The library comes with a number of builtin axis classes (you can write your own, too, see [link histogram.concepts.axis_type axis concept]). The [classref boost::histogram::axis::regular regular axis] should be your default choice, because it is easy to use and fast. If you have a continous range of integers, the [classref boost::histogram::axis::integer integer axis] is faster. If you have data which wraps around, like angles, use a [classref boost::histogram::axis::circular circular axis].
Check the class descriptions of [classref boost::histogram::axis::regular regular axis], [classref boost::histogram::axis::variable variable axis], [classref boost::histogram::axis::circular circular axis], [classref boost::histogram::axis::integer integer axis], and [classref boost::histogram::axis::category category axis] for advice. See the [link histogram.rationale.axis_types rationale about axis types] for more information.
@ -47,9 +47,9 @@ int main() {
}
``
Without the labels it would be difficult to remember which axis was covering which quantity, as they or otherwise identical. To avoid errors, labels cannot be changed once the axis is passed in the constructor of the histogram. Axes objects which differ in their label do not compare equal with `operator==`.
Without the labels it would be difficult to remember which axis was covering which quantity. Beware, for safety reasons, labels cannot be changed once the axis is created. Axes objects which differ in their label do not compare equal with `operator==`.
By default, axis objects add under- and overflow bins to the covered range. Therefore, if you create an axis with 20 bins, it will actually get 22 bins. The two extra bins are very useful and in most cases you want to have them. However, if you know for sure that the input is strictly covered by the axis, you can disable them and save memory:
By default, under- and overflow bins are added automatically for each axis range. Therefore, if you create an axis with 20 bins, the histogram will actually have 22 bins in that dimension. The two extra bins are very useful and in most cases you want to have them. However, if you know for sure that the input is strictly covered by the axis, you can disable them and save memory:
[c++]``
#include <boost/histogram.hpp>
@ -191,4 +191,10 @@ The histogram can be serialized to disk for persistent storage from C++ and pick
[endsect]
[section Expert usage]
TODO
[endsect]
[endsect]