diff options
author | Petar Mlinarić <petar.mlinaric@gmail.com> | 2022-07-19 01:23:40 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-07-19 09:23:40 +0300 |
commit | 14c92e414cb5c5ab77aa8af9eb9e6d810b28ff4d (patch) | |
tree | 627a52da4a5017e2aef751230642d0e081d1da18 /numpy | |
parent | fe2bb380fd9a084b622ff3f00cb6f245e8c1a10e (diff) | |
download | numpy-14c92e414cb5c5ab77aa8af9eb9e6d810b28ff4d.tar.gz |
DOC: unify `np.transpose`, `np.ndarray.transpose`, and `np.ndarray.T` (#21997)
Better organize and improve cross referencing between the various transpose
functions/methods.
Co-authored-by: Rohit Goswami <r95g10@gmail.com>
Diffstat (limited to 'numpy')
-rw-r--r-- | numpy/core/_add_newdocs.py | 55 | ||||
-rw-r--r-- | numpy/core/fromnumeric.py | 66 |
2 files changed, 64 insertions, 57 deletions
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py index 50ec50d2d..aeecb0cb3 100644 --- a/numpy/core/_add_newdocs.py +++ b/numpy/core/_add_newdocs.py @@ -2886,24 +2886,25 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('strides', add_newdoc('numpy.core.multiarray', 'ndarray', ('T', """ - The transposed array. + View of the transposed array. Same as ``self.transpose()``. Examples -------- - >>> x = np.array([[1.,2.],[3.,4.]]) - >>> x - array([[ 1., 2.], - [ 3., 4.]]) - >>> x.T - array([[ 1., 3.], - [ 2., 4.]]) - >>> x = np.array([1.,2.,3.,4.]) - >>> x - array([ 1., 2., 3., 4.]) - >>> x.T - array([ 1., 2., 3., 4.]) + >>> a = np.array([[1, 2], [3, 4]]) + >>> a + array([[1, 2], + [3, 4]]) + >>> a.T + array([[1, 3], + [2, 4]]) + + >>> a = np.array([1, 2, 3, 4]) + >>> a + array([1, 2, 3, 4]) + >>> a.T + array([1, 2, 3, 4]) See Also -------- @@ -4515,15 +4516,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose', Returns a view of the array with axes transposed. - For a 1-D array this has no effect, as a transposed vector is simply the - same vector. To convert a 1-D array into a 2D column vector, an additional - dimension must be added. `np.atleast2d(a).T` achieves this, as does - `a[:, np.newaxis]`. - For a 2-D array, this is a standard matrix transpose. - For an n-D array, if axes are given, their order indicates how the - axes are permuted (see Examples). If axes are not provided and - ``a.shape = (i[0], i[1], ... i[n-2], i[n-1])``, then - ``a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0])``. + Refer to `numpy.transpose` for full documentation. Parameters ---------- @@ -4531,20 +4524,20 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose', * None or no argument: reverses the order of the axes. - * tuple of ints: `i` in the `j`-th place in the tuple means `a`'s - `i`-th axis becomes `a.transpose()`'s `j`-th axis. + * tuple of ints: `i` in the `j`-th place in the tuple means that the + array's `i`-th axis becomes the transposed array's `j`-th axis. * `n` ints: same as an n-tuple of the same ints (this form is - intended simply as a "convenience" alternative to the tuple form) + intended simply as a "convenience" alternative to the tuple form). Returns ------- - out : ndarray - View of `a`, with axes suitably permuted. + p : ndarray + View of the array with its axes suitably permuted. See Also -------- - transpose : Equivalent function + transpose : Equivalent function. ndarray.T : Array property returning the array transposed. ndarray.reshape : Give a new shape to an array without changing its data. @@ -4564,6 +4557,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose', array([[1, 3], [2, 4]]) + >>> a = np.array([1, 2, 3, 4]) + >>> a + array([1, 2, 3, 4]) + >>> a.transpose() + array([1, 2, 3, 4]) + """)) diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py index 6e0da47ca..36ddaa8f0 100644 --- a/numpy/core/fromnumeric.py +++ b/numpy/core/fromnumeric.py @@ -601,59 +601,67 @@ def _transpose_dispatcher(a, axes=None): @array_function_dispatch(_transpose_dispatcher) def transpose(a, axes=None): """ - Reverse or permute the axes of an array; returns the modified array. - - For an array a with two axes, transpose(a) gives the matrix transpose. - - Refer to `numpy.ndarray.transpose` for full documentation. + Returns an array with axes transposed. + + For a 1-D array, this returns an unchanged view of the original array, as a + transposed vector is simply the same vector. + To convert a 1-D array into a 2-D column vector, an additional dimension + must be added, e.g., ``np.atleast2d(a).T`` achieves this, as does + ``a[:, np.newaxis]``. + For a 2-D array, this is the standard matrix transpose. + For an n-D array, if axes are given, their order indicates how the + axes are permuted (see Examples). If axes are not provided, then + ``transpose(a).shape == a.shape[::-1]``. Parameters ---------- a : array_like Input array. axes : tuple or list of ints, optional - If specified, it must be a tuple or list which contains a permutation of - [0,1,..,N-1] where N is the number of axes of a. The i'th axis of the - returned array will correspond to the axis numbered ``axes[i]`` of the - input. If not specified, defaults to ``range(a.ndim)[::-1]``, which - reverses the order of the axes. + If specified, it must be a tuple or list which contains a permutation + of [0,1,...,N-1] where N is the number of axes of `a`. The `i`'th axis + of the returned array will correspond to the axis numbered ``axes[i]`` + of the input. If not specified, defaults to ``range(a.ndim)[::-1]``, + which reverses the order of the axes. Returns ------- p : ndarray - `a` with its axes permuted. A view is returned whenever - possible. + `a` with its axes permuted. A view is returned whenever possible. See Also -------- - ndarray.transpose : Equivalent method - moveaxis - argsort + ndarray.transpose : Equivalent method. + moveaxis : Move axes of an array to new positions. + argsort : Return the indices that would sort an array. Notes ----- - Use `transpose(a, argsort(axes))` to invert the transposition of tensors + Use ``transpose(a, argsort(axes))`` to invert the transposition of tensors when using the `axes` keyword argument. - Transposing a 1-D array returns an unchanged view of the original array. - Examples -------- - >>> x = np.arange(4).reshape((2,2)) - >>> x - array([[0, 1], - [2, 3]]) + >>> a = np.array([[1, 2], [3, 4]]) + >>> a + array([[1, 2], + [3, 4]]) + >>> np.transpose(a) + array([[1, 3], + [2, 4]]) - >>> np.transpose(x) - array([[0, 2], - [1, 3]]) + >>> a = np.array([1, 2, 3, 4]) + >>> a + array([1, 2, 3, 4]) + >>> np.transpose(a) + array([1, 2, 3, 4]) - >>> x = np.ones((1, 2, 3)) - >>> np.transpose(x, (1, 0, 2)).shape + >>> a = np.ones((1, 2, 3)) + >>> np.transpose(a, (1, 0, 2)).shape (2, 1, 3) - >>> x = np.ones((2, 3, 4, 5)) - >>> np.transpose(x).shape + >>> a = np.ones((2, 3, 4, 5)) + >>> np.transpose(a).shape (5, 4, 3, 2) """ |