Merge pull request #3531 from fkbreitl/master

Updated documentation for histogram2d() in twodim_base.py according to discussion

1 files changed, 45 insertions, 15 deletions

diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 94dfbe796..c4cbaa9f1 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -585,21 +585,51 @@ def histogram2d(x, y, bins=10, range=None, normed=False, weights=None):
 
     Examples
     --------
-    >>> x, y = np.random.randn(2, 100)
-    >>> H, xedges, yedges = np.histogram2d(x, y, bins=(5, 8))
-    >>> H.shape, xedges.shape, yedges.shape
-    ((5, 8), (6,), (9,))
-
-    We can now use the Matplotlib to visualize this 2-dimensional histogram:
-
-    >>> extent = [yedges[0], yedges[-1], xedges[-1], xedges[0]]
-    >>> import matplotlib.pyplot as plt
-    >>> plt.imshow(H, extent=extent, interpolation='nearest')
-    <matplotlib.image.AxesImage object at ...>
-    >>> plt.colorbar()
-    <matplotlib.colorbar.Colorbar instance at ...>
-    >>> plt.show()
-
+    2D-histogram with variable bin width:
+
+    import matplotlib as ml
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    # First we define the bin edges                                                
+    xedges = [0, 1, 1.5, 3, 5]
+    yedges = [0, 2, 3, 4, 6]
+
+    # Next we create a histogram H with random bin content                         
+    x = np.random.normal(3, 1, 100)
+    y = np.random.normal(1, 1, 100)
+    H, xedges, yedges = np.histogram2d(y, x, bins=(xedges, yedges))
+
+    # Or we fill the histogram H with a determined bin content                     
+    H = np.ones((4, 4)).cumsum().reshape(4, 4)
+    print H[::-1]  # This shows the bin content in the order as plotted            
+
+    fig = plt.figure(figsize=(7, 3))
+    # Imshow can only do an equidistant representation of bins                     
+    ax = fig.add_subplot(131)
+    ax.set_title('imshow:\nequidistant')
+    im = plt.imshow(H, interpolation='nearest', origin='low',
+                    extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]])
+
+    # pcolormesh can displaying exact bin edges                                    
+    ax = fig.add_subplot(132)
+    ax.set_title('pcolormesh:\nexact bin edges')
+    X, Y = np.meshgrid(xedges, yedges)
+    ax.pcolormesh(X, Y, H)
+    ax.set_aspect('equal')
+    
+    # NonUniformImage displays exact bin edges with interpolation                  
+    ax = fig.add_subplot(133)
+    ax.set_title('NonUniformImage:\ninterpolated')
+    im = ml.image.NonUniformImage(ax, interpolation='bilinear')
+    xcenters = xedges[:-1] + 0.5 * (xedges[1:] - xedges[:-1])
+    ycenters = yedges[:-1] + 0.5 * (yedges[1:] - yedges[:-1])
+    im.set_data(xcenters, ycenters, H)
+    ax.images.append(im)
+    ax.set_xlim(xedges[0], xedges[-1])
+    ax.set_ylim(yedges[0], yedges[-1])
+    ax.set_aspect('equal')
+    plt.show()
     """
     from numpy import histogramdd