libs/histogram/doc/html/histogram/getting_started.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Getting started</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Histogram">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Histogram">
   9 <link rel="prev" href="overview.html" title="Overview">
  10 <link rel="next" href="guide.html" title="User guide">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="overview.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="guide.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="histogram.getting_started"></a><a class="link" href="getting_started.html" title="Getting started">Getting started</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="getting_started.html#histogram.getting_started.1d_histogram_with_axis_types_kno">1d-histogram
  31       with axis types known at compile-time</a></span></dt>
  32 <dt><span class="section"><a href="getting_started.html#histogram.getting_started.3d_histogram_axis_configuration_">3d-histogram
  33       (axis configuration defined at run-time)</a></span></dt>
  34 <dt><span class="section"><a href="getting_started.html#histogram.getting_started.1d_profile">1d-profile</a></span></dt>
  35 <dt><span class="section"><a href="getting_started.html#histogram.getting_started.standard_library_algorithms">Standard
  36       library algorithms</a></span></dt>
  37 </dl></div>
  38 <p>
  39       Here are some commented examples to copy-paste from, this should allow you
  40       to kick off a project with Boost.Histogram. If you prefer a traditional structured
  41       exposition, go to the <a class="link" href="guide.html" title="User guide">user guide</a>.
  42     </p>
  43 <p>
  44       Boost.Histogram uses <span class="emphasis"><em>axis</em></span> objects to convert input values
  45       into indices. The library comes with several builtin axis types, which can
  46       be configured via template parameters. This already gives you a lot of flexibility
  47       should you need it, otherwise just use the defaults. Beyond that, you can easily
  48       write your own axis type.
  49     </p>
  50 <div class="section">
  51 <div class="titlepage"><div><div><h3 class="title">
  52 <a name="histogram.getting_started.1d_histogram_with_axis_types_kno"></a><a class="link" href="getting_started.html#histogram.getting_started.1d_histogram_with_axis_types_kno" title="1d-histogram with axis types known at compile-time">1d-histogram
  53       with axis types known at compile-time</a>
  54 </h3></div></div></div>
  55 <p>
  56         When the axis types for the histogram are known at compile-time, the library
  57         generates the fastest and most efficient code for you. Here is such an example.
  58       </p>
  59 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span>           <span class="comment">// std::for_each</span>
  60 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">format</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>    <span class="comment">// only needed for printing</span>
  61 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// make_histogram, regular, weight, indexed</span>
  62 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>             <span class="comment">// assert (used to test this example for correctness)</span>
  63 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>          <span class="comment">// std::ref</span>
  64 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>            <span class="comment">// std::cout, std::flush</span>
  65 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>             <span class="comment">// std::ostringstream</span>
  66
  67 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
  68   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">histogram</span><span class="special">;</span> <span class="comment">// strip the boost::histogram prefix</span>
  69
  70   <span class="comment">/*
  71     Create a 1d-histogram with a regular axis that has 6 equidistant bins on
  72     the real line from -1.0 to 2.0, and label it as "x". A family of overloaded
  73     factory functions called `make_histogram` makes creating histograms easy.
  74
  75     A regular axis is a sequence of semi-open bins. Extra under- and overflow
  76     bins extend the axis by default (this can be turned off).
  77
  78     index    :      -1  |  0  |  1  |  2  |  3  |  4  |  5  |  6
  79     bin edges:  -inf  -1.0  -0.5   0.0   0.5   1.0   1.5   2.0   inf
  80   */</span>
  81   <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram</span><span class="special">(</span><span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;(</span><span class="number">6</span><span class="special">,</span> <span class="special">-</span><span class="number">1.0</span><span class="special">,</span> <span class="number">2.0</span><span class="special">,</span> <span class="string">"x"</span><span class="special">));</span>
  82
  83   <span class="comment">/*
  84     Let's fill a histogram with data, typically this happens in a loop.
  85
  86     STL algorithms are supported. std::for_each is very convenient to fill a
  87     histogram from an iterator range. Use std::ref in the call, if you don't
  88     want std::for_each to make a copy of your histogram.
  89   */</span>
  90   <span class="keyword">auto</span> <span class="identifier">data</span> <span class="special">=</span> <span class="special">{-</span><span class="number">0.5</span><span class="special">,</span> <span class="number">1.1</span><span class="special">,</span> <span class="number">0.3</span><span class="special">,</span> <span class="number">1.7</span><span class="special">};</span>
  91   <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">data</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">h</span><span class="special">));</span>
  92   <span class="comment">// let's fill some more values manually</span>
  93   <span class="identifier">h</span><span class="special">(-</span><span class="number">1.5</span><span class="special">);</span> <span class="comment">// is placed in underflow bin -1</span>
  94   <span class="identifier">h</span><span class="special">(-</span><span class="number">1.0</span><span class="special">);</span> <span class="comment">// is placed in bin 0, bin interval is semi-open</span>
  95   <span class="identifier">h</span><span class="special">(</span><span class="number">2.0</span><span class="special">);</span>  <span class="comment">// is placed in overflow bin 6, bin interval is semi-open</span>
  96   <span class="identifier">h</span><span class="special">(</span><span class="number">20.0</span><span class="special">);</span> <span class="comment">// is placed in overflow bin 6</span>
  97
  98   <span class="comment">/*
  99     This does a weighted fill using the `weight` function as an additional
 100     argument. It may appear at the beginning or end of the argument list. C++
 101     doesn't have keyword arguments like Python, this is the next-best thing.
 102   */</span>
 103   <span class="identifier">h</span><span class="special">(</span><span class="number">0.1</span><span class="special">,</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">1.0</span><span class="special">));</span>
 104
 105   <span class="comment">/*
 106     Iterate over bins with the `indexed` range generator, which provides a
 107     special accessor object, that can be used to obtain the current bin index,
 108     and the current bin value by dereferncing (it acts like a pointer to the
 109     value). Using `indexed` is convenient and gives you better performance than
 110     looping over the histogram cells with hand-written for loops. By default,
 111     under- and overflow bins are skipped. Passing `coverage::all` as the
 112     optional second argument iterates over all bins.
 113
 114     - Access the value with the dereference operator.
 115     - Access the current index with `index(d)` method of the accessor.
 116     - Access the corresponding bin interval view with `bin(d)`.
 117
 118     The return type of `bin(d)` depends on the axis type (see the axis reference
 119     for details). It usually is a class that represents a semi-open interval.
 120     Edges can be accessed with methods `lower()` and `upper()`.
 121   */</span>
 122
 123   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
 124   <span class="keyword">for</span> <span class="special">(</span><span class="keyword">auto</span><span class="special">&amp;&amp;</span> <span class="identifier">x</span> <span class="special">:</span> <span class="identifier">indexed</span><span class="special">(</span><span class="identifier">h</span><span class="special">,</span> <span class="identifier">coverage</span><span class="special">::</span><span class="identifier">all</span><span class="special">))</span> <span class="special">{</span>
 125     <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="string">"bin %2i [%4.1f, %4.1f): %i\n"</span><span class="special">)</span>
 126           <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">().</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">().</span><span class="identifier">upper</span><span class="special">()</span> <span class="special">%</span> <span class="special">*</span><span class="identifier">x</span><span class="special">;</span>
 127   <span class="special">}</span>
 128
 129   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">flush</span><span class="special">;</span>
 130
 131   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"bin -1 [-inf, -1.0): 1\n"</span>
 132                      <span class="string">"bin  0 [-1.0, -0.5): 1\n"</span>
 133                      <span class="string">"bin  1 [-0.5, -0.0): 1\n"</span>
 134                      <span class="string">"bin  2 [-0.0,  0.5): 2\n"</span>
 135                      <span class="string">"bin  3 [ 0.5,  1.0): 0\n"</span>
 136                      <span class="string">"bin  4 [ 1.0,  1.5): 1\n"</span>
 137                      <span class="string">"bin  5 [ 1.5,  2.0): 1\n"</span>
 138                      <span class="string">"bin  6 [ 2.0,  inf): 2\n"</span><span class="special">);</span>
 139 <span class="special">}</span>
 140 </pre>
 141 <p>
 142         We passed the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code>
 143         axis type directly to the <code class="computeroutput"><a class="link" href="reference.html#header.boost.histogram.make_histogram_hpp" title="Header &lt;boost/histogram/make_histogram.hpp&gt;">make_histogram</a></code>
 144         function. The library then generates a specialized histogram type with just
 145         one regular axis from a generic template.
 146       </p>
 147 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 148 <li class="listitem">
 149             Pro: Many user errors are already caught at compile-time, not at run-time.
 150           </li>
 151 <li class="listitem">
 152             Con: You get template errors if you make a mistake, which may be hard
 153             to read. We try to give you useful error messages, but still.
 154           </li>
 155 </ul></div>
 156 </div>
 157 <div class="section">
 158 <div class="titlepage"><div><div><h3 class="title">
 159 <a name="histogram.getting_started.3d_histogram_axis_configuration_"></a><a class="link" href="getting_started.html#histogram.getting_started.3d_histogram_axis_configuration_" title="3d-histogram (axis configuration defined at run-time)">3d-histogram
 160       (axis configuration defined at run-time)</a>
 161 </h3></div></div></div>
 162 <p>
 163         Sometimes, you don't know the number or types of axes at compile-time, because
 164         it depends on run-time information. Perhaps you want to write a command-line
 165         tool that generates histograms from input data, or you use this library as
 166         a back-end for a product with a GUI. This is possible as well, here is the
 167         example.
 168       </p>
 169 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">format</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 170 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 171 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 172 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 173 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
 174 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
 175
 176 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
 177   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">histogram</span><span class="special">;</span>
 178
 179   <span class="comment">/*
 180     Create a histogram which can be configured dynamically at run-time. The axis
 181     configuration is first collected in a vector of axis::variant type, which
 182     can hold different axis types (those in its template argument list). Here,
 183     we use a variant that can store a regular and a category axis.
 184   */</span>
 185   <span class="keyword">using</span> <span class="identifier">reg</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;;</span>
 186   <span class="keyword">using</span> <span class="identifier">cat</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">category</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;;</span>
 187   <span class="keyword">using</span> <span class="identifier">variant</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;,</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">category</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;&gt;;</span>
 188   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">variant</span><span class="special">&gt;</span> <span class="identifier">axes</span><span class="special">;</span>
 189   <span class="identifier">axes</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="identifier">cat</span><span class="special">({</span><span class="string">"red"</span><span class="special">,</span> <span class="string">"blue"</span><span class="special">}));</span>
 190   <span class="identifier">axes</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="identifier">reg</span><span class="special">(</span><span class="number">3</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="string">"x"</span><span class="special">));</span>
 191   <span class="identifier">axes</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="identifier">reg</span><span class="special">(</span><span class="number">3</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="string">"y"</span><span class="special">));</span>
 192   <span class="comment">// passing an iterator range also works here</span>
 193   <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">axes</span><span class="special">));</span>
 194
 195   <span class="comment">// fill histogram with data, usually this happens in a loop</span>
 196   <span class="identifier">h</span><span class="special">(</span><span class="string">"red"</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.2</span><span class="special">);</span>
 197   <span class="identifier">h</span><span class="special">(</span><span class="string">"blue"</span><span class="special">,</span> <span class="number">0.7</span><span class="special">,</span> <span class="number">0.3</span><span class="special">);</span>
 198   <span class="identifier">h</span><span class="special">(</span><span class="string">"red"</span><span class="special">,</span> <span class="number">0.3</span><span class="special">,</span> <span class="number">0.7</span><span class="special">);</span>
 199   <span class="identifier">h</span><span class="special">(</span><span class="string">"red"</span><span class="special">,</span> <span class="number">0.7</span><span class="special">,</span> <span class="number">0.7</span><span class="special">);</span>
 200
 201   <span class="comment">/*
 202     Print histogram by iterating over bins.
 203     Since the [bin type] of the category axis cannot be converted into a double,
 204     it cannot be handled by the polymorphic interface of axis::variant. We use
 205     axis::get to "cast" the variant type to the actual category type.
 206   */</span>
 207
 208   <span class="comment">// get reference to category axis, performs a run-time checked static cast</span>
 209   <span class="keyword">const</span> <span class="keyword">auto</span><span class="special">&amp;</span> <span class="identifier">cat_axis</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">cat</span><span class="special">&gt;(</span><span class="identifier">h</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">0</span><span class="special">));</span>
 210   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
 211   <span class="keyword">for</span> <span class="special">(</span><span class="keyword">auto</span><span class="special">&amp;&amp;</span> <span class="identifier">x</span> <span class="special">:</span> <span class="identifier">indexed</span><span class="special">(</span><span class="identifier">h</span><span class="special">))</span> <span class="special">{</span>
 212     <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="string">"(%i, %i, %i) %4s [%3.1f, %3.1f) [%3.1f, %3.1f) %3.0f\n"</span><span class="special">)</span>
 213           <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">2</span><span class="special">)</span>
 214           <span class="special">%</span> <span class="identifier">cat_axis</span><span class="special">.</span><span class="identifier">bin</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">0</span><span class="special">))</span>
 215           <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">(</span><span class="number">1</span><span class="special">).</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">(</span><span class="number">1</span><span class="special">).</span><span class="identifier">upper</span><span class="special">()</span>
 216           <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">(</span><span class="number">2</span><span class="special">).</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">(</span><span class="number">2</span><span class="special">).</span><span class="identifier">upper</span><span class="special">()</span>
 217           <span class="special">%</span> <span class="special">*</span><span class="identifier">x</span><span class="special">;</span>
 218   <span class="special">}</span>
 219
 220   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">flush</span><span class="special">;</span>
 221   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"(0, 0, 0)  red [0.0, 0.3) [0.0, 0.3)   1\n"</span>
 222                      <span class="string">"(1, 0, 0) blue [0.0, 0.3) [0.0, 0.3)   0\n"</span>
 223                      <span class="string">"(0, 1, 0)  red [0.3, 0.7) [0.0, 0.3)   0\n"</span>
 224                      <span class="string">"(1, 1, 0) blue [0.3, 0.7) [0.0, 0.3)   0\n"</span>
 225                      <span class="string">"(0, 2, 0)  red [0.7, 1.0) [0.0, 0.3)   0\n"</span>
 226                      <span class="string">"(1, 2, 0) blue [0.7, 1.0) [0.0, 0.3)   1\n"</span>
 227                      <span class="string">"(0, 0, 1)  red [0.0, 0.3) [0.3, 0.7)   0\n"</span>
 228                      <span class="string">"(1, 0, 1) blue [0.0, 0.3) [0.3, 0.7)   0\n"</span>
 229                      <span class="string">"(0, 1, 1)  red [0.3, 0.7) [0.3, 0.7)   0\n"</span>
 230                      <span class="string">"(1, 1, 1) blue [0.3, 0.7) [0.3, 0.7)   0\n"</span>
 231                      <span class="string">"(0, 2, 1)  red [0.7, 1.0) [0.3, 0.7)   0\n"</span>
 232                      <span class="string">"(1, 2, 1) blue [0.7, 1.0) [0.3, 0.7)   0\n"</span>
 233                      <span class="string">"(0, 0, 2)  red [0.0, 0.3) [0.7, 1.0)   1\n"</span>
 234                      <span class="string">"(1, 0, 2) blue [0.0, 0.3) [0.7, 1.0)   0\n"</span>
 235                      <span class="string">"(0, 1, 2)  red [0.3, 0.7) [0.7, 1.0)   0\n"</span>
 236                      <span class="string">"(1, 1, 2) blue [0.3, 0.7) [0.7, 1.0)   0\n"</span>
 237                      <span class="string">"(0, 2, 2)  red [0.7, 1.0) [0.7, 1.0)   1\n"</span>
 238                      <span class="string">"(1, 2, 2) blue [0.7, 1.0) [0.7, 1.0)   0\n"</span><span class="special">);</span>
 239 <span class="special">}</span>
 240 </pre>
 241 <p>
 242         The axis configuration is passed to <code class="computeroutput"><span class="identifier">make_histogram</span></code>
 243         as a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">axis</span><span class="special">::</span><span class="identifier">variant</span><span class="special">&lt;...&gt;&gt;</span></code>,
 244         which can hold arbitrary sequences of axis types from a predefined set.
 245       </p>
 246 <p>
 247         Run-time configurable histograms are a slower than their compile-time brethren,
 248         but still pretty fast.
 249       </p>
 250 <div class="note"><table border="0" summary="Note">
 251 <tr>
 252 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 253 <th align="left">Note</th>
 254 </tr>
 255 <tr><td align="left" valign="top"><p>
 256           If you know already at compile-time, that you will only use one axis type,
 257           <code class="computeroutput"><span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;</span></code>
 258           for example, but not how many per histogram, then you can also pass a
 259           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;&gt;</span></code>
 260           to <code class="computeroutput"><span class="identifier">make_histogram</span></code>. You
 261           get almost the same speed as in the very first case, where both the axis
 262           configuration was fully known at compile-time.
 263         </p></td></tr>
 264 </table></div>
 265 <div class="note"><table border="0" summary="Note">
 266 <tr>
 267 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 268 <th align="left">Note</th>
 269 </tr>
 270 <tr><td align="left" valign="top"><p>
 271           If you care about maximum performance: In this example, <code class="computeroutput"><span class="identifier">axis</span><span class="special">::</span><span class="identifier">category</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span></code> is used with two string labels "red"
 272           and "blue". It is faster to use an enum, <code class="computeroutput"><span class="keyword">enum</span>
 273           <span class="special">{</span> <span class="identifier">red</span><span class="special">,</span> <span class="identifier">blue</span> <span class="special">};</span></code> and a <code class="computeroutput"><span class="identifier">axis</span><span class="special">::</span><span class="identifier">category</span><span class="special">&lt;&gt;</span></code> axis.
 274         </p></td></tr>
 275 </table></div>
 276 </div>
 277 <div class="section">
 278 <div class="titlepage"><div><div><h3 class="title">
 279 <a name="histogram.getting_started.1d_profile"></a><a class="link" href="getting_started.html#histogram.getting_started.1d_profile" title="1d-profile">1d-profile</a>
 280 </h3></div></div></div>
 281 <p>
 282         The library was designed to be very flexible and modular. The modularity
 283         is used, for example, to also provide profiles. Profiles are generalized
 284         histograms. A histogram counts how often an input falls into a particular
 285         cell. A profile accepts pairs of input values and a sample value. The profile
 286         computes the mean of the samples that end up in each cell. Have a look at
 287         the example, which should clear up any confusion.
 288       </p>
 289 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">format</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 290 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 291 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 292 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 293 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
 294
 295 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
 296   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">histogram</span><span class="special">;</span>
 297
 298   <span class="comment">/*
 299     Create a profile. Profiles does not only count entries in each cell, but
 300     also compute the mean of a sample value in each cell.
 301   */</span>
 302   <span class="keyword">auto</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">make_profile</span><span class="special">(</span><span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;&gt;(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">));</span>
 303
 304   <span class="comment">/*
 305     Fill profile with data, usually this happens in a loop. You pass the sample
 306     with the `sample` helper function. The sample can be the first or last
 307     argument.
 308   */</span>
 309   <span class="identifier">p</span><span class="special">(</span><span class="number">0.1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1</span><span class="special">));</span>
 310   <span class="identifier">p</span><span class="special">(</span><span class="number">0.15</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span>
 311   <span class="identifier">p</span><span class="special">(</span><span class="number">0.2</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">));</span>
 312   <span class="identifier">p</span><span class="special">(</span><span class="number">0.9</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">5</span><span class="special">));</span>
 313
 314   <span class="comment">/*
 315     Iterate over bins and print profile.
 316   */</span>
 317   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
 318   <span class="keyword">for</span> <span class="special">(</span><span class="keyword">auto</span><span class="special">&amp;&amp;</span> <span class="identifier">x</span> <span class="special">:</span> <span class="identifier">indexed</span><span class="special">(</span><span class="identifier">p</span><span class="special">))</span> <span class="special">{</span>
 319     <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="string">"bin %i [%3.1f, %3.1f) count %i mean %g\n"</span><span class="special">)</span>
 320           <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">index</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">().</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">bin</span><span class="special">().</span><span class="identifier">upper</span><span class="special">()</span>
 321           <span class="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">count</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>
 322   <span class="special">}</span>
 323
 324   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">flush</span><span class="special">;</span>
 325   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"bin 0 [0.0, 0.2) count 2 mean 2\n"</span>
 326                      <span class="string">"bin 1 [0.2, 0.4) count 1 mean 4\n"</span>
 327                      <span class="string">"bin 2 [0.4, 0.6) count 0 mean 0\n"</span>
 328                      <span class="string">"bin 3 [0.6, 0.8) count 0 mean 0\n"</span>
 329                      <span class="string">"bin 4 [0.8, 1.0) count 1 mean 5\n"</span><span class="special">);</span>
 330 <span class="special">}</span>
 331 </pre>
 332 </div>
 333 <div class="section">
 334 <div class="titlepage"><div><div><h3 class="title">
 335 <a name="histogram.getting_started.standard_library_algorithms"></a><a class="link" href="getting_started.html#histogram.getting_started.standard_library_algorithms" title="Standard library algorithms">Standard
 336       library algorithms</a>
 337 </h3></div></div></div>
 338 <p>
 339         The library was designed to work well with the C++ standard library. Here
 340         is an example on how to get the most common color from an image, using a
 341         3d histogram and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">max_element</span></code>.
 342       </p>
 343 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span>           <span class="comment">// std::max_element</span>
 344 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">format</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>    <span class="comment">// only needed for printing</span>
 345 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// make_histogram, integer, indexed</span>
 346 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>            <span class="comment">// std::cout, std::endl</span>
 347 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>             <span class="comment">// std::ostringstream</span>
 348
 349 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
 350   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">histogram</span><span class="special">;</span>
 351   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">histogram</span><span class="special">::</span><span class="identifier">literals</span><span class="special">;</span>
 352
 353   <span class="comment">/*
 354     We make a 3d histogram for color values (r, g, b) in an image. We assume the values
 355     are of type char. The value range then is [0, 256). The integer axis is perfect for
 356     color values.
 357   */</span>
 358   <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram</span><span class="special">(</span>
 359     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">integer</span><span class="special">&lt;&gt;(</span><span class="number">0</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="string">"r"</span><span class="special">),</span>
 360     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">integer</span><span class="special">&lt;&gt;(</span><span class="number">0</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="string">"g"</span><span class="special">),</span>
 361     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">integer</span><span class="special">&lt;&gt;(</span><span class="number">0</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="string">"b"</span><span class="special">)</span>
 362   <span class="special">);</span>
 363
 364   <span class="comment">/*
 365     We don't have real image data, so fill some fake data.
 366   */</span>
 367   <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span>
 368   <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span>
 369   <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
 370
 371   <span class="comment">/*
 372     Now let's say we want to know which color is most common. We can use std::max_element
 373     on an indexed range for that.
 374   */</span>
 375   <span class="keyword">auto</span> <span class="identifier">ind</span> <span class="special">=</span> <span class="identifier">indexed</span><span class="special">(</span><span class="identifier">h</span><span class="special">);</span>
 376   <span class="keyword">auto</span> <span class="identifier">max_it</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">max_element</span><span class="special">(</span><span class="identifier">ind</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">ind</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
 377
 378   <span class="comment">/*
 379     max_it is a special iterator to the histogram cell with the highest count.
 380     This iterator allows one to access the cell value, bin indices, and bin values.
 381     You need to twice dereference it to get to the cell value.
 382   */</span>
 383   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
 384   <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="string">"count=%i rgb=(%i, %i, %i)"</span><span class="special">)</span>
 385         <span class="special">%</span> <span class="special">**</span><span class="identifier">max_it</span> <span class="special">%</span> <span class="identifier">max_it</span><span class="special">-&gt;</span><span class="identifier">bin</span><span class="special">(</span><span class="number">0</span><span class="identifier">_c</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">max_it</span><span class="special">-&gt;</span><span class="identifier">bin</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">max_it</span><span class="special">-&gt;</span><span class="identifier">bin</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
 386
 387   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 388
 389   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"count=2 rgb=(1, 2, 3)"</span><span class="special">);</span>
 390 <span class="special">}</span>
 391 </pre>
 392 </div>
 393 </div>
 394 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 395 <td align="left"></td>
 396 <td align="right"><div class="copyright-footer">Copyright &#169; 2016-2019 Hans
 397       Dembinski<p>
 398         Distributed under the Boost Software License, Version 1.0. (See accompanying
 399         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 400       </p>
 401 </div></td>
 402 </tr></table>
 403 <hr>
 404 <div class="spirit-nav">
 405 <a accesskey="p" href="overview.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="guide.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 406 </div>
 407 </body>
 408 </html>