Imported Upstream version 1.72.0

[platform/upstream/boost.git] / libs / histogram / doc / html / histogram / guide.html

diff --git a/libs/histogram/doc/html/histogram/guide.html b/libs/histogram/doc/html/histogram/guide.html
index 4420475..fb557fa 100644 (file)
--- a/libs/histogram/doc/html/histogram/guide.html
+++ b/libs/histogram/doc/html/histogram/guide.html
@@ -50,14 +50,14 @@
 <dt><span class="section"><a href="guide.html#histogram.guide.serialization">Serialization</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert">Advanced usage</a></span></dt>
 <dd><dl>
-<dt><span class="section"><a href="guide.html#histogram.guide.expert.parallelization_options">Parallelization
-        options</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_axes">User-defined
         axes</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.axis_with_several_arguments">Axis
         with several arguments</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_storage_class">User-defined
         storage class</a></span></dt>
+<dt><span class="section"><a href="guide.html#histogram.guide.expert.parallelization_options">Parallelization
+        options</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_accumulators">User-defined
         accumulators</a></span></dt>
 </dl></dd>
@@ -74,21 +74,22 @@
 <a name="histogram.guide.making_histograms"></a><a class="link" href="guide.html#histogram.guide.making_histograms" title="Making histograms">Making histograms</a>
 </h3></div></div></div>
 <p>
-        A histogram consists of a <a class="link" href="concepts.html#histogram.concepts.Storage" title="Storage">storage</a>
-        and a sequence of <a class="link" href="concepts.html#histogram.concepts.Axis" title="Axis">axis objects</a>.
-        The storage represents a grid of cells of counters. The axis objects maps
-        input values to indices, which are used to look up the cell.
+        A histogram consists of a collection of <a class="link" href="concepts.html#histogram.concepts.Axis" title="Axis">axis
+        objects</a> and a <a class="link" href="concepts.html#histogram.concepts.Storage" title="Storage">storage</a>.
+        The storage holds a collection of accumulators, one for each cell. The axis
+        objects maps input values to indices, which are combined into a global index
+        that is used to look up the cell in the storage.
       </p>
 <p>
-        You don't normally have to worry about the storage, since the library provides
-        a very good default. There are many interesting axis types to choose from
-        (discussed further below), but for now let us stick to the most common axis,
-        the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code>
+        To start off you do not have to worry about the storage, the library provides
+        a good default. Learning more about the many interesting axis types to choose
+        from, however, will pay off very quickly (which are discussed further below).
+        For now, let us stick to the most common axis, the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code>
         axis. It represents equidistant intervals on the real line.
       </p>
 <p>
-        To make a histogram, use the convenient factory function <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>.
-        In the following example, a histogram with a single axis is created.
+        Histograms are created with the convenient factory function <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>.
+        The following example shows how to make a histogram with a single axis.
       </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
@@ -105,10 +106,12 @@
 <span class="special">}</span>
 </pre>
 <p>
-        An axis object defines how input values are mapped to bins, which means that
-        it defines the number of bins along that axis and a mapping function from
-        input values to bins. If you provide one axis, the histogram is one-dimensional.
-        If you provide two, it is two-dimensional, and so on.
+        An axis object defines how input values are mapped to bins, it is a mapping
+        functor of input values to indices. The axis object holds information such
+        as how many bins there are, where the bin edges are, metadata about the axis
+        and so on. The rank of a histogram is given by the number of axes. A histogram
+        with one axis is one-dimensional. If you provide two, it is two-dimensional,
+        and so on.
       </p>
 <p>
         In the example above, the compiler knows the number of axes and their type
@@ -165,10 +168,10 @@
 <tr><td align="left" valign="top"><p>
           When the axis types are known at compile-time, the histogram internally
           holds them in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">tuple</span></code>, which is very efficient and avoids
-          a memory allocation from the heap. If they are only known at run-time,
-          it stores the axes in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>.
-          The interface hides this difference, but not perfectly. There are a corner
-          cases where the difference becomes apparent. The <a class="link" href="overview.html#histogram.overview.rationale.structure.host" title="Histogram host class">rationale</a>
+          a heap memory allocation. If the number of axes is only known at run-time,
+          they are stored in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>.
+          The interface hides this difference very well, but there are a corner cases
+          where the difference becomes apparent. The <a class="link" href="overview.html#histogram.overview.structure.host" title="Histogram host class">overview</a>
           has more details on this point.
         </p></td></tr>
 </table></div>
@@ -193,9 +196,9 @@
 <p>
         The library provides a number of useful axis types. The builtin axis types
         can be configured to fit many needs. If you still need something more exotic,
-        no problem, it is easy to write your own axis types, see <a class="link" href="guide.html#histogram.guide.expert" title="Advanced usage">Advanced
-        usage</a>. In the following, we give some advice when to use which of
-        the builtin axis types.
+        no problem, it is easy to write your own axis types, see the <a class="link" href="guide.html#histogram.guide.expert" title="Advanced usage">Advanced
+        usage section</a> for details. In the following, we give some advice when
+        to use which of the builtin axis types.
       </p>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
@@ -211,8 +214,9 @@
                 conversion is O(1) and very fast. The axis does not allocate memory
                 dynamically. The axis is very flexible thanks to transforms (see
                 below). Due to finite precision of floating point calculations, bin
-                edges may not be exactly at expected values. If you need bin edges
-                at exactly defined floating point values, use the next axis.
+                edges may not be exactly at expected values, though. If you need
+                bin edges at exactly defined floating point values, use the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable axis</a></code>.
+                If you need bins at exact consecutive integral values, use the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/integer.html" title="Class template integer">integer axis</a></code>.
               </p></dd>
 <dt><span class="term"> <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">boost::histogram::axis::variable</a></code>
             </span></dt>
@@ -226,20 +230,23 @@
 <dt><span class="term"> <code class="computeroutput"><a class="link" href="../boost/histogram/axis/integer.html" title="Class template integer">boost::histogram::axis::integer</a></code>
             </span></dt>
 <dd><p>
-                Axis over an integer sequence [i, i+1, i+2, ...]. It can also handle
-                real input values; then it represents bins with a fixed bin width
-                of 1. Value-to-index conversion is O(1) and faster than for the
-                <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code>
-                axis. Does not allocate memory dynamically. Use this when your input
-                consists of a sequence of integers.
+                Axis over an integer sequence [i, i+1, i+2, ...]. It can be configured
+                to handle real input values, too, and then acts like a fast regular
+                axis with a fixed bin width of 1. Value-to-index conversion is O(1)
+                and faster than for the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular
+                axis</a></code>. Does not allocate memory dynamically. Use this
+                when your input consists of an integer range or pre-digitized values
+                with low dynamic range, like pixel values for individual colors in
+                an image.
               </p></dd>
 <dt><span class="term"> <code class="computeroutput"><a class="link" href="../boost/histogram/axis/category.html" title="Class template category">boost::histogram::axis::category</a></code>
             </span></dt>
 <dd><p>
                 Axis over a set of unique values of an arbitrary equal-comparable
-                type. Value-to-index conversion is O(N), but faster than <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable</a></code> axis
-                for N &lt; 10, the typical use case. The axis allocates memory dynamically
-                to store the values.
+                type. Value-to-index conversion is O(N), but still faster than the
+                O(logN) complexity of the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable
+                axis</a></code> for N &lt; 10, the typical use case. The axis allocates
+                memory from the heap to store the values.
               </p></dd>
 </dl>
 </div>
@@ -343,7 +350,7 @@
 
   <span class="comment">// create a 2d-histogram with an "age" and an "income" axis</span>
   <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">20</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">100.0</span><span class="special">,</span> <span class="string">"age in years"</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">20</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">100.0</span><span class="special">,</span> <span class="string">"yearly income in 1000 EUR"</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">20</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">100.0</span><span class="special">,</span> <span class="string">"yearly income in Thousands"</span><span class="special">));</span>
 
   <span class="comment">// do something with h</span>
 <span class="special">}</span>
@@ -424,16 +431,13 @@
 <a name="histogram.guide.axis_guide.axis_configuration.transforms"></a><a class="link" href="guide.html#histogram.guide.axis_guide.axis_configuration.transforms" title="Transforms">Transforms</a>
 </h5></div></div></div>
 <p>
-            Transforms are a way to customize a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code>
-            axis. The default is the identity transform which forwards the value.
-            Transforms allow you to chose the faster stack-allocated regular axis
-            over the generic <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable</a></code>
-            axis in some cases.
-          </p>
-<p>
-            A common need is a regular binning in the logarithm of the input value.
-            This can be achieved with a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/transform/log.html" title="Struct log">log
-            transform</a></code>. The follow example shows the builtin transforms.
+            Transforms are a way to customize a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular
+            axis</a></code>. The default is the identity transform which forwards
+            the value. Transforms allow you to chose the faster stack-allocated regular
+            axis over the generic <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable
+            axis</a></code> in some cases. A common need is a regular binning in
+            the logarithm of the input value. This can be achieved with a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/transform/log.html" title="Struct log">log transform</a></code>.
+            The follow example shows the builtin transforms.
           </p>
 <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">histogram</span><span class="special">/</span><span class="identifier">axis</span><span class="special">/</span><span class="identifier">regular</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
@@ -446,8 +450,8 @@
   <span class="comment">// log transform:</span>
   <span class="comment">// - useful when values vary dramatically in magnitude, like brightness of stars</span>
   <span class="comment">// - edges are not exactly at 10, 100, 1000, because of finite floating point precision</span>
-  <span class="comment">// - value &gt;= 0 below is mapped to -1</span>
-  <span class="comment">// - value &lt; 0 below is mapped to `size()`, because the result of std::log is NaN</span>
+  <span class="comment">// - values &gt;= 0 but smaller than the starting value of the axis are mapped to -1</span>
+  <span class="comment">// - values &lt; 0 are mapped to `size()`, because the result of std::log(value) is NaN</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_log</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">10.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_log</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">100.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_log</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">1000.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span>
@@ -459,8 +463,8 @@
   <span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">transform</span><span class="special">::</span><span class="identifier">sqrt</span><span class="special">&gt;</span> <span class="identifier">r_sqrt</span><span class="special">{</span><span class="number">3</span><span class="special">,</span> <span class="number">4.</span><span class="special">,</span> <span class="number">25.</span><span class="special">};</span>
   <span class="comment">// sqrt transform:</span>
   <span class="comment">// - bin widths are more mildly increasing compared to log transform</span>
-  <span class="comment">// - starting axis at value == 0 is ok, sqrt(0) == 0 unlike log transform</span>
-  <span class="comment">// - value &lt; 0 is mapped to `size()`, because the result of std::sqrt is NaN</span>
+  <span class="comment">// - axis starting at value == 0 is ok, sqrt(0) == 0 unlike log transform</span>
+  <span class="comment">// - values &lt; 0 are mapped to `size()`, because the result of std::sqrt(value) is NaN</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_sqrt</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="special">-</span><span class="number">1</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_sqrt</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">4.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_sqrt</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">9.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
@@ -472,9 +476,9 @@
   <span class="keyword">using</span> <span class="identifier">pow_trans</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">transform</span><span class="special">::</span><span class="identifier">pow</span><span class="special">;</span>
   <span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">pow_trans</span><span class="special">&gt;</span> <span class="identifier">r_pow</span><span class="special">(</span><span class="identifier">pow_trans</span><span class="special">{</span><span class="number">1.</span> <span class="special">/</span> <span class="number">3.</span><span class="special">},</span> <span class="number">3</span><span class="special">,</span> <span class="number">1.</span><span class="special">,</span> <span class="number">64.</span><span class="special">);</span>
   <span class="comment">// pow transform:</span>
-  <span class="comment">// - generalization of the sqrt transform, power index is first argument of ctor</span>
-  <span class="comment">// - starting the axis at value == 0 is ok, 0^p == 0 for p != 0</span>
-  <span class="comment">// - value &lt; 0 is mapped to `size()`, because the result of std::pow is NaN</span>
+  <span class="comment">// - generalization of the sqrt transform</span>
+  <span class="comment">// - starting the axis at value == 0 is ok for power p &gt; 0, 0^p == 0 for p &gt; 0</span>
+  <span class="comment">// - values &lt; 0 are mapped to `size()` if power p is not a positive integer</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_pow</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="special">-</span><span class="number">1</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_pow</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">1.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">r_pow</span><span class="special">.</span><span class="identifier">index</span><span class="special">(</span><span class="number">8.1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
@@ -484,14 +488,13 @@
 <span class="special">}</span>
 </pre>
 <p>
-            As shown in the example, due to the finite precision of floating point
-            calculations, the bin edges of a transformed regular axis may not be
-            exactly at the expected values. If you need exact correspondence, use
-            a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable</a></code>
-            axis.
+            Due to the finite precision of floating point calculations, the bin edges
+            of a transformed regular axis may not be exactly at the expected values.
+            If you need exact correspondence, use a <code class="computeroutput"><a class="link" href="../boost/histogram/axis/variable.html" title="Class template variable">variable
+            axis</a></code>.
           </p>
 <p>
-            Users may write their own transforms and use them with the builtin <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular</a></code> axis, by implementing
+            Users may write their own transforms and use them with the builtin <code class="computeroutput"><a class="link" href="../boost/histogram/axis/regular.html" title="Class template regular">regular axis</a></code>, by implementing
             a type that matches the <a class="link" href="concepts.html#histogram.concepts.Transform" title="Transform"><span class="bold"><strong>Transform</strong></span> concept</a>.
           </p>
 </div>
@@ -504,7 +507,7 @@
             can be used to configure each axis type. The option flags are implemented
             as tag types with the suffix <code class="computeroutput"><span class="identifier">_t</span></code>.
             Each tag type has a corresponding value without the suffix. The values
-            behave set semantics. You can compute the union with <code class="computeroutput"><span class="keyword">operator</span><span class="special">|</span></code> and the intersection with <code class="computeroutput"><span class="keyword">operator</span><span class="special">&amp;</span></code>.
+            have set semantics: You can compute the union with <code class="computeroutput"><span class="keyword">operator</span><span class="special">|</span></code> and the intersection with <code class="computeroutput"><span class="keyword">operator</span><span class="special">&amp;</span></code>.
             When you pass a single option flag to an axis as a template parameter,
             use the tag type. When you need to pass the union of several options
             to an axis as a template parameter, surround the union of option values
@@ -515,12 +518,12 @@
             <span class="bold"><strong>Under- and overflow bins</strong></span>
           </p>
 <p>
-            By default, under- and overflow bins are added automatically for each
-            axis (except if adding them makes no sense). If you create an axis with
-            20 bins, the histogram will actually have 22 bins along that axis. The
-            extra bins are very useful, as explained in the <a class="link" href="overview.html#histogram.overview.rationale.uoflow" title="Under- and overflow bins">rationale</a>.
-            If the input cannot exceed the axis range, you can disable the extra
-            bins to save memory. Example:
+            Under- and overflow bins are added automatically for most axis types.
+            If you create an axis with 10 bins, the histogram will actually have
+            12 bins along that axis. The extra bins are very useful, as explained
+            in the <a class="link" href="rationale.html#histogram.rationale.uoflow" title="Under- and overflow bins">rationale</a>. If
+            the input cannot exceed the axis range or if you are really tight on
+            memory, you can disable the extra bins. A demonstration:
           </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
@@ -544,9 +547,9 @@
 <span class="special">}</span>
 </pre>
 <p>
-            The <code class="computeroutput"><a class="link" href="../boost/histogram/axis/category.html" title="Class template category">category</a></code>
-            axis comes only with an overflow bin, which counts all input values that
-            are not part of the initial set.
+            The <code class="computeroutput"><a class="link" href="../boost/histogram/axis/category.html" title="Class template category">category axis</a></code>
+            by default comes only with an overflow bin, which counts all input values
+            that are not part of the initial set.
           </p>
 <p>
             <span class="bold"><strong>Circular axes</strong></span>
@@ -554,8 +557,7 @@
 <p>
             Each builtin axis except the <code class="computeroutput"><a class="link" href="../boost/histogram/axis/category.html" title="Class template category">category</a></code>
             axis can be made circular. This means that the axis is periodic at its
-            ends, like a polar angle that wraps around after 360 degrees. This is
-            particularly useful if you want make a histogram over a polar angle.
+            ends. This is useful if you want make a histogram over a polar angle.
             Example:
           </p>
 <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">histogram</span><span class="special">/</span><span class="identifier">axis</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
@@ -597,16 +599,16 @@
             generates a compile-time error. Since the highest bin wraps around to
             the lowest bin, there is no possibility for overflow either. However,
             an overflow bin is still added by default if the value is a floating
-            point type, to catch NaNs.
+            point type, to catch NaNs and infinities.
           </p>
 <p>
             <span class="bold"><strong>Growing axes</strong></span>
           </p>
 <p>
             Each builtin axis has an option to make it grow beyond its initial range
-            when a value outside of that range is discovered, instead of counting
-            this value in the under- or overflow bins (or to discard it). This can
-            be incredibly convenient. Example:
+            when a value outside of that range is passed to it, while the default
+            behavior is to count this value in the under- or overflow bins (or to
+            discard it). Example:
           </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
@@ -660,25 +662,26 @@
 <span class="special">}</span>
 </pre>
 <p>
-            So this feature is very convenient, but keep two caveats in mind.
+            This feature can be very convenient, but keep two caveats in mind.
           </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem">
                 Growing axes come with a run-time cost, since the histogram has to
-                reallocate memory for all cells when any axis size changes. Whether
+                reallocate memory for all cells when an axis changes its size. Whether
                 this performance hit is noticeable depends on your application. This
                 is a minor issue, the next is more severe.
               </li>
 <li class="listitem">
                 If you have unexpected outliers in your data which are far away from
                 the normal range, the axis could grow to a huge size and the corresponding
-                huge memory request could bring your computer to its knees. This
-                is the reason why growing axes are not the default.
+                huge memory request could bring the computer to its knees. This is
+                one of the reason why growing axes are not the default.
               </li>
 </ul></div>
 <p>
             A growing axis can have under- and overflow bins, but these only count
-            the special floating point values +-infinity and NaN.
+            the special floating point values: positive and negative infinity, and
+            NaN.
           </p>
 </div>
 </div>
@@ -690,17 +693,23 @@
 </h3></div></div></div>
 <p>
         A histogram has been created and now you want to insert values. This is done
-        with the flexible <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45525168868144-bb">histogram::operator()</a></code>,
-        which you typically use in a loop. It accepts <code class="computeroutput"><span class="identifier">N</span></code>
+        with the flexible <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538352576-bb">call
+        operator</a></code> or the <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538337296-bb">fill
+        method</a></code>, which you typically call in a loop. <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538352576-bb">The
+        call operator</a></code> accepts <code class="computeroutput"><span class="identifier">N</span></code>
         arguments or a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">tuple</span></code> with <code class="computeroutput"><span class="identifier">N</span></code>
         elements, where <code class="computeroutput"><span class="identifier">N</span></code> is equal
         to the number of axes of the histogram. It finds the corresponding bin for
-        the input and increments the bin counter by one.
+        the input and increments the bin counter by one. The <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538337296-bb">fill
+        method</a></code> accepts a single iterable over other iterables (which
+        must have have elements contiguous in memory) or values, see the method documentation
+        for details.
       </p>
 <p>
-        After the histogram has been filled, use <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45525156443728-bb">histogram::at</a></code>
-        (in analogy to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">::</span><span class="identifier">at</span></code>) to access the cell values. It accepts
-        integer indices, one for each axis of the histogram.
+        After the histogram has been filled, use the <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414525334448-bb">at
+        method</a></code> (in analogy to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">::</span><span class="identifier">at</span></code>) to
+        access the cell values. It accepts integer indices, one for each axis of
+        the histogram.
       </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
@@ -724,16 +733,13 @@
   <span class="keyword">auto</span> <span class="identifier">xy</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.3</span><span class="special">);</span>
   <span class="identifier">h</span><span class="special">(</span><span class="identifier">xy</span><span class="special">);</span>
 
-  <span class="comment">// functional-style processing is also supported, generate some data...</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;&gt;</span> <span class="identifier">input_data</span><span class="special">;</span>
-  <span class="identifier">input_data</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0.8</span><span class="special">);</span>
-  <span class="identifier">input_data</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">0.4</span><span class="special">);</span>
-  <span class="identifier">input_data</span><span class="special">.</span><span class="identifier">emplace_back</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.7</span><span class="special">);</span> <span class="comment">// goes into overflow bin of first axis</span>
+  <span class="comment">// chunk-wise filling is also supported and more efficient, make some data...</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">xy2</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">=</span> <span class="special">{{</span><span class="number">0</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">5</span><span class="special">},</span> <span class="special">{</span><span class="number">0.8</span><span class="special">,</span> <span class="number">0.4</span><span class="special">,</span> <span class="number">0.7</span><span class="special">}};</span>
 
-  <span class="comment">// std::for_each takes the functor by value, a reference wrapper avoid copies</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">input_data</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">input_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>
+  <span class="comment">// ... and call fill method</span>
+  <span class="identifier">h</span><span class="special">.</span><span class="identifier">fill</span><span class="special">(</span><span class="identifier">xy2</span><span class="special">);</span>
 
-  <span class="comment">// once histogram is filled, access cells using operator[] or at(...)</span>
+  <span class="comment">// once histogram is filled, access individual cells using operator[] or at(...)</span>
   <span class="comment">// - operator[] can only accept a single argument in the current version of C++,</span>
   <span class="comment">//   it is convenient when you have a 1D histogram</span>
   <span class="comment">// - at(...) can accept several values, so use this by default</span>
@@ -752,7 +758,7 @@
 
   <span class="comment">// iteration over values works, but see next example for a better way</span>
   <span class="comment">// - iteration using begin() and end() includes under- and overflow bins</span>
-  <span class="comment">// - iteration order is an implementation detail and may change in future versions</span>
+  <span class="comment">// - iteration order is an implementation detail and should not be relied upon</span>
   <span class="keyword">const</span> <span class="keyword">double</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">accumulate</span><span class="special">(</span><span class="identifier">h</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">h</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="number">0.0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">sum</span> <span class="special">==</span> <span class="number">6</span><span class="special">);</span>
 <span class="special">}</span>
@@ -769,7 +775,7 @@
         other inputs. It can be the first or last argument. You can freely mix calls
         with and without a weight. Calls without <code class="computeroutput"><span class="identifier">weight</span></code>
         act like the weight is <code class="computeroutput"><span class="number">1</span></code>. Why
-        weighted increments are sometimes useful is explained <a class="link" href="overview.html#histogram.overview.rationale.weights" title="Support of weighted fills">in
+        weighted increments are sometimes useful is explained <a class="link" href="rationale.html#histogram.rationale.weights" title="Support of weighted fills">in
         the rationale</a>.
       </p>
 <div class="note"><table border="0" summary="Note">
@@ -785,10 +791,11 @@
 <p>
         When the weights come from a stochastic process, it is useful to keep track
         of the variance of the sum of weights per cell. A specialized histogram can
-        be generated with the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45525155370992.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>
+        be generated with the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45414524212960.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>
         factory function which does that.
       </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 
 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
   <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>
@@ -801,12 +808,17 @@
   <span class="identifier">h</span><span class="special">(</span><span class="number">0.4</span><span class="special">,</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// weight 3 goes to second bin</span>
   <span class="identifier">h</span><span class="special">(</span><span class="number">0.5</span><span class="special">,</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">4</span><span class="special">));</span> <span class="comment">// weight 4 goes to second bin</span>
 
+  <span class="comment">// chunk-wise filling is also supported</span>
+  <span class="keyword">auto</span> <span class="identifier">x</span> <span class="special">=</span> <span class="special">{</span><span class="number">0.2</span><span class="special">,</span> <span class="number">0.6</span><span class="special">};</span>
+  <span class="keyword">auto</span> <span class="identifier">w</span> <span class="special">=</span> <span class="special">{</span><span class="number">5</span><span class="special">,</span> <span class="number">6</span><span class="special">};</span>
+  <span class="identifier">h</span><span class="special">.</span><span class="identifier">fill</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">weight</span><span class="special">(</span><span class="identifier">w</span><span class="special">));</span>
+
   <span class="comment">// Weight counters have methods to access the value (sum of weights) and the variance</span>
   <span class="comment">// (sum of weights squared, why this gives the variance is explained in the rationale)</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">value</span><span class="special">()</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="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">1</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">2</span><span class="special">);</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">1</span><span class="special">].</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span> <span class="special">+</span> <span class="number">4</span><span class="special">);</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">1</span><span class="special">].</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span> <span class="special">*</span> <span class="number">3</span> <span class="special">+</span> <span class="number">4</span> <span class="special">*</span> <span class="number">4</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">value</span><span class="special">()</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">5</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">1</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">2</span> <span class="special">+</span> <span class="number">5</span> <span class="special">*</span> <span class="number">5</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">1</span><span class="special">].</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span> <span class="special">+</span> <span class="number">4</span> <span class="special">+</span> <span class="number">6</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">[</span><span class="number">1</span><span class="special">].</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span> <span class="special">*</span> <span class="number">3</span> <span class="special">+</span> <span class="number">4</span> <span class="special">*</span> <span class="number">4</span> <span class="special">+</span> <span class="number">6</span> <span class="special">*</span> <span class="number">6</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 <p>
@@ -891,36 +903,34 @@
 </h3></div></div></div>
 <p>
         Histograms from this library can do more than counting, they can hold arbitrary
-        accumulators which accept samples. A histogram is called a <span class="emphasis"><em>profile</em></span>,
-        if it computes the means of the samples in each cell.
-      </p>
-<p>
-        Profiles can be generated with the factory function <code class="computeroutput"><a class="link" href="../boost/histogram/make_pro_idm45525155334368.html" title="Function template make_profile">make_profile</a></code>.
+        accumulators which accept samples. We call a histogram with accumulators
+        that compute the mean of samples in each cell a <span class="emphasis"><em>profile</em></span>.
+        Profiles can be generated with the factory function <code class="computeroutput"><a class="link" href="../boost/histogram/make_pro_idm45414524176336.html" title="Function template make_profile">make_profile</a></code>.
       </p>
 <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>
 <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="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
-<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">utility</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">tuple</span><span class="special">&gt;</span>
 
 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
   <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">// make a profile, it computes the mean of the samples in each histogram cell</span>
-  <span class="keyword">auto</span> <span class="identifier">h</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">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="keyword">auto</span> <span class="identifier">h</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">integer</span><span class="special">&lt;&gt;(</span><span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">));</span>
 
   <span class="comment">// mean is computed from the values marked with the sample() helper function</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="number">0.10</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2.5</span><span class="special">));</span> <span class="comment">// 2.5 goes to bin 0</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="number">0.25</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3.5</span><span class="special">));</span> <span class="comment">// 3.5 goes to bin 0</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="number">0.45</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1.2</span><span class="special">));</span> <span class="comment">// 1.2 goes to bin 1</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="identifier">sample</span><span class="special">(</span><span class="number">3.4</span><span class="special">),</span> <span class="number">0.51</span><span class="special">);</span> <span class="comment">// 3.4 goes to bin 1, sample be at the front</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1</span><span class="special">));</span> <span class="comment">// sample goes to cell 0</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2</span><span class="special">));</span> <span class="comment">// sample goes to cell 0</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// sample goes to cell 1</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">),</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// sample goes to cell 1; sample can be first or last argument</span>
 
-  <span class="comment">// fills from tuples are also supported, 1.3 and 1.9 go to bin 2</span>
-  <span class="keyword">auto</span> <span class="identifier">xs1</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">0.81</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1.3</span><span class="special">));</span>
-  <span class="keyword">auto</span> <span class="identifier">xs2</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">0.86</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1.9</span><span class="special">));</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="identifier">xs1</span><span class="special">);</span>
-  <span class="identifier">h</span><span class="special">(</span><span class="identifier">xs2</span><span class="special">);</span>
+  <span class="comment">// fills from tuples are also supported, 5 and 6 go to cell 2</span>
+  <span class="keyword">auto</span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">5</span><span class="special">));</span>
+  <span class="keyword">auto</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">sample</span><span class="special">(</span><span class="number">6</span><span class="special">),</span> <span class="number">2</span><span class="special">);</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="identifier">a</span><span class="special">);</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="identifier">b</span><span class="special">);</span>
 
   <span class="comment">// builtin accumulators have methods to access their state</span>
   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
@@ -931,14 +941,14 @@
     <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">n</span> <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="comment">// how many samples are in this bin</span>
     <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">vl</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>    <span class="comment">// mean value</span>
     <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">vr</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">variance</span><span class="special">();</span> <span class="comment">// estimated variance of the mean value</span>
-    <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 count %i value %.1f variance %.1f\n"</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">i</span> <span class="special">%</span> <span class="identifier">n</span> <span class="special">%</span> <span class="identifier">vl</span> <span class="special">%</span> <span class="identifier">vr</span><span class="special">;</span>
+    <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">"index %i count %i value %.1f variance %.1f\n"</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">i</span> <span class="special">%</span> <span class="identifier">n</span> <span class="special">%</span> <span class="identifier">vl</span> <span class="special">%</span> <span class="identifier">vr</span><span class="special">;</span>
   <span class="special">}</span>
 
   <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>
 
-  <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 count 2 value 3.0 variance 0.5\n"</span>
-                     <span class="string">"bin 1 count 2 value 2.3 variance 2.4\n"</span>
-                     <span class="string">"bin 2 count 2 value 1.6 variance 0.2\n"</span><span class="special">);</span>
+  <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">"index 0 count 2 value 1.5 variance 0.5\n"</span>
+                     <span class="string">"index 1 count 2 value 3.5 variance 0.5\n"</span>
+                     <span class="string">"index 2 count 2 value 5.5 variance 0.5\n"</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 <p>
@@ -947,15 +957,58 @@
         marker function. It must be the first or last argument.
       </p>
 <p>
-        Weights and samples may be combined, if the histogram accumulators can handle
-        weights. When both <code class="computeroutput"><a class="link" href="../boost/histogram/weight.html" title="Function template weight">weight()</a></code>
+        Weights and samples may be combined, if the accumulators can handle weights.
+        When both <code class="computeroutput"><a class="link" href="../boost/histogram/weight.html" title="Function template weight">weight()</a></code>
         and <code class="computeroutput"><a class="link" href="../boost/histogram/sample.html" title="Function template sample">sample()</a></code>
-        appear in <code class="computeroutput">histogram::operator()</code>,
-        they can be in any order with respect to other, but they must be the first
-        and/or last arguments. To make a profile which can compute weighted means
-        use the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45525155328880.html" title="Function template make_weighted_profile">make_weighted_profile</a></code>
+        appear in the <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538352576-bb">call
+        operator</a></code> or the <code class="computeroutput"><a class="link" href="../boost/histogram/histogram.html#idm45414538337296-bb">fill
+        method</a></code>, they can be in any order with respect to other, but
+        they must be the first or last arguments. To make a profile which can compute
+        weighted means with proper uncertainty estimates, use the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45414524170848.html" title="Function template make_weighted_profile">make_weighted_profile</a></code>
         factory function.
       </p>
+<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>
+<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="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
+  <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="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> <span class="comment">// _c suffix creates compile-time numbers</span>
+
+  <span class="comment">// make 2D weighted profile</span>
+  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_weighted_profile</span><span class="special">(</span><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">2</span><span class="special">),</span> <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">2</span><span class="special">));</span>
+
+  <span class="comment">// The mean is computed from the values marked with the sample() helper function.</span>
+  <span class="comment">// Weights can be passed as well. The `sample` and `weight` arguments can appear in any</span>
+  <span class="comment">// order, but they must be the first or last arguments.</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1</span><span class="special">));</span>            <span class="comment">// sample goes to cell (0, 0); weight is 1</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2</span><span class="special">),</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// sample goes to cell (0, 0); weight is 3</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span>            <span class="comment">// sample goes to cell (1, 0); weight is 1</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">));</span>            <span class="comment">// sample goes to cell (1, 0); weight is 1</span>
+  <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="identifier">sample</span><span class="special">(</span><span class="number">5</span><span class="special">));</span>            <span class="comment">// sample goes to cell (1, 0); weight is 1</span>
+  <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="identifier">sample</span><span class="special">(</span><span class="number">6</span><span class="special">));</span>            <span class="comment">// sample goes to cell (1, 0); weight is 1</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">4</span><span class="special">),</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">7</span><span class="special">));</span> <span class="comment">// sample goes to cell (1, 1); weight is 4</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="identifier">weight</span><span class="special">(</span><span class="number">5</span><span class="special">),</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">8</span><span class="special">),</span> <span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// sample goes to cell (1, 1); weight is 5</span>
+
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
+  <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>
+    <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">i</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="identifier">_c</span><span class="special">);</span>
+    <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">j</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="identifier">_c</span><span class="special">);</span>
+    <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">m</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>    <span class="comment">// weighted mean</span>
+    <span class="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">variance</span><span class="special">();</span> <span class="comment">// estimated variance of weighted mean</span>
+    <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">"index %i,%i mean %.1f variance %.1f\n"</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">i</span> <span class="special">%</span> <span class="identifier">j</span> <span class="special">%</span> <span class="identifier">m</span> <span class="special">%</span> <span class="identifier">v</span><span class="special">;</span>
+  <span class="special">}</span>
+
+  <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>
+
+  <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">"index 0,0 mean 1.8 variance 0.5\n"</span>
+                     <span class="string">"index 1,0 mean 3.5 variance 0.5\n"</span>
+                     <span class="string">"index 0,1 mean 5.5 variance 0.5\n"</span>
+                     <span class="string">"index 1,1 mean 7.6 variance 0.5\n"</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">
@@ -965,15 +1018,15 @@
         The following operators are supported for pairs of histograms <code class="computeroutput"><span class="special">+,</span> <span class="special">-,</span> <span class="special">*,</span>
         <span class="special">/,</span> <span class="special">==,</span> <span class="special">!=</span></code>. Histograms can also be multiplied and
         divided by a scalar. Only a subset of the arithmetic operators is available
-        when the underlying cell value type only supports a subset.
+        when the underlying accumulator only supports that subset.
       </p>
 <p>
         The arithmetic operators can only be used when the histograms have the same
-        axis configuration. This checked at compile-time if possible, or at run-time.
-        An exception is thrown if the configurations do not match. Two histograms
-        have the same axis configuration, if all axes compare equal, which includes
-        a comparison of their metadata. Two histograms compare equal, when their
-        axis configurations and all their cell values compare equal.
+        axis configuration. This checked at run-time. An exception is thrown if the
+        configurations do not match. Two histograms have the same axis configuration,
+        if all axes compare equal, which includes a comparison of their metadata.
+        Two histograms compare equal, when their axis configurations and all their
+        cell values compare equal.
       </p>
 <div class="note"><table border="0" summary="Note">
 <tr>
@@ -1011,15 +1064,14 @@
 
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h4</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span> <span class="special">&amp;&amp;</span> <span class="identifier">h4</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span>
 
-  <span class="comment">// multiply by number; h4 *= 2 is not allowed, because the result of a multiplication is</span>
-  <span class="comment">// not a histogram anymore, it has the type boost::histogram::grid&lt;...&gt;)</span>
-  <span class="keyword">auto</span> <span class="identifier">g4</span> <span class="special">=</span> <span class="identifier">h4</span> <span class="special">*</span> <span class="number">2</span><span class="special">;</span> <span class="comment">// counts are: 4 4</span>
+  <span class="comment">// multiply by number, h4 *= 2 also works</span>
+  <span class="keyword">auto</span> <span class="identifier">h5</span> <span class="special">=</span> <span class="identifier">h4</span> <span class="special">*</span> <span class="number">2</span><span class="special">;</span> <span class="comment">// counts are: 4 4</span>
 
-  <span class="comment">// divide by number; g4 /= 4 also works</span>
-  <span class="keyword">auto</span> <span class="identifier">g5</span> <span class="special">=</span> <span class="identifier">g4</span> <span class="special">/</span> <span class="number">4</span><span class="special">;</span> <span class="comment">// counts are: 1 1</span>
+  <span class="comment">// divide by number; s4 /= 4 also works</span>
+  <span class="keyword">auto</span> <span class="identifier">h6</span> <span class="special">=</span> <span class="identifier">h5</span> <span class="special">/</span> <span class="number">4</span><span class="special">;</span> <span class="comment">// counts are: 1 1</span>
 
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">g5</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span> <span class="special">&amp;&amp;</span> <span class="identifier">g5</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">g4</span> <span class="special">!=</span> <span class="identifier">g5</span> <span class="special">&amp;&amp;</span> <span class="identifier">g4</span> <span class="special">==</span> <span class="number">4</span> <span class="special">*</span> <span class="identifier">g5</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h6</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span> <span class="special">&amp;&amp;</span> <span class="identifier">h6</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h6</span> <span class="special">!=</span> <span class="identifier">h5</span> <span class="special">&amp;&amp;</span> <span class="identifier">h5</span> <span class="special">==</span> <span class="number">4</span> <span class="special">*</span> <span class="identifier">h6</span><span class="special">);</span>
 
   <span class="comment">// note the special effect of multiplication on weight_storage</span>
   <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">weight_storage</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">2</span><span class="special">,</span> <span class="special">-</span><span class="number">1.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">));</span>
@@ -1029,15 +1081,15 @@
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="number">1</span> <span class="special">&amp;&amp;</span> <span class="identifier">h</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
 
   <span class="keyword">auto</span> <span class="identifier">h_sum</span> <span class="special">=</span> <span class="identifier">h</span> <span class="special">+</span> <span class="identifier">h</span><span class="special">;</span>
-  <span class="keyword">auto</span> <span class="identifier">g_mul</span> <span class="special">=</span> <span class="number">2</span> <span class="special">*</span> <span class="identifier">h</span><span class="special">;</span>
+  <span class="keyword">auto</span> <span class="identifier">h_mul</span> <span class="special">=</span> <span class="number">2</span> <span class="special">*</span> <span class="identifier">h</span><span class="special">;</span>
 
   <span class="comment">// values are the same as expected...</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">g_mul</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">value</span><span class="special">());</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">h_mul</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">value</span><span class="special">());</span>
   <span class="comment">// ... but variances differ</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">&amp;&amp;</span> <span class="identifier">g_mul</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">&amp;&amp;</span> <span class="identifier">h_mul</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">variance</span><span class="special">()</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span>
 
   <span class="comment">// equality operator checks variances, so histograms are not equal</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span> <span class="special">!=</span> <span class="identifier">g_mul</span><span class="special">);</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h_sum</span> <span class="special">!=</span> <span class="identifier">h_mul</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 <div class="note"><table border="0" summary="Note">
@@ -1061,8 +1113,8 @@
           When the storage tracks weight variances, such as <code class="computeroutput"><a class="link" href="reference.html#boost.histogram.weight_storage">boost::histogram::weight_storage</a></code>,
           adding two copies of a histogram produces a different result than scaling
           the histogram by a factor of two, as shown in the last example. The is
-          a consequence of the mathematical properties of variances. They add like
-          normal numbers, but scaling by <code class="computeroutput"><span class="identifier">s</span></code>
+          a consequence of the mathematical properties of variances. They can be
+          added like normal numbers, but scaling by <code class="computeroutput"><span class="identifier">s</span></code>
           means that variances are scaled by <code class="computeroutput"><span class="identifier">s</span><span class="special">^</span><span class="number">2</span></code>.
         </p></td></tr>
 </table></div>
@@ -1098,8 +1150,7 @@
               The histogram iterators also walk over the under- and overflow bins,
               if they are present. To skip the extra bins one should use the fast
               iterators from the <code class="computeroutput"><a class="link" href="../boost/histogram/indexed.html" title="Function template indexed">boost::histogram::indexed</a></code>
-              range generator instead, but the values then need to be accessed through
-              an extra dereference operation.
+              range generator instead.
             </li>
 <li class="listitem">
               The iteration order for histograms with several axes is an implementation-detail,
@@ -1137,7 +1188,7 @@
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h1</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">==</span> <span class="number">0.00</span><span class="special">);</span>
 
   <span class="comment">// use any_of to check if any cell values are smaller than 0.1,</span>
-  <span class="keyword">auto</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">any_of</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> <span class="special">[](</span><span class="keyword">const</span> <span class="keyword">auto</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="special">*</span><span class="identifier">x</span> <span class="special">&lt;</span> <span class="number">0.1</span><span class="special">;</span> <span class="special">});</span>
+  <span class="keyword">auto</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">any_of</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> <span class="special">[](</span><span class="keyword">const</span> <span class="keyword">auto</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">&lt;</span> <span class="number">0.1</span><span class="special">;</span> <span class="special">});</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">b</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// under- and overflow cells are zero, but skipped</span>
 
   <span class="comment">// find minimum element</span>
@@ -1186,20 +1237,20 @@
 </h4></div></div></div>
 <p>
           It is sometimes convenient to generate a high-dimensional histogram first
-          and then extract smaller or lower-dimensional versions from it. One useful
-          way to obtain a lower-dimensional histogram is to sum the bin contents
-          of the removed axes. This is called a <span class="emphasis"><em>projection</em></span>.
-          When the histogram has under- and overflow bins along all axes, this operation
-          creates a histogram that is exactly equal to one obtained, if it was filled
-          with the original data from the start.
+          and then extract smaller or lower-dimensional versions from it. Lower-dimensional
+          histograms are obtained by summing the bin contents of the removed axes.
+          This is called a <span class="emphasis"><em>projection</em></span>. When the histogram has
+          under- and overflow bins along all axes, this operation creates a histogram
+          which is identical to one that would have been obtained by filling the
+          original data.
         </p>
 <p>
           Projection is useful if you found out that there is no interesting structure
           along an axis, so it is not worth keeping that axis around, or if you want
-          to visualize 1d or 2d projections of a high-dimensional histogram.
+          to visualize 1d or 2d summaries of a high-dimensional histogram.
         </p>
 <p>
-          The library provides the <code class="computeroutput"><a class="link" href="../boost/histogram/algorithm/project_idm45525156151136.html" title="Function template project">boost::histogram::algorithm::project</a></code>
+          The library provides the <code class="computeroutput"><a class="link" href="../boost/histogram/algorithm/project_idm45414525025232.html" title="Function template project">boost::histogram::algorithm::project</a></code>
           function for this purpose. It accepts the original histogram and the indices
           (one or more) of the axes that are kept and returns the lower-dimensional
           histogram. If the histogram is static, meaning the axis configuration is
@@ -1262,19 +1313,19 @@
 <a name="histogram.guide.using_algorithms.reduction"></a><a class="link" href="guide.html#histogram.guide.using_algorithms.reduction" title="Reduction">Reduction</a>
 </h4></div></div></div>
 <p>
-          A projection removes an axis completely. Another way to obtain a smaller
-          histogram is the <code class="computeroutput"><a class="link" href="../boost/histogram/algorithm/reduce_idm45525156086992.html" title="Function template reduce">boost::histogram::algorithm::reduce</a></code>
-          function to <span class="emphasis"><em>slice</em></span>, <span class="emphasis"><em>shrink</em></span> or
-          <span class="emphasis"><em>rebin</em></span> axes.
+          A projection removes an axis completely. A less drastic way to obtain a
+          smaller histogram is the <code class="computeroutput"><a class="link" href="../boost/histogram/algorithm/reduce_idm45414524960512.html" title="Function template reduce">boost::histogram::algorithm::reduce</a></code>
+          function, which allows one to <span class="emphasis"><em>slice</em></span>, <span class="emphasis"><em>shrink</em></span>
+          or <span class="emphasis"><em>rebin</em></span> individual axes.
         </p>
 <p>
           Shrinking means that the range of an axis is reduced and the number of
-          bins along this axis. Slicing means the same, but is based on axis indices
-          instead of their values. Rebinning means that adjacent bins are piece-wise
-          merged into larger bins. For N adjacent bins, a new bin is formed which
-          covers the interval of the merged bins and has their added content. These
-          two operations can be combined and applied to several axes at once (which
-          is much more efficient than doing it sequentially).
+          bins along that axis. Slicing does the same, but is based on axis indices
+          while shrinking is based on the axis values. Rebinning means that adjacent
+          bins are merged into larger bins. For N adjacent bins, a new bin is formed
+          which covers the common interval of the merged bins and has their added
+          content. These two operations can be combined and applied to several axes
+          at once (which is much more efficient than doing it sequentially).
         </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
@@ -1294,15 +1345,16 @@
   <span class="comment">// rebin the second axis by merging pairs of adjacent bins</span>
   <span class="keyword">auto</span> <span class="identifier">h2</span> <span class="special">=</span> <span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">reduce</span><span class="special">(</span><span class="identifier">h</span><span class="special">,</span> <span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">shrink</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">3.0</span><span class="special">),</span> <span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">rebin</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="comment">// reduce does not remove counts if the histogram has underflow/overflow bins</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h2</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span>
-
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">bin</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">==</span> <span class="number">0.0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">0</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> <span class="special">==</span> <span class="number">3.0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">1</span><span class="special">).</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">1</span><span class="special">).</span><span class="identifier">bin</span><span class="special">(</span><span class="number">0</span><span class="special">).</span><span class="identifier">lower</span><span class="special">()</span> <span class="special">==</span> <span class="special">-</span><span class="number">1.0</span><span class="special">);</span>
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">h2</span><span class="special">.</span><span class="identifier">axis</span><span class="special">(</span><span class="number">1</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> <span class="special">==</span> <span class="number">1.0</span><span class="special">);</span>
+
+  <span class="comment">// reduce does not change the total count if the histogram has underflow/overflow bins;</span>
+  <span class="comment">// counts in removed bins are added to the corresponding under- and overflow bins</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h2</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 </div>
@@ -1312,13 +1364,13 @@
 <a name="histogram.guide.streaming"></a><a class="link" href="guide.html#histogram.guide.streaming" title="Streaming">Streaming</a>
 </h3></div></div></div>
 <p>
-        Simple ostream operators are shipped with the library, which are internally
-        used by the unit tests. These give text representations of axis and histogram
-        configurations, but do not show the histogram content. They may be useful
-        for debugging and more useful text representations are planned for the future.
-        Since user may want to use their own implementations, the headers with the
-        builtin implementations are not included by the super header <code class="computeroutput"><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></code>.
-        The following example shows the effect of output streaming.
+        Simple ostream operators are shipped with the library. They are internally
+        used by the unit tests and give simple text representations of axis and histogram
+        configurations and show the histogram content. One-dimensional histograms
+        are rendered as ASCII drawings. The text representations may be useful for
+        debugging or more, but users may want to use their own implementations. Therefore,
+        the headers with the builtin implementations are not included by any other
+        header of the library. The following example shows the effect of output streaming.
       </p>
 <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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <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">ostream</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
@@ -1329,38 +1381,44 @@
 
 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
   <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="keyword">namespace</span> <span class="identifier">tr</span> <span class="special">=</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">transform</span><span class="special">;</span>
-
-  <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">2</span><span class="special">,</span> <span class="special">-</span><span class="number">1.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">),</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">tr</span><span class="special">::</span><span class="identifier">log</span><span class="special">&gt;(</span><span class="number">2</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="number">10.0</span><span class="special">,</span> <span class="string">"axis 1"</span><span class="special">),</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">regular</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">tr</span><span class="special">::</span><span class="identifier">pow</span><span class="special">,</span> <span class="identifier">use_default</span><span class="special">,</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">option</span><span class="special">::</span><span class="identifier">growth_t</span><span class="special">&gt;(</span>
-                         <span class="identifier">tr</span><span class="special">::</span><span class="identifier">pow</span><span class="special">{</span><span class="number">1.5</span><span class="special">},</span> <span class="number">2</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="number">10.0</span><span class="special">,</span> <span class="string">"axis 2"</span><span class="special">),</span>
-                     <span class="comment">// axis without metadata</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">circular</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">null_type</span><span class="special">&gt;(</span><span class="number">4</span><span class="special">,</span> <span class="number">0.0</span><span class="special">,</span> <span class="number">360.0</span><span class="special">),</span>
-                     <span class="comment">// axis without under-/overflow bins</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">variable</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">use_default</span><span class="special">,</span> <span class="identifier">axis</span><span class="special">::</span><span class="identifier">option</span><span class="special">::</span><span class="identifier">none_t</span><span class="special">&gt;(</span>
-                         <span class="special">{-</span><span class="number">1.0</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">"axis 4"</span><span class="special">),</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">category</span><span class="special">&lt;&gt;({</span><span class="number">2</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">3</span><span class="special">},</span> <span class="string">"axis 5"</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><span class="string">"red"</span><span class="special">,</span> <span class="string">"blue"</span><span class="special">},</span> <span class="string">"axis 6"</span><span class="special">),</span>
-                     <span class="identifier">axis</span><span class="special">::</span><span class="identifier">integer</span><span class="special">&lt;&gt;(-</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="string">"axis 7"</span><span class="special">));</span>
 
   <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
-  <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">h</span><span class="special">;</span>
+
+  <span class="keyword">auto</span> <span class="identifier">h1</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">5</span><span class="special">,</span> <span class="special">-</span><span class="number">1.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="string">"axis 1"</span><span class="special">));</span>
+  <span class="identifier">h1</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
+  <span class="identifier">h1</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span>
+  <span class="identifier">h1</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">=</span> <span class="number">3</span><span class="special">;</span>
+  <span class="identifier">h1</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
+
+  <span class="comment">// 1D histograms are rendered as an ASCII drawing</span>
+  <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">h1</span><span class="special">;</span>
+
+  <span class="keyword">auto</span> <span class="identifier">h2</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">2</span><span class="special">,</span> <span class="special">-</span><span class="number">1.0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">,</span> <span class="string">"axis 1"</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><span class="string">"red"</span><span class="special">,</span> <span class="string">"blue"</span><span class="special">},</span> <span class="string">"axis 2"</span><span class="special">));</span>
+
+  <span class="comment">// higher dimensional histograms just have their cell counts listed</span>
+  <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">h2</span><span class="special">;</span>
 
   <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>
 
-  <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">"histogram(\n"</span>
-         <span class="string">"  regular(2, -1, 1, options=underflow | overflow),\n"</span>
-         <span class="string">"  regular_log(2, 1, 10, metadata=\"axis 1\", options=underflow | overflow),\n"</span>
-         <span class="string">"  regular_pow(2, 1, 10, metadata=\"axis 2\", options=growth, power=1.5),\n"</span>
-         <span class="string">"  regular(4, 0, 360, options=overflow | circular),\n"</span>
-         <span class="string">"  variable(-1, 0, 1, metadata=\"axis 4\", options=none),\n"</span>
-         <span class="string">"  category(2, 1, 3, metadata=\"axis 5\", options=overflow),\n"</span>
-         <span class="string">"  category(\"red\", \"blue\", metadata=\"axis 6\", options=overflow),\n"</span>
-         <span class="string">"  integer(-1, 1, metadata=\"axis 7\", options=underflow | overflow)\n"</span>
-         <span class="string">")"</span><span class="special">);</span>
+  <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">"histogram(regular(5, -1, 1, metadata=\"axis 1\", options=underflow | overflow))\n"</span>
+      <span class="string">"               +-------------------------------------------------------------+\n"</span>
+      <span class="string">"[-inf,   -1) 0 |                                                             |\n"</span>
+      <span class="string">"[  -1, -0.6) 2 |==============================                               |\n"</span>
+      <span class="string">"[-0.6, -0.2) 4 |============================================================ |\n"</span>
+      <span class="string">"[-0.2,  0.2) 3 |=============================================                |\n"</span>
+      <span class="string">"[ 0.2,  0.6) 0 |                                                             |\n"</span>
+      <span class="string">"[ 0.6,    1) 1 |===============                                              |\n"</span>
+      <span class="string">"[   1,  inf) 0 |                                                             |\n"</span>
+      <span class="string">"               +-------------------------------------------------------------+\n"</span>
+      <span class="string">"histogram(\n"</span>
+      <span class="string">"  regular(2, -1, 1, metadata=\"axis 1\", options=underflow | overflow)\n"</span>
+      <span class="string">"  category(\"red\", \"blue\", metadata=\"axis 2\", options=overflow)\n"</span>
+      <span class="string">"  (-1 0): 0 ( 0 0): 0 ( 1 0): 0 ( 2 0): 0 (-1 1): 0 ( 0 1): 0\n"</span>
+      <span class="string">"  ( 1 1): 0 ( 2 1): 0 (-1 2): 0 ( 0 2): 0 ( 1 2): 0 ( 2 2): 0\n"</span>
+      <span class="string">")"</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 </div>
@@ -1371,8 +1429,8 @@
 <p>
         The library supports serialization via <a href="../../../../../libs/serialization/index.html" target="_top">Boost.Serialization</a>.
         The serialization code is not included by the super header <code class="computeroutput"><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></code>,
-        so that the library can be used without Boost.Serialization or with a different
-        serialization library.
+        so that the library can be used without Boost.Serialization or with another
+        compatible serialization library.
       </p>
 <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">archive</span><span class="special">/</span><span class="identifier">text_iarchive</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">archive</span><span class="special">/</span><span class="identifier">text_oarchive</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
@@ -1418,113 +1476,25 @@
 <a name="histogram.guide.expert"></a><a class="link" href="guide.html#histogram.guide.expert" title="Advanced usage">Advanced usage</a>
 </h3></div></div></div>
 <div class="toc"><dl class="toc">
-<dt><span class="section"><a href="guide.html#histogram.guide.expert.parallelization_options">Parallelization
-        options</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_axes">User-defined
         axes</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.axis_with_several_arguments">Axis
         with several arguments</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_storage_class">User-defined
         storage class</a></span></dt>
+<dt><span class="section"><a href="guide.html#histogram.guide.expert.parallelization_options">Parallelization
+        options</a></span></dt>
 <dt><span class="section"><a href="guide.html#histogram.guide.expert.user_defined_accumulators">User-defined
         accumulators</a></span></dt>
 </dl></div>
 <p>
         The library is customizable and extensible by users. Users can create new
         axis types and use them with the histogram, or implement a custom storage
-        policy, or use a builtin storage policy with a custom counter type.
+        policy, or use a builtin storage policy with a custom counter type. The library
+        was designed to make this very easy. This section shows how to do this.
       </p>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
-<a name="histogram.guide.expert.parallelization_options"></a><a class="link" href="guide.html#histogram.guide.expert.parallelization_options" title="Parallelization options">Parallelization
-        options</a>
-</h4></div></div></div>
-<p>
-          There are two ways to generate a single histogram using several threads.
-        </p>
-<p>
-          1. Each thread has its own copy of the histogram. Each copy is independently
-          filled. The copies are then added in the main thread. Use this as the default
-          when you can afford having <code class="computeroutput"><span class="identifier">N</span></code>
-          copies of the histogram in memory for <code class="computeroutput"><span class="identifier">N</span></code>
-          threads, because it allows each thread to work on its thread-local memory
-          and utilize the CPU cache without the need to synchronize memory access.
-          The highest performance gains are obtained in this way.
-        </p>
-<p>
-          2. There is only one histogram which is filled concurrently by several
-          threads. This requires using a thread-safe storage that can handle concurrent
-          writes. The library provides the <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/thread_safe.html" title="Class template thread_safe">boost::histogram::accumulators::thread_safe</a></code>
-          accumulator, which combined with the <code class="computeroutput"><a class="link" href="reference.html#boost.histogram.dense_storage">boost::histogram::dense_storage</a></code>
-          provides a thread-safe storage.
-        </p>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td align="left" valign="top"><p>
-            Filling a histogram with growing axes in a multi-threaded environment
-            is safe, but will have poor performance since the storage must be locked
-            on each fill of a growing axis to see whether an extension of the storage
-            is needed. Even without growing axes, there is a performance gain of
-            filling a histogram in parallel only if the histogram is either very
-            large or when significant time is spend in preparing the value to fill.
-            For small histograms, threads frequently access the same cell, whose
-            state has to be synchronized between the threads. This is slow even with
-            atomic counters, since different threads are usually executed on different
-            cores and the synchronization causes cache misses that eat up the performance
-            gained by doing some calculations in parallel.
-          </p></td></tr>
-</table></div>
-<p>
-          The next example demonstrates option 2 (option 1 is straight-forward to
-          implement).
-        </p>
-<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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
-<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">algorithm</span><span class="special">/</span><span class="identifier">sum</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
-<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
-<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>
-<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">thread</span><span class="special">&gt;</span>
-<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
-
-<span class="comment">// dummy fill function, to be executed in parallel by several threads</span>
-<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Histogram</span><span class="special">&gt;</span>
-<span class="keyword">void</span> <span class="identifier">fill</span><span class="special">(</span><span class="identifier">Histogram</span><span class="special">&amp;</span> <span class="identifier">h</span><span class="special">)</span> <span class="special">{</span>
-  <span class="keyword">for</span> <span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">1000</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">h</span><span class="special">(</span><span class="identifier">i</span> <span class="special">%</span> <span class="number">10</span><span class="special">);</span> <span class="special">}</span>
-<span class="special">}</span>
-
-<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
-  <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">/*
-    Create histogram with container of thread-safe counters for parallel filling in
-    several threads. Only filling is thread-safe, other guarantees are not given.
-  */</span>
-  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">accumulators</span><span class="special">::</span><span class="identifier">thread_safe</span><span class="special">&lt;</span><span class="keyword">unsigned</span><span class="special">&gt;&gt;(),</span>
-                               <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">10</span><span class="special">));</span>
-
-  <span class="comment">/*
-    Run the fill function in parallel from different threads. This is safe when a
-    thread-safe accumulator and a storage with thread-safe cell access are used.
-  */</span>
-  <span class="keyword">auto</span> <span class="identifier">fill_h</span> <span class="special">=</span> <span class="special">[&amp;</span><span class="identifier">h</span><span class="special">]()</span> <span class="special">{</span> <span class="identifier">fill</span><span class="special">(</span><span class="identifier">h</span><span class="special">);</span> <span class="special">};</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t1</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t2</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t3</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t4</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
-  <span class="identifier">t1</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
-  <span class="identifier">t2</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
-  <span class="identifier">t3</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
-  <span class="identifier">t4</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
-
-  <span class="comment">// Without a thread-safe accumulator, this number may be smaller.</span>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> <span class="special">==</span> <span class="number">4000</span><span class="special">);</span>
-<span class="special">}</span>
-</pre>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h4 class="title">
 <a name="histogram.guide.expert.user_defined_axes"></a><a class="link" href="guide.html#histogram.guide.expert.user_defined_axes" title="User-defined axes">User-defined
         axes</a>
 </h4></div></div></div>
@@ -1722,7 +1692,7 @@
 <p>
           Users who work exclusively with weighted histograms should chose 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="keyword">double</span><span class="special">&gt;</span></code>
           over the default storage, it will be faster. If they also want to track
-          the variance of the sum of weights, using the factor function <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45525155370992.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>
+          the variance of the sum of weights, using the factor function <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45414524212960.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>
           is a convenient, which provides a histogram with a vector-based storage
           of <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/weighted_sum.html" title="Class template weighted_sum">weighted_sum</a></code>
           accumulators.
@@ -1791,6 +1761,96 @@
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
+<a name="histogram.guide.expert.parallelization_options"></a><a class="link" href="guide.html#histogram.guide.expert.parallelization_options" title="Parallelization options">Parallelization
+        options</a>
+</h4></div></div></div>
+<p>
+          There are two ways to generate a single histogram using several threads.
+        </p>
+<p>
+          1. Each thread has its own copy of the histogram. Each copy is independently
+          filled. The copies are then added in the main thread. Use this as the default
+          when you can afford having <code class="computeroutput"><span class="identifier">N</span></code>
+          copies of the histogram in memory for <code class="computeroutput"><span class="identifier">N</span></code>
+          threads, because it allows each thread to work on its thread-local memory
+          and utilize the CPU cache without the need to synchronize memory access.
+          The highest performance gains are obtained in this way.
+        </p>
+<p>
+          2. There is only one histogram which is filled concurrently by several
+          threads. This requires using a thread-safe storage that can handle concurrent
+          writes. The library provides the <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/thread_safe.html" title="Class template thread_safe">boost::histogram::accumulators::thread_safe</a></code>
+          accumulator, which combined with the <code class="computeroutput"><a class="link" href="reference.html#boost.histogram.dense_storage">boost::histogram::dense_storage</a></code>
+          provides a thread-safe storage.
+        </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+            Filling a histogram with growing axes in a multi-threaded environment
+            is safe, but has poor performance since the histogram must be locked
+            on each fill. The locks are required because an axis could grow each
+            time, which changes the number of cells and cell addressing for all other
+            threads. Even without growing axes, there is only a performance gain
+            of filling a thread-safe histogram in parallel if the histogram is either
+            very large or when significant time is spend in preparing the value to
+            fill. For small histograms, threads frequently access the same cell,
+            whose state has to be synchronized between the threads. This is slow
+            even with atomic counters, since different threads are usually executed
+            on different cores and the synchronization causes cache misses that eat
+            up the performance gained by doing some calculations in parallel.
+          </p></td></tr>
+</table></div>
+<p>
+          The next example demonstrates option 2 (option 1 is straight-forward to
+          implement).
+        </p>
+<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">histogram</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<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">algorithm</span><span class="special">/</span><span class="identifier">sum</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">thread</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
+
+<span class="comment">// dummy fill function, to be executed in parallel by several threads</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Histogram</span><span class="special">&gt;</span>
+<span class="keyword">void</span> <span class="identifier">fill</span><span class="special">(</span><span class="identifier">Histogram</span><span class="special">&amp;</span> <span class="identifier">h</span><span class="special">)</span> <span class="special">{</span>
+  <span class="keyword">for</span> <span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">1000</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">h</span><span class="special">(</span><span class="identifier">i</span> <span class="special">%</span> <span class="number">10</span><span class="special">);</span> <span class="special">}</span>
+<span class="special">}</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
+  <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">/*
+    Create histogram with container of thread-safe counters for parallel filling in
+    several threads. Only filling is thread-safe, other guarantees are not given.
+  */</span>
+  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">accumulators</span><span class="special">::</span><span class="identifier">thread_safe</span><span class="special">&lt;</span><span class="keyword">unsigned</span><span class="special">&gt;&gt;(),</span>
+                               <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">10</span><span class="special">));</span>
+
+  <span class="comment">/*
+    Run the fill function in parallel from different threads. This is safe when a
+    thread-safe accumulator and a storage with thread-safe cell access are used.
+  */</span>
+  <span class="keyword">auto</span> <span class="identifier">fill_h</span> <span class="special">=</span> <span class="special">[&amp;</span><span class="identifier">h</span><span class="special">]()</span> <span class="special">{</span> <span class="identifier">fill</span><span class="special">(</span><span class="identifier">h</span><span class="special">);</span> <span class="special">};</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t1</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t2</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t3</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t4</span><span class="special">(</span><span class="identifier">fill_h</span><span class="special">);</span>
+  <span class="identifier">t1</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
+  <span class="identifier">t2</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
+  <span class="identifier">t3</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
+  <span class="identifier">t4</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
+
+  <span class="comment">// Without a thread-safe accumulator, this number may be smaller.</span>
+  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">sum</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> <span class="special">==</span> <span class="number">4000</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
 <a name="histogram.guide.expert.user_defined_accumulators"></a><a class="link" href="guide.html#histogram.guide.expert.user_defined_accumulators" title="User-defined accumulators">User-defined
         accumulators</a>
 </h4></div></div></div>
@@ -1813,24 +1873,25 @@
               accepts no samples, but accepts a weight. It is an alternative to a
               plain arithmetic type as a counter. It provides an advantage when histograms
               are filled with weights that differ dramatically in magnitude. The
-              sum of weights is computed incrementally with the Neumaier algorithm,
-              which is more accurate than a normal sum of arithmetic types.
+              sum of weights is computed incrementally with the Neumaier algorithm.
+              The algorithm is more accurate, but consumes more CPU and memory (memory
+              is doubled compared to a normal sum of floating point numbers).
             </li>
 <li class="listitem">
               <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/weighted_sum.html" title="Class template weighted_sum">weighted_sum</a></code>
               accepts no samples, but accepts a weight. It computes the sum of weights
               and the sum of weights squared, the variance estimate of the sum of
-              weights. This type is used by the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45525155370992.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>.
+              weights. This type is used by the <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45414524212960.html" title="Function template make_weighted_histogram">make_weighted_histogram</a></code>.
             </li>
 <li class="listitem">
               <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/mean.html" title="Class template mean">mean</a></code>
-              accepts a sample and computes the mean of the samples. <code class="computeroutput"><a class="link" href="../boost/histogram/make_pro_idm45525155334368.html" title="Function template make_profile">make_profile</a></code> uses
+              accepts a sample and computes the mean of the samples. <code class="computeroutput"><a class="link" href="../boost/histogram/make_pro_idm45414524176336.html" title="Function template make_profile">make_profile</a></code> uses
               this accumulator.
             </li>
 <li class="listitem">
               <code class="computeroutput"><a class="link" href="../boost/histogram/accumulators/weighted_mean.html" title="Class template weighted_mean">weighted_mean</a></code>
               accepts a sample and a weight. It computes the weighted mean of the
-              samples. <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45525155328880.html" title="Function template make_weighted_profile">make_weighted_profile</a></code>
+              samples. <code class="computeroutput"><a class="link" href="../boost/histogram/make_wei_idm45414524170848.html" title="Function template make_weighted_profile">make_weighted_profile</a></code>
               uses this accumulator.
             </li>
 </ul></div>
@@ -1838,64 +1899,130 @@
           Users can easily write their own accumulators and plug them into the histogram,
           if they adhere to the <a class="link" href="concepts.html#histogram.concepts.Accumulator" title="Accumulator"><span class="bold"><strong>Accumulator</strong></span> concept</a>.
         </p>
-<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">array</span><span class="special">&gt;</span>
-<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>
+<p>
+          The first example shows how to make and use a histogram that uses one of
+          the the builtin accumulators.
+        </p>
+<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>
 <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="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">accumulators</span><span class="special">/</span><span class="identifier">mean</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
 
 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
   <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="keyword">const</span> <span class="keyword">auto</span> <span class="identifier">axis</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">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="keyword">using</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="identifier">accumulators</span><span class="special">::</span><span class="identifier">mean</span><span class="special">&lt;&gt;;</span>
 
-  <span class="comment">// Create a 1D-profile, which computes the mean of samples in each bin. The</span>
-  <span class="comment">// factory function `make_profile` is provided by the library as a shorthand.</span>
-  <span class="keyword">auto</span> <span class="identifier">h1</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">accumulators</span><span class="special">::</span><span class="identifier">mean</span><span class="special">&lt;&gt;&gt;(),</span> <span class="identifier">axis</span><span class="special">);</span>
+  <span class="comment">// Create a 1D-profile, which computes the mean of samples in each bin.</span>
+  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">mean</span><span class="special">&gt;(),</span> <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">2</span><span class="special">));</span>
+  <span class="comment">// The factory function `make_profile` is provided as a shorthand for this, so this is</span>
+  <span class="comment">// equivalent to the previous line: auto h = make_profile(axis::integer&lt;&gt;(0, 2));</span>
 
-  <span class="comment">// Argument of `sample` is passed to accumulator.</span>
-  <span class="identifier">h1</span><span class="special">(</span><span class="number">0.0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2</span><span class="special">));</span> <span class="comment">// sample 2 goes to first bin</span>
-  <span class="identifier">h1</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">2</span><span class="special">));</span> <span class="comment">// sample 2 goes to first bin</span>
-  <span class="identifier">h1</span><span class="special">(</span><span class="number">0.4</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// sample 3 goes to second bin</span>
-  <span class="identifier">h1</span><span class="special">(</span><span class="number">0.5</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">));</span> <span class="comment">// sample 4 goes to second bin</span>
+  <span class="comment">// An argument marked as `sample` is passed to the accumulator.</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1</span><span class="special">));</span> <span class="comment">// sample goes to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2</span><span class="special">));</span> <span class="comment">// sample goes to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// sample goes to second cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">));</span> <span class="comment">// sample goes to second cell</span>
 
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os1</span><span class="special">;</span>
-  <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">h1</span><span class="special">))</span> <span class="special">{</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
+  <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>
     <span class="comment">// Accumulators usually have methods to access their state. Use the arrow</span>
     <span class="comment">// operator to access them. Here, `count()` gives the number of samples,</span>
     <span class="comment">// `value()` the mean, and `variance()` the variance estimate of the mean.</span>
-    <span class="identifier">os1</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 count %i mean %.1f variance %.1f\n"</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="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> <span class="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">variance</span><span class="special">();</span>
+    <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">"index %i count %i mean %.1f variance %.1f\n"</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="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> <span class="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">variance</span><span class="special">();</span>
   <span class="special">}</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os1</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>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os1</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"0 count 2 mean 2.0 variance 0.0\n"</span>
-                      <span class="string">"1 count 2 mean 3.5 variance 0.5\n"</span>
-                      <span class="string">"2 count 0 mean 0.0 variance 0.0\n"</span><span class="special">);</span>
-
-  <span class="comment">// Let's make a custom accumulator, which tracks the maximum of the samples. It must</span>
-  <span class="comment">// have a call operator that accepts the argument of the `sample` function. The return</span>
-  <span class="comment">// value of the call operator is ignored.</span>
-  <span class="keyword">struct</span> <span class="identifier">max</span> <span class="special">{</span>
+  <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>
+  <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">"index 0 count 2 mean 1.5 variance 0.5\n"</span>
+                     <span class="string">"index 1 count 2 mean 3.5 variance 0.5\n"</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+          The second example shows how to use a simple custom accumulator.
+        </p>
+<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>
+<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="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
+  <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">// Make a custom accumulator, which tracks the maximum of the samples.</span>
+  <span class="comment">// It must have a call operator that accepts the argument of the `sample` function.</span>
+  <span class="keyword">struct</span> <span class="identifier">maximum</span> <span class="special">{</span>
+    <span class="comment">// return value is ignored, so we use void</span>
     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">double</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span>
       <span class="keyword">if</span> <span class="special">(</span><span class="identifier">x</span> <span class="special">&gt;</span> <span class="identifier">value</span><span class="special">)</span> <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span>
     <span class="special">}</span>
     <span class="keyword">double</span> <span class="identifier">value</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// value is initialized to zero</span>
   <span class="special">};</span>
 
-  <span class="comment">// Create a histogram that uses the custom accumulator.</span>
-  <span class="keyword">auto</span> <span class="identifier">h2</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">max</span><span class="special">&gt;(),</span> <span class="identifier">axis</span><span class="special">);</span>
-  <span class="identifier">h2</span><span class="special">(</span><span class="number">0.0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2</span><span class="special">));</span>   <span class="comment">// sample 2 goes to first bin</span>
-  <span class="identifier">h2</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">2.5</span><span class="special">));</span> <span class="comment">// sample 2.5 goes to first bin</span>
-  <span class="identifier">h2</span><span class="special">(</span><span class="number">0.4</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">));</span>   <span class="comment">// sample 3 goes to second bin</span>
-  <span class="identifier">h2</span><span class="special">(</span><span class="number">0.5</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4</span><span class="special">));</span>   <span class="comment">// sample 4 goes to second bin</span>
+  <span class="comment">// Create 1D histogram that uses the custom accumulator.</span>
+  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">maximum</span><span class="special">&gt;(),</span> <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">2</span><span class="special">));</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">1.0</span><span class="special">));</span> <span class="comment">// sample goes to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">2.0</span><span class="special">));</span> <span class="comment">// sample goes to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3.0</span><span class="special">));</span> <span class="comment">// sample goes to second cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">4.0</span><span class="special">));</span> <span class="comment">// sample goes to second cell</span>
 
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os2</span><span class="special">;</span>
-  <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">h2</span><span class="special">))</span> <span class="special">{</span>
-    <span class="identifier">os2</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 value %.1f\n"</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="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">;</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
+  <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>
+    <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">"index %i maximum %.1f\n"</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="special">%</span> <span class="identifier">x</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">;</span>
   <span class="special">}</span>
-  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">os2</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>
-  <span class="identifier">assert</span><span class="special">(</span><span class="identifier">os2</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"0 value 2.5\n"</span>
-                      <span class="string">"1 value 4.0\n"</span>
-                      <span class="string">"2 value 0.0\n"</span><span class="special">);</span>
+  <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>
+  <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">"index 0 maximum 2.0\n"</span>
+                     <span class="string">"index 1 maximum 4.0\n"</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+          The third example shows how to make and use an accumulator that accepts
+          multiple samples at once and an optional weight. The accumulator in the
+          example accepts two samples and independently computes the mean for each
+          one. This is more efficient than filling two separate profiles, because
+          the cell lookup has to be done only once.
+        </p>
+<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>
+<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="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
+  <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">// Accumulator accepts two samples and an optional weight and computes the mean of each.</span>
+  <span class="keyword">struct</span> <span class="identifier">multi_mean</span> <span class="special">{</span>
+    <span class="identifier">accumulators</span><span class="special">::</span><span class="identifier">mean</span><span class="special">&lt;&gt;</span> <span class="identifier">mx</span><span class="special">,</span> <span class="identifier">my</span><span class="special">;</span>
+
+    <span class="comment">// called when no weight is passed</span>
+    <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">double</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">{</span>
+      <span class="identifier">mx</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
+      <span class="identifier">my</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span>
+    <span class="special">}</span>
+
+    <span class="comment">// called when a weight is passed</span>
+    <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">weight_type</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">w</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">{</span>
+      <span class="identifier">mx</span><span class="special">(</span><span class="identifier">w</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span>
+      <span class="identifier">my</span><span class="special">(</span><span class="identifier">w</span><span class="special">,</span> <span class="identifier">y</span><span class="special">);</span>
+    <span class="special">}</span>
+  <span class="special">};</span>
+  <span class="comment">// Note: The implementation can be made more efficient by sharing the sum of weights.</span>
+
+  <span class="comment">// Create a 1D histogram that uses the custom accumulator.</span>
+  <span class="keyword">auto</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">make_histogram_with</span><span class="special">(</span><span class="identifier">dense_storage</span><span class="special">&lt;</span><span class="identifier">multi_mean</span><span class="special">&gt;(),</span> <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">2</span><span class="special">));</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</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="comment">// samples go to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">));</span>            <span class="comment">// samples go to first cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">6</span><span class="special">),</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">2</span><span class="special">));</span> <span class="comment">// samples go to second cell</span>
+  <span class="identifier">h</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">sample</span><span class="special">(</span><span class="number">7</span><span class="special">,</span> <span class="number">8</span><span class="special">),</span> <span class="identifier">weight</span><span class="special">(</span><span class="number">3</span><span class="special">));</span> <span class="comment">// samples go to second cell</span>
+
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">os</span><span class="special">;</span>
+  <span class="keyword">for</span> <span class="special">(</span><span class="keyword">auto</span><span class="special">&amp;&amp;</span> <span class="identifier">bin</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>
+    <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">"index %i mean-x %.1f mean-y %.1f\n"</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">bin</span><span class="special">.</span><span class="identifier">index</span><span class="special">()</span> <span class="special">%</span>
+              <span class="identifier">bin</span><span class="special">-&gt;</span><span class="identifier">mx</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">bin</span><span class="special">-&gt;</span><span class="identifier">my</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span>
+  <span class="special">}</span>
+  <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>
+  <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">"index 0 mean-x 2.0 mean-y 3.0\n"</span>
+                     <span class="string">"index 1 mean-x 6.2 mean-y 7.2\n"</span><span class="special">);</span>
 <span class="special">}</span>
 </pre>
 </div>