<div dir="ltr"><div>In the past months there have been two proposals for new numpy functions using the name "stack":</div><div><br></div>1. np.stack for stacking like np.asarray(np.bmat(...))<br><a href="http://thread.gmane.org/gmane.comp.python.numeric.general/58748/">http://thread.gmane.org/gmane.comp.python.numeric.general/58748/</a><br><div><a href="https://github.com/numpy/numpy/pull/5057">https://github.com/numpy/numpy/pull/5057</a></div><div><div><br><div>2. np.stack for stacking along an arbitrary new axis (this was my proposal)</div><div><a href="http://thread.gmane.org/gmane.comp.python.numeric.general/59850/">http://thread.gmane.org/gmane.comp.python.numeric.general/59850/</a><br></div></div><div><a href="https://github.com/numpy/numpy/pull/5605">https://github.com/numpy/numpy/pull/5605</a><br></div></div><div><br></div><div>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?</div><div><br></div><div>The existing *stack functions use the word "stack" to refer to combining arrays in two similarly different ways:</div><div>a. For ND -> ND stacking along an existing dimensions (like numpy.concatenate and proposal 1)</div><div>b. For ND -> (N+1)D stacking along new dimensions (like proposal 2).</div><div><br></div><div>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.</div><div><br></div><div>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.)</div><div><br></div><div>In any case, I would appreciate your thoughts.</div><div><br></div><div>Best,</div><div>Stephan</div></div>