summaryrefslogtreecommitdiff
path: root/numpy
diff options
context:
space:
mode:
authorPetar Mlinarić <petar.mlinaric@gmail.com>2022-07-19 01:23:40 -0500
committerGitHub <noreply@github.com>2022-07-19 09:23:40 +0300
commit14c92e414cb5c5ab77aa8af9eb9e6d810b28ff4d (patch)
tree627a52da4a5017e2aef751230642d0e081d1da18 /numpy
parentfe2bb380fd9a084b622ff3f00cb6f245e8c1a10e (diff)
downloadnumpy-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.py55
-rw-r--r--numpy/core/fromnumeric.py66
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)
"""