Return specified diagonals. If `a` is 2-D, returns the diagonal of `a` with the given offset, i.e., the collection of elements of the form ``a[i, i+offset]``. If `a` has more than two dimensions, then the axes specified by `axis1` and `axis2` are used to determine the 2-D sub-
(a, offset=0, axis1=0, axis2=1)
| 1564 | |
| 1565 | @array_function_dispatch(_diagonal_dispatcher) |
| 1566 | def diagonal(a, offset=0, axis1=0, axis2=1): |
| 1567 | """ |
| 1568 | Return specified diagonals. |
| 1569 | |
| 1570 | If `a` is 2-D, returns the diagonal of `a` with the given offset, |
| 1571 | i.e., the collection of elements of the form ``a[i, i+offset]``. If |
| 1572 | `a` has more than two dimensions, then the axes specified by `axis1` |
| 1573 | and `axis2` are used to determine the 2-D sub-array whose diagonal is |
| 1574 | returned. The shape of the resulting array can be determined by |
| 1575 | removing `axis1` and `axis2` and appending an index to the right equal |
| 1576 | to the size of the resulting diagonals. |
| 1577 | |
| 1578 | In versions of NumPy prior to 1.7, this function always returned a new, |
| 1579 | independent array containing a copy of the values in the diagonal. |
| 1580 | |
| 1581 | In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, |
| 1582 | but depending on this fact is deprecated. Writing to the resulting |
| 1583 | array continues to work as it used to, but a FutureWarning is issued. |
| 1584 | |
| 1585 | Starting in NumPy 1.9 it returns a read-only view on the original array. |
| 1586 | Attempting to write to the resulting array will produce an error. |
| 1587 | |
| 1588 | In some future release, it will return a read/write view and writing to |
| 1589 | the returned array will alter your original array. The returned array |
| 1590 | will have the same type as the input array. |
| 1591 | |
| 1592 | If you don't write to the array returned by this function, then you can |
| 1593 | just ignore all of the above. |
| 1594 | |
| 1595 | If you depend on the current behavior, then we suggest copying the |
| 1596 | returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead |
| 1597 | of just ``np.diagonal(a)``. This will work with both past and future |
| 1598 | versions of NumPy. |
| 1599 | |
| 1600 | Parameters |
| 1601 | ---------- |
| 1602 | a : array_like |
| 1603 | Array from which the diagonals are taken. |
| 1604 | offset : int, optional |
| 1605 | Offset of the diagonal from the main diagonal. Can be positive or |
| 1606 | negative. Defaults to main diagonal (0). |
| 1607 | axis1 : int, optional |
| 1608 | Axis to be used as the first axis of the 2-D sub-arrays from which |
| 1609 | the diagonals should be taken. Defaults to first axis (0). |
| 1610 | axis2 : int, optional |
| 1611 | Axis to be used as the second axis of the 2-D sub-arrays from |
| 1612 | which the diagonals should be taken. Defaults to second axis (1). |
| 1613 | |
| 1614 | Returns |
| 1615 | ------- |
| 1616 | array_of_diagonals : ndarray |
| 1617 | If `a` is 2-D, then a 1-D array containing the diagonal and of the |
| 1618 | same type as `a` is returned unless `a` is a `matrix`, in which case |
| 1619 | a 1-D array rather than a (2-D) `matrix` is returned in order to |
| 1620 | maintain backward compatibility. |
| 1621 | |
| 1622 | If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2` |
| 1623 | are removed, and a new axis inserted at the end corresponding to the |
no test coverage detected