Keyword numpy (#143)

* Add bhistogram*, remove debug printout

* Use keyword arguments instead

Author: henryiii

CHANGELOG.md

@@ -0,0 +1,8 @@
+## Version 0.5
+
+First beta release and beginning of the changelog.
+
+#### Known issues:
+
+* Unlimited storage does not support pickling or classic multiprocessing
+* Some non-simple storages do not support some forms of access, like `.view`

README.md

@@ -26,12 +26,11 @@ For the moment, you need to uninstall and reinstall to ensure you have the lates
 
 ## Usage
 
-This is a suggested example of usage.
 
 ```python
 import boost_histogram as bh
 
-# Compose axis however you like
+# Compose axis however you like; this is a 2D histogram
 hist = bh.histogram(bh.axis.regular(2, 0, 1),
                     bh.axis.regular(4, 0.0, 1.0))
 
@@ -53,21 +52,25 @@ counts = hist.view()
     * `bh.axis.regular_pow(n, start, stop, power)`: Regularly spaced value to some `power`
     * `bh.axis.integer(start, stop, underflow=True, overflow=True, growth=False)`: Special high-speed version of `regular` for evenly spaced bins of width 1
     * `bh.axis.variable([start, edge1, edge2, ..., stop], underflow=True, overflow=True)`: Uneven bin spacing
-    * `bh.axis.category([...], growth=False)`: Integer or (WIP) string categories
+    * `bh.axis.category([...], growth=False)`: Integer or string categories
 * Axis features:
+    * `.index(values)`: The index at a point (or points) on the axis
+    * `.value(indexes)`: The value for a fractional bin in the axis
+    * `.bin(i)`: The bin given an integer index
+    * `.options`: The options the axis was created with
+    * `.metadata`: Anything a user wants to store
+    * `.size`: The number of bins (not including under/overflow)
+    * `.extent`: The number of bins (including under/overflow)
     * `.bin(i)`: The bin or a bin view for continuous axis types
         * `.lower()`: The lower value
         * `.upper()`: The upper value
         * `.center()`: The center value
         * `.width()`: The bin width
-    * `.bins()`: A list of bins or bin views
-    * `.size()`: The number of bins (not including under/overflow)
-    * `.size(flow=True)`: The number of bins (including under/overflow)
     * `.options()`: The options set on the axis (`bh.axis.options` bitfields)
-    * `.edges(flow=False)`: The N+1 bin edges (if continuous)
-    * `.centers(flow=False)`: The N bin centers (if continuous)
-    * `.index(values)`: The index at a point (or points) on the axis
-    * `.value(index)`: The value for a fractional bin in the axis
+    * `.edges`: The N+1 bin edges (if continuous)
+    * `.centers`: The N bin centers (if continuous)
+    * `.widths`: The N bin widths
+
 * Many storage types
     * `bh.storage.int`: 64 bit unsigned integers for high performance and useful view access
     * `bh.storage.double`: Doubles for weighted values
@@ -82,30 +85,29 @@ counts = hist.view()
     * `bh.accumulator.sum`: High accuracy sum (Neumaier)
     * `bh.accumulator.mean`: Running count, mean, and variance (Welfords's incremental algorithm)
 * Histogram operations
-    * `.fill(arr, ..., weight=...)` Fill with N arrays or single values
-    * `(a, b, ...)`: Fill with arrays or single values
-    * `+`: Add two histograms
-    * `.rank()`: The number of dimensions
-    * `.size()`: The number of bins (include under/overflow bins)
+    * `h.fill(arr, ..., weight=...)` Fill with N arrays or single values
+    * `h.rank`: The number of dimensions
+    * `h.size or len(h)`: The number of bins
     * `.reset()`: Set counters to 0
+    * `+`: Add two histograms
     * `*=`: Multiply by a scaler (not all storages) (`hist * scalar` and `scalar * hist` supported too)
     * `/=`: Divide by a scaler (not all storages) (`hist / scalar` supported too)
     * `.to_numpy(flow=False)`: Convert to a numpy style tuple (with or without under/overflow bins)
     * `.view(flow=False)`: Get a view on the bin contents (with or without under/overflow bins)
-    * `np.asarray(...)`: Get a view on the bin contents with under/overflow bins
     * `.axis(i)`: Get the `i`th axis
-    * `.at(i, j, ...)`: Get the bin contents as a location
-    * `.sum()`: The total count of all bins
+    * `.sum(flow=False)`: The total count of all bins
     * `.project(ax1, ax2, ...)`: Project down to listed axis (numbers)
     * `.reduce(ax, reduce_option, ...)`: shrink, rebin, or slice, or any combination
+    <!--
     * `.indexed(flow=False)`: Iterate over the bins with a special "indexed" iterator
         * `ind.content`: The contents of a bin (set or get)
         * `ind.bins()`: A list of bins
         * `ind.centers()`: The centers of each bin
         * `ind.indices()`: A list of indices
+    -->
+* Indexing - Supports the Unified Histogram Indexing (UHI) proposal
 * Details
     * Use `bh.histogram(..., storage=...)` to make a histogram (there are several different types)
-    * Several common combinations are optimized, such as regular axes + int storage
 
 
 ## Supported platforms

boost_histogram/__init__.py

@@ -2,9 +2,7 @@
 
 from ._hist import histogram
 
-from . import axis, storage, accumulators, algorithm
-
-# The numpy module is not imported yet - waiting until it is stable
+from . import axis, storage, accumulators, algorithm, numpy
 
 from .utils import loc, rebin, project, indexed, underflow, overflow
 

boost_histogram/_hist.py

@@ -27,20 +27,23 @@ def _make_histogram(*args, **kwargs):
     Make a histogram with an optional storage (keyword only).
     """
 
+    # Keyword only trick (change when Python2 is dropped)
     with KWArgs(kwargs) as k:
         storage = k.optional("storage", _core.storage.double())
 
     # Initialize storage if user has not
     if isinstance(storage, type):
         storage = storage()
 
+    # Allow a tuple to represent a regular axis
     args = [_arg_shortcut(arg) for arg in args]
 
     if len(args) > _core.hist._axes_limit:
         raise IndexError(
             "Too many axes, must be less than {}".format(_core.hist._axes_limit)
         )
 
+    # Check all available histograms, and if the storage matches, return that one
     for h in _histograms:
         if isinstance(storage, h._storage_type):
             return h(args, storage)

boost_histogram/numpy.py

@@ -1,19 +1,26 @@
 from __future__ import absolute_import, division, print_function
 
+del absolute_import, division, print_function  # hides these from IPython
+
 from . import axis as _axis
 from . import _hist as _hist
 from . import core as _core
 
-import warnings
+from .utils import KWArgs as _KWArgs
+
+import numpy as _np
+
+__all__ = ("histogram", "histogram2d", "histogramdd")
 
-warnings.warn(
-    "The boost_histogram.numpy module is provisional and may change in future releases",
-    FutureWarning,
-)
 
+def histogramdd(
+    a, bins=10, range=None, normed=None, weights=None, density=None, **kwargs
+):
+    np = _np  # Hidden to keep module clean
 
-def histogramdd(a, bins=10, range=None, normed=None, weights=None, density=None):
-    import numpy as np
+    with _KWArgs(kwargs) as k:
+        boost = k.optional("bh", False)
+        storage = k.optional("bh_storage", _core.storage.double)
 
     if normed is not None:
         raise KeyError(
@@ -24,7 +31,7 @@ def histogramdd(a, bins=10, range=None, normed=None, weights=None, density=None)
             "boost-histogram does not support the density keyword at the moment"
         )
 
-    # Odd design here. Oh well.
+    # Odd numpy design here. Oh well.
     if isinstance(a, np.ndarray):
         a = a.T
 
@@ -53,23 +60,49 @@ def histogramdd(a, bins=10, range=None, normed=None, weights=None, density=None)
             axs.append(_axis.variable(b))
 
     if weights is None:
-        return _hist.histogram(*axs).fill(*a)
+        hist = _hist.histogram(*axs).fill(*a)
     else:
-        return _hist.histogram(*axis).fill(*a, weight=weights)
+        hist = _hist.histogram(*axis).fill(*a, weight=weights)
+
+    return hist if boost else hist.to_numpy()
+
 
+def histogram2d(
+    x, y, bins=10, range=None, normed=None, weights=None, density=None, **kwargs
+):
+    return histogramdd((x, y), bins, range, normed, weights, density, **kwargs)
 
-def histogram2d(x, y, bins=10, range=None, normed=None, weights=None, density=None):
-    return histogramdd((x, y), bins, range, normed, weights, density)
 
+def histogram(
+    a, bins=10, range=None, normed=None, weights=None, density=None, **kwargs
+):
+    np = _np
 
-def histogram(x, bins=10, range=None, normed=None, weights=None, density=None):
-    import numpy as np
+    # numpy 1d histogram returns integers in some cases
+    if "bh_storage" not in kwargs and not (weights or normed or density):
+        kwargs["bh_storage"] = _core.storage.int
 
     if isinstance(bins, str):
         if tuple(int(x) for x in np.__version__.split(".")[:2]) < (1, 13):
             raise KeyError(
                 "Upgrade numpy to 1.13+ to use string arguments to boost-histogram's histogram function"
             )
-        bins = np.histogram_bin_edges(x, bins, range, weights)
-    return histogramdd((x,), (bins,), (range,), normed, weights, density)
-    # TODO: this also supports a few more tricks in Numpy, those can be added for numpy 1.13+
+        bins = np.histogram_bin_edges(a, bins, range, weights)
+    return histogramdd((a,), (bins,), (range,), normed, weights, density, **kwargs)
+
+
+# Process docstrings
+for f, n in zip(
+    (histogram, histogram2d, histogramdd),
+    (_np.histogram, _np.histogram2d, _np.histogramdd),
+):
+
+    H = """\
+    Return a boost-histogram object using the same arguments as numpy's {}.
+    This does not support density/normed yet. Two extra arguments are added: bh=True
+    will enable object based output, and bh_storage=... lets you set the storage used.
+    """
+
+    f.__doc__ = H.format(n.__name__) + n.__doc__
+
+del f, n, H

include/boost/histogram/python/regular_numpy.hpp

@@ -30,7 +30,6 @@ class regular_numpy : public bh::axis::regular<double, bh::use_default, metadata
         , stop_(0){};
 
     boost::histogram::axis::index_type index(value_type v) const {
-        std::cout << "stop: " << stop_ << std::endl;
         return v <= stop_ ? std::min(regular::index(v), size() - 1) : regular::index(v);
     }
 

tests/test_numpy.py

@@ -46,7 +46,7 @@
 def test_histogram1d(a, opt):
     v = np.array(a)
     h1, e1 = np.histogram(v, **opt)
-    h2, e2 = bhnp.histogram(v, **opt).to_numpy()
+    h2, e2 = bhnp.histogram(v, **opt)
 
     np.testing.assert_array_almost_equal(e1, e2)
     np.testing.assert_array_equal(h1, h2)
@@ -57,7 +57,7 @@ def test_histogram2d():
     y = np.array([0.4, 0.5, 0.22, 0.65, 0.32, 0.01, 0.23, 1.98])
 
     h1, e1x, e1y = np.histogram2d(x, y)
-    h2, e2x, e2y = bhnp.histogram2d(x, y).to_numpy()
+    h2, e2x, e2y = bhnp.histogram2d(x, y)
 
     np.testing.assert_array_almost_equal(e1x, e2x)
     np.testing.assert_array_almost_equal(e1y, e2y)