[Numpy-discussion] numpy.stack -- which function, if any, deserves the name?

[Stephan Hoyer]

In the past months there have been two proposals for new numpy functions
using the name "stack":

1. np.stack for stacking like np.asarray(np.bmat(...))
http://thread.gmane.org/gmane.comp.python.numeric.general/58748/
https://github.com/numpy/numpy/pull/5057

2. np.stack for stacking along an arbitrary new axis (this was my proposal)
http://thread.gmane.org/gmane.comp.python.numeric.general/59850/
https://github.com/numpy/numpy/pull/5605

Both functions generalize the notion of stacking arrays from the existing
hstack, vstack and dstack, but in two very different ways. Both could be
useful -- but we can only call one "stack". Which one deserves that name?

The existing *stack functions use the word "stack" to refer to combining
arrays in two similarly different ways:
a. For ND -> ND stacking along an existing dimensions (like
numpy.concatenate and proposal 1)
b. For ND -> (N+1)D stacking along new dimensions (like proposal 2).

I think it would be much cleaner API design if we had different words to
denote these two different operations. Concatenate for "combine along an
existing dimension" already exists, so my thought (when I wrote proposal
2), was that the verb "stack" could be reserved (going forward) for
"combine along a new dimension." This also has the advantage of suggesting
that "concatenate" and "stack" are the two fundamental operations for
combining N-dimensional arrays. The documentation on this is currently
quite confusing, mostly because no function like that in proposal 2
currently exists.

Of course, the *stack functions have existed for quite some time, and in
many cases vstack and hstack are indeed used for concatenate like
functionality (e.g., whenever they are used for 2D arrays/matrices). So the
case is not entirely clear-cut. (We'll never be able to remove this
functionality from NumPy.)

In any case, I would appreciate your thoughts.

Best,
Stephan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20150315/5a72a8bb/attachment.html>