Repository: numpy/numpy

Issue:
Documentation issue: np.histogram2D, non-functioning example for pcolormesh
Hi all,

np.histogram2d online documentation gives an non-functioning example.

Documentation page:
http://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram2d.html

Non-functioning example:

```
pcolormesh can display exact bin edges:
>>> ax = fig.add_subplot(132)
>>> ax.set_title('pcolormesh: exact bin edges')
>>> X, Y = np.meshgrid(xedges, yedges)
>>> ax.pcolormesh(X, Y, H)
>>> ax.set_aspect('equal')
```

Problem with example:
numpy.histogram2d returns an array H shaped (nx, ny).
numpy.meshgrid returns X, Y arrays shaped (ny, nx).   [When called with the default Cartesian indexing]
Therefore, X,Y are incompatible with H for pcolormesh, which gives an error.

Proposed updated example (transpose H):

```
pcolormesh can display exact bin edges:
>>> ax = fig.add_subplot(132)
>>> ax.set_title('pcolormesh: exact bin edges')
>>> X, Y = np.meshgrid(xedges, yedges)
>>> ax.pcolormesh(X, Y, H.T)
>>> ax.set_aspect('equal')
```



Discussion:
H happens to be a square matrix in the documentation example, so here's a short bit to reproduce the problem:

``` python
import matplotlib.pyplot as plt
import numpy as np

H, xedges, yedges = np.histogram2d([], [], bins=(2, 4))
X, Y = np.meshgrid(xedges, yedges)
plt.pcolormesh(X, Y, H)
```

(With X and Y of dimensions 5x3 and H 2x4.)

Yes, thanks for that update! So, the example script technically does work! I hadn't noticed this; my apologies. I think we both agree it is nonetheless bad documentation (it only executes because, by chance, nx=ny, and in the plot it flips the X and Y axes nonetheless). The proposed fix I think is much better documentation.


Resolving patch:
diff --git a/doc/source/conf.py b/doc/source/conf.py
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -199,7 +199,10 @@
 # -----------------------------------------------------------------------------
 # Intersphinx configuration
 # -----------------------------------------------------------------------------
-intersphinx_mapping = {'http://docs.python.org/dev': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/dev', None),
+    'matplotlib': ('http://matplotlib.org', None)
+}
 
 
 # -----------------------------------------------------------------------------
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -599,52 +599,40 @@ def histogram2d(x, y, bins=10, range=None, normed=False, weights=None):
     Construct a 2-D histogram with variable bin width. First define the bin
     edges:
 
-    >>> xedges = [0, 1, 1.5, 3, 5]
+    >>> xedges = [0, 1, 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)
+    >>> x = np.random.normal(2, 1, 100)
     >>> y = np.random.normal(1, 1, 100)
-    >>> H, xedges, yedges = np.histogram2d(y, x, bins=(xedges, yedges))
+    >>> H, xedges, yedges = np.histogram2d(x, y, bins=(xedges, yedges))
+    >>> H = H.T  # Let each row list bins with common y range.
 
-    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
-    [[ 13.  14.  15.  16.]
-     [  9.  10.  11.  12.]
-     [  5.   6.   7.   8.]
-     [  1.   2.   3.   4.]]
-
-    Imshow can only do an equidistant representation of bins:
+    :func:`imshow <matplotlib.pyplot.imshow>` can only display square bins:
 
     >>> fig = plt.figure(figsize=(7, 3))
-    >>> ax = fig.add_subplot(131)
-    >>> ax.set_title('imshow: equidistant')
-    >>> im = plt.imshow(H, interpolation='nearest', origin='low',
-    ...            extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]])
+    >>> ax = fig.add_subplot(131, title='imshow: square bins')
+    >>> plt.imshow(H, interpolation='nearest', origin='low',
+    ...         extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]])
 
-    pcolormesh can display exact bin edges:
+    :func:`pcolormesh <matplotlib.pyplot.pcolormesh>` can display actual edges:
 
-    >>> ax = fig.add_subplot(132)
-    >>> ax.set_title('pcolormesh: exact bin edges')
+    >>> ax = fig.add_subplot(132, title='pcolormesh: actual edges',
+    ...         aspect='equal')
     >>> X, Y = np.meshgrid(xedges, yedges)
     >>> ax.pcolormesh(X, Y, H)
-    >>> ax.set_aspect('equal')
 
-    NonUniformImage displays exact bin edges with interpolation:
+    :class:`NonUniformImage <matplotlib.image.NonUniformImage>` can be used to
+    display actual bin edges with interpolation:
 
-    >>> ax = fig.add_subplot(133)
-    >>> ax.set_title('NonUniformImage: interpolated')
+    >>> ax = fig.add_subplot(133, title='NonUniformImage: interpolated',
+    ...         aspect='equal', xlim=xedges[[0, -1]], ylim=yedges[[0, -1]])
     >>> im = mpl.image.NonUniformImage(ax, interpolation='bilinear')
-    >>> xcenters = xedges[:-1] + 0.5 * (xedges[1:] - xedges[:-1])
-    >>> ycenters = yedges[:-1] + 0.5 * (yedges[1:] - yedges[:-1])
+    >>> xcenters = (xedges[:-1] + xedges[1:]) / 2
+    >>> ycenters = (yedges[:-1] + yedges[1:]) / 2
     >>> 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()
 
     """


Test patch: