DOC: Unify cross-references between array joining methods #16197
Conversation
numpy/core/shape_base.py
Outdated
| vstack : Stack arrays in sequence vertically (row wise). | ||
| hstack : Stack arrays in sequence horizontally (column wise). | ||
| dstack : Stack arrays in sequence depth wise (along third axis). | ||
| column_stack : Stack 1-D arrays as columns into a 2-D array. |
There was a problem hiding this comment.
I think omitting these four might have been deliberate, as stack is a more predictable replacement for all of these.
There was a problem hiding this comment.
I'm not following. Do you mean one should always use stack instead of these? If so, that should be noted explicitly in the above functions. If not, I don't see why one should not link to these other and more specialized functions.
There was a problem hiding this comment.
Here's the reference I was looking for: #7183 (comment):
I actually intentionally omitted
vstackandhstackfrom the docstring forstack, because these routines are less general and powerful thanstackandconcatenate. The way thatvstack/hstack/dstackhandle arrays of different dimensionality is quirky and difficult to predict for most people without experimentation. In contrast,stackandconcatenateare a better fit for NumPy as a library for manipulating N-dimensional arrays. -- @shoyer
There was a problem hiding this comment.
#7253 added links in the other direction recommending stack be used instead.
There was a problem hiding this comment.
I've removed the links again as I don't want to go down a long API discussion. This is just intended as a small doc fix.
Note however, that the wording was alleviated in #10057, but the wording is IMHO too vague. With my user hat on, I still don't know what the recommended way of working is. Can / should or shouldn't I use vstack? It would be ok to keep it in the API but recommend to use stack in which case we shouldn't link from stack to vstack. Note also that concatenate and block still link to the *stack variants. That should be removed as well if the intention is to reduce visibility of *stack.
| vstack | ||
| hstack | ||
| dstack | ||
| column_stack | ||
| block |
There was a problem hiding this comment.
I'd be tempted to put block immediately below stack.
| ma.vstack | ||
| ma.hstack |
There was a problem hiding this comment.
Nit: below you put h before v
|
LGTM as well, thanks @timhoffm and Eric. |
Essentially, always reference the following functions:
but omitting the documented function itself (of course), and appending the corresponding inverse split operation instead.
In particular: