np.transpose documentation #15020
Description
The documentation for np.transpose is extremely unclear.
numpy/numpy/core/fromnumeric.py
Line 613 in d9b1e32
Permute the dimensions of an array.
Parameters
----------
a : array_like
Input array.
axes : list of ints, optional
By default, reverse the dimensions, otherwise permute the axes
according to the values given.
Firstly, the use of the two terms "dimensions" and "axes" to mean apparently the same thing is confusing.
The sentence "By default, reverse the dimensions, otherwise permute the axes according to the values given" is the documentation for "axes" yet it read as if it were the documentation for the whole function. And it is nonspecific about which order it's done in, e.g. will axis numbered i of the input become the axis numbered axes[i] of the output, or vice versa?
The following would be clearer and more explicit.
(I am just showing the first part.. the later part is OK.)
Reverse or permute the axes of an array; returns the modified array.
For an array a with two axes, transpose(a) is equivalent to the
matrix transpose of a.
Parameters
----------
a : array_like
Input array.
axes : array_like (e.g. tuple or list), optional
If not specified, this function reverses the order of the axes.
If specified, it must be an array_like object 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 matrix will correspond to the axis
numbered axes[i] of the input.