Merge pull request #5567 from ahjulstad/histogram2d-docstring

DOC: Updated docstring for histogram2d as suggested in issue #5538

2 files changed, 36 insertions, 3 deletions

diff --git a/numpy/lib/tests/test_twodim_base.py b/numpy/lib/tests/test_twodim_base.py
index 739061a5d..b65a8df97 100644
--- a/numpy/lib/tests/test_twodim_base.py
+++ b/numpy/lib/tests/test_twodim_base.py
@@ -265,6 +265,37 @@ class TestHistogram2d(TestCase):
         a, edge1, edge2 = histogram2d([], [], bins=4)
         assert_array_max_ulp(a, np.zeros((4, 4)))
 
+    def test_binparameter_combination(self):
+        x = array(
+            [0, 0.09207008,  0.64575234,  0.12875982,  0.47390599,  
+             0.59944483, 1])
+        y = array(
+            [0, 0.14344267,  0.48988575,  0.30558665,  0.44700682,  
+             0.15886423, 1])
+        edges = (0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1)
+        H, xe, ye = histogram2d(x, y, (edges, 4))
+        answer = array(
+            [[ 2.,  0.,  0.,  0.],
+             [ 0.,  1.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.],
+             [ 0.,  1.,  0.,  0.],
+             [ 1.,  0.,  0.,  0.],
+             [ 0.,  1.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.],
+             [ 0.,  0.,  0.,  1.]])
+        assert_array_equal(H, answer)
+        assert_array_equal(ye, array([0., 0.25, 0.5, 0.75, 1]))
+        H, xe, ye = histogram2d(x, y, (4, edges))
+        answer = array(
+            [[ 1.,  1.,  0.,  1.,  0.,  0.,  0.,  0.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.,  1.,  0.,  0.,  0.,  0.,  0.],
+             [ 0.,  1.,  0.,  0.,  1.,  0.,  0.,  0.,  0.,  0.],
+             [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  1.]])
+        assert_array_equal(H, answer)
+        assert_array_equal(xe, array([0., 0.25, 0.5, 0.75, 1]))
+
 
 class TestTri(TestCase):
     def test_dtype(self):
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 24dc3cced..464ffd914 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -589,16 +589,18 @@ def histogram2d(x, y, bins=10, range=None, normed=False, weights=None):
     y : array_like, shape (N,)
         An array containing the y coordinates of the points to be
         histogrammed.
-    bins : int or [int, int] or array_like or [array, array], optional
+    bins : int or array_like or [int, int] or [array, array], optional
         The bin specification:
 
           * If int, the number of bins for the two dimensions (nx=ny=bins).
-          * If [int, int], the number of bins in each dimension
-            (nx, ny = bins).
           * If array_like, the bin edges for the two dimensions
             (x_edges=y_edges=bins).
+          * If [int, int], the number of bins in each dimension
+            (nx, ny = bins).
           * If [array, array], the bin edges in each dimension
             (x_edges, y_edges = bins).
+          * A combination [int, array] or [array, int], where int
+            is the number of bins and array is the bin edges.
 
     range : array_like, shape(2,2), optional
         The leftmost and rightmost edges of the bins along each dimension