DOC: Added anti-diagonal examples to np.diagonal and np.fill_diagonal

2 files changed, 40 insertions, 8 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index cb10c3947..0e89277d8 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1531,9 +1531,9 @@ def diagonal(a, offset=0, axis1=0, axis2=1):
             [2, 3]],
            [[4, 5],
             [6, 7]]])
-    >>> a.diagonal(0, # Main diagonals of two arrays created by skipping
-    ...            0, # across the outer(left)-most axis last and
-    ...            1) # the "middle" (row) axis first.
+    >>> a.diagonal(0,  # Main diagonals of two arrays created by skipping
+    ...            0,  # across the outer(left)-most axis last and
+    ...            1)  # the "middle" (row) axis first.
     array([[0, 6],
            [1, 7]])
 
@@ -1541,13 +1541,28 @@ def diagonal(a, offset=0, axis1=0, axis2=1):
     corresponds to fixing the right-most (column) axis, and that the
     diagonals are "packed" in rows.
 
-    >>> a[:,:,0] # main diagonal is [0 6]
+    >>> a[:,:,0]  # main diagonal is [0 6]
     array([[0, 2],
            [4, 6]])
-    >>> a[:,:,1] # main diagonal is [1 7]
+    >>> a[:,:,1]  # main diagonal is [1 7]
     array([[1, 3],
            [5, 7]])
 
+    The anti-diagonal can be obtained by reversing the order of elements
+    using either `numpy.flipud` or `numpy.fliplr`.
+
+    >>> a = np.arange(9).reshape(3, 3)
+    >>> a
+    array([[0, 1, 2],
+           [3, 4, 5],
+           [6, 7, 8]])
+    >>> np.fliplr(a).diagonal()  # Horizontal flip
+    array([2, 4, 6])
+    >>> np.flipud(a).diagonal()  # Vertical flip
+    array([6, 4, 2])
+
+    Note that the order in which the diagonal is retrieved varies depending
+    on the flip function.
     """
     if isinstance(a, np.matrix):
         # Make diagonal of matrix 1-D to preserve backward compatibility.
diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py
index 8d4b1ce1e..40c1cda05 100644
--- a/numpy/lib/index_tricks.py
+++ b/numpy/lib/index_tricks.py
@@ -813,7 +813,7 @@ def fill_diagonal(a, val, wrap=False):
     The wrap option affects only tall matrices:
 
     >>> # tall matrices no wrap
-    >>> a = np.zeros((5, 3),int)
+    >>> a = np.zeros((5, 3), int)
     >>> np.fill_diagonal(a, 4)
     >>> a
     array([[4, 0, 0],
@@ -823,7 +823,7 @@ def fill_diagonal(a, val, wrap=False):
            [0, 0, 0]])
 
     >>> # tall matrices wrap
-    >>> a = np.zeros((5, 3),int)
+    >>> a = np.zeros((5, 3), int)
     >>> np.fill_diagonal(a, 4, wrap=True)
     >>> a
     array([[4, 0, 0],
@@ -833,13 +833,30 @@ def fill_diagonal(a, val, wrap=False):
            [4, 0, 0]])
 
     >>> # wide matrices
-    >>> a = np.zeros((3, 5),int)
+    >>> a = np.zeros((3, 5), int)
     >>> np.fill_diagonal(a, 4, wrap=True)
     >>> a
     array([[4, 0, 0, 0, 0],
            [0, 4, 0, 0, 0],
            [0, 0, 4, 0, 0]])
 
+    The anti-diagonal can be filled by reversing the order of elements
+    using either `numpy.flipud` or `numpy.fliplr`.
+
+    >>> a = np.zeros((3, 3), int);
+    >>> np.fill_diagonal(np.fliplr(a), [1,2,3])  # Horizontal flip
+    >>> a
+    array([[0, 0, 1],
+           [0, 2, 0],
+           [3, 0, 0]])
+    >>> np.fill_diagonal(np.flipud(a), [1,2,3])  # Vertical flip
+    >>> a
+    array([[0, 0, 3],
+           [0, 2, 0],
+           [1, 0, 0]])
+
+    Note that the order in which the diagonal is filled varies depending
+    on the flip function.
     """
     if a.ndim < 2:
         raise ValueError("array must be at least 2-d")