boost_mirror/histogram
1
0
Fork 0
mirror of https://github.com/boostorg/histogram.git synced 2025-05-09 23:04:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

more docs

Browse Source
This commit is contained in:
Hans Dembinski 2016-04-25 09:14:08 -04:00
parent ee984c3c9f
commit 88d3a2430c
8 changed files with 19 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/html/index.html
View File

@ -64,7 +64,7 @@
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="types.html#the-histogram-class">The Histogram Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#histogram-type">Histogram type</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#axis-types">Axis Types</a></li>
</ul>
</li>

1
doc/html/motivation.html
View File

@ -43,6 +43,7 @@
<h1>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline"></a></h1>
<p>There is a lack of a widely-used, free histogram class. While it is easy to write an 1-dimensional histogram, writing an n-dimensional histogram poses more of a challenge. If you add serialization and Python/Numpy support onto the wish-list, the air becomes thin.</p>
<p>The main competitor is the <a class="reference external" href="https://root.cern.ch">ROOT framework</a>. The histogram in this project is designed to be more convenient to use, and as fast or faster than the equivalent ROOT histograms. It comes without heavy baggage, instead it has a clean and modern C++ design which follows the advice given in popular C++ books, like those of <a class="reference external" href="http://www.aristeia.com/books.html">Meyers</a> and <a class="reference external" href="http://www.gotw.ca/publications/c++cs.htm">Sutter and Alexandrescu</a>.</p>
<p>Two of the main design goals are to conveniently hide the internal details on how things are counted, and to use the same interface for 1-dimensional and n-dimensional histograms. The count storage is an implementation detail, chosen automatically to be fast and efficient. The histogram should <em>just work</em>, users shouldn&#8217;t be forced to make choices among several storage options everytime they encounter a new data set.</p>
</div>

2
doc/html/notes.html
View File

@ -80,7 +80,7 @@
<dt>Properties</dt>
<dd>Getter/setter-like functions are wrapped as properties.</dd>
<dt>Keyword-based parameters</dt>
<dd>C++ member functions <a class="reference internal" href="types.html#_CPPv2N9histogram4fillEdz" title="histogram::fill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::fill()</span></code></a> and <a class="reference internal" href="types.html#_CPPv2N9histogram5wfillEjPKdd" title="histogram::wfill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::wfill()</span></code></a> are wrapped by the single Python member function <code class="xref py py-func docutils literal"><span class="pre">histogram.fill()</span></code></dd>
<dd>C++ member functions <a class="reference internal" href="types.html#_CPPv2N9histogram4fillEdz" title="histogram::fill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::fill()</span></code></a> and <a class="reference internal" href="types.html#_CPPv2N9histogram5wfillEjPKdd" title="histogram::wfill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::wfill()</span></code></a> are wrapped by the single Python member function <code class="xref py py-func docutils literal"><span class="pre">histogram.fill()</span></code> with an optional keyword parameter <code class="xref py py-obj docutils literal"><span class="pre">w</span></code> to pass a weight.</dd>
<dt>C++ convenience</dt>
<dd>C++ member function <a class="reference internal" href="types.html#_CPPv2NK9histogram4binsEj" title="histogram::bins"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::bins()</span></code></a> is omitted on the Python side, since it is very easy to just query this directly from the axis object in Python. On the C++ side, this would require a extra type cast or applying a visitor.</dd>
</dl>

2
doc/html/searchindex.js
View File

File diff suppressed because one or more lines are too long

12
doc/html/types.html
View File

@ -42,8 +42,8 @@
<div class="section" id="types">
<h1>Types<a class="headerlink" href="#types" title="Permalink to this headline"></a></h1>
<p>The library consists of a single <a class="reference internal" href="#_CPPv29histogram" title="histogram"><code class="xref cpp cpp-class docutils literal"><span class="pre">histogram</span></code></a> and several axis types which are stored in a <code class="docutils literal"><span class="pre">boost::variant</span></code> called <a class="reference internal" href="#_CPPv29axis_type" title="axis_type"><code class="xref cpp cpp-type docutils literal"><span class="pre">axis_type</span></code></a>. The axis types are created and passed to the constructor of the histogram to define its binning scheme. All following types are embedded in the <code class="docutils literal"><span class="pre">boost::histogram</span></code> namespace, which is omitted for brevity.</p>
<div class="section" id="the-histogram-class">
<h2>The Histogram Class<a class="headerlink" href="#the-histogram-class" title="Permalink to this headline"></a></h2>
<div class="section" id="histogram-type">
<h2>Histogram type<a class="headerlink" href="#histogram-type" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal"><span class="pre">#include</span> <span class="pre">&lt;boost/histogram/histogram.hpp&gt;</span></code></p>
<div class="section" id="c-interface">
<h3>C++ interface<a class="headerlink" href="#c-interface" title="Permalink to this headline"></a></h3>
@ -152,7 +152,7 @@
<dl class="function">
<dt id="_CPPv2NK9histogram5shapeEj">
<span id="histogram::shape__unsignedC"></span>unsigned <code class="descclassname"></code><code class="descname">shape</code><span class="sig-paren">(</span>unsigned <em>i</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv2NK9histogram5shapeEj" title="Permalink to this definition"></a></dt>
<dd><p>Returns the actual number of fields used by the axis. If the axis has underflow and overflow bins disabled, this is equal to <a class="reference internal" href="#_CPPv2NK9histogram4binsEj" title="histogram::bins"><code class="xref cpp cpp-func docutils literal"><span class="pre">bins()</span></code></a>. Otherwise, the number is larger by 2.</p>
<dd><p>Returns the actual number of fields used by the axis. If the axis has no underflow and overflow bins, this is equal to <a class="reference internal" href="#_CPPv2NK9histogram4binsEj" title="histogram::bins"><code class="xref cpp cpp-func docutils literal"><span class="pre">bins()</span></code></a>. Otherwise, the number is larger by 2.</p>
</dd></dl>
<dl class="function">
@ -183,7 +183,7 @@ template&lt;typename <code class="descname">T</code>&gt;</dt>
<dl class="method">
<dt id="histogram.histogram.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>*axes</em><span class="sig-paren">)</span><a class="headerlink" href="#histogram.histogram.__init__" title="Permalink to this definition"></a></dt>
<dd><p>Pass one or more axis objects to define the dimensions of the histogram.</p>
<dd><p>Pass one or more axis objects as arguments to define the dimensions of the histogram.</p>
</dd></dl>
<dl class="attribute">
@ -234,7 +234,7 @@ template&lt;typename <code class="descname">T</code>&gt;</dt>
<dt id="histogram.histogram.fill">
<code class="descname">fill</code><span class="sig-paren">(</span><em>*values</em>, <em>w=None</em><span class="sig-paren">)</span><a class="headerlink" href="#histogram.histogram.fill" title="Permalink to this definition"></a></dt>
<dd><p>Pass a sequence of values with a length <code class="docutils literal"><span class="pre">n</span></code> is equal to the dimensions of the histogram, and optionally a weight <code class="xref py py-obj docutils literal"><span class="pre">w</span></code> for this fill (<em>int</em> or <em>float</em>).</p>
<p>If Numpy support is enabled, values my also be a 2d-array of shape (<code class="docutils literal"><span class="pre">m</span></code>, <code class="docutils literal"><span class="pre">n</span></code>), where <code class="docutils literal"><span class="pre">m</span></code> is the number of tuples, and optionally another a second 1d-array <code class="xref py py-obj docutils literal"><span class="pre">w</span></code> of shape (<code class="docutils literal"><span class="pre">n</span></code>,).</p>
<p>If Numpy support is enabled, <code class="xref py py-obj docutils literal"><span class="pre">values</span></code> my also be a 2d-array of shape <code class="docutils literal"><span class="pre">(m,</span> <span class="pre">n)</span></code>, where <code class="docutils literal"><span class="pre">m</span></code> is the number of tuples to pass at once, and optionally another a second 1d-array <code class="xref py py-obj docutils literal"><span class="pre">w</span></code> of shape <code class="docutils literal"><span class="pre">(m,)</span></code>.</p>
</dd></dl>
<dl class="method">
@ -484,7 +484,7 @@ template&lt;typename <code class="descname">T</code>&gt;</dt>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes.html">Notes</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#the-histogram-class">The Histogram Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#histogram-type">Histogram type</a></li>
<li class="toctree-l2"><a class="reference internal" href="#axis-types">Axis Types</a></li>
</ul>
</li>

2
doc/sphinx/motivation.rst
View File

@ -4,3 +4,5 @@ Motivation
There is a lack of a widely-used, free histogram class. While it is easy to write an 1-dimensional histogram, writing an n-dimensional histogram poses more of a challenge. If you add serialization and Python/Numpy support onto the wish-list, the air becomes thin.
The main competitor is the `ROOT framework <https://root.cern.ch>`_. The histogram in this project is designed to be more convenient to use, and as fast or faster than the equivalent ROOT histograms. It comes without heavy baggage, instead it has a clean and modern C++ design which follows the advice given in popular C++ books, like those of `Meyers <http://www.aristeia.com/books.html>`_ and `Sutter and Alexandrescu <http://www.gotw.ca/publications/c++cs.htm>`_.
Two of the main design goals are to conveniently hide the internal details on how things are counted, and to use the same interface for 1-dimensional and n-dimensional histograms. The count storage is an implementation detail, chosen automatically to be fast and efficient. The histogram should *just work*, users shouldn't be forced to make choices among several storage options everytime they encounter a new data set.

2
doc/sphinx/notes.rst
View File

@ -45,7 +45,7 @@ Properties
Getter/setter-like functions are wrapped as properties.
Keyword-based parameters
C++ member functions :cpp:func:`histogram::fill` and :cpp:func:`histogram::wfill` are wrapped by the single Python member function :py:func:`histogram.fill`
C++ member functions :cpp:func:`histogram::fill` and :cpp:func:`histogram::wfill` are wrapped by the single Python member function :py:func:`histogram.fill` with an optional keyword parameter :py:obj:`w` to pass a weight.
C++ convenience
C++ member function :cpp:func:`histogram::bins` is omitted on the Python side, since it is very easy to just query this directly from the axis object in Python. On the C++ side, this would require a extra type cast or applying a visitor.

12
doc/sphinx/types.rst
View File

@ -3,8 +3,8 @@ Types
The library consists of a single :cpp:class:`histogram` and several axis types which are stored in a ``boost::variant`` called :cpp:type:`axis_type`. The axis types are created and passed to the constructor of the histogram to define its binning scheme. All following types are embedded in the ``boost::histogram`` namespace, which is omitted for brevity.
The Histogram Class
-------------------
Histogram type
--------------
``#include <boost/histogram/histogram.hpp>``
@ -93,7 +93,7 @@ C++ interface
.. cpp:function:: unsigned shape(unsigned i) const
Returns the actual number of fields used by the axis. If the axis has underflow and overflow bins disabled, this is equal to :cpp:func:`bins`. Otherwise, the number is larger by 2.
Returns the actual number of fields used by the axis. If the axis has no underflow and overflow bins, this is equal to :cpp:func:`bins`. Otherwise, the number is larger by 2.
.. cpp:function:: template <typename T> T& axis(unsigned i)
@ -112,7 +112,7 @@ Python interface
.. py:method:: __init__(*axes)
Pass one or more axis objects to define the dimensions of the histogram.
Pass one or more axis objects as arguments to define the dimensions of the histogram.
.. autoattribute:: dim
@ -124,12 +124,12 @@ Python interface
Pass a sequence of values with a length ``n`` is equal to the dimensions of the histogram, and optionally a weight :py:obj:`w` for this fill (*int* or *float*).
If Numpy support is enabled, values my also be a 2d-array of shape (``m``, ``n``), where ``m`` is the number of tuples, and optionally another a second 1d-array :py:obj:`w` of shape (``n``,).
If Numpy support is enabled, :py:obj:`values` my also be a 2d-array of shape ``(m, n)``, where ``m`` is the number of tuples to pass at once, and optionally another a second 1d-array :py:obj:`w` of shape ``(m,)``.
.. py:method:: value(*indices)
:param int indices: indices of the bin
:return: value for the bin
:return: count for the bin
.. py:method:: variance(*indices)