[Numpy-discussion] A proposed change to rollaxis() behavior for negative 'start' values

[Nathaniel Smith]

On Tue, Sep 21, 2010 at 12:48 PM, Ken Basye <kbasye1 at jhu.edu> wrote:
> If that's going to break too much code, here's a pathway that might be
> acceptable:  Add a new function moveaxis() which works the way
> rollaxis() does for positive arguments but in the new way for negative
> arguments.  Eventually, rollaxis could be deprecated to keep things
> tidy.  This has the added advantage of using a name that seems to fit
> what the function does better - 'rollaxis' suggests a behavior like the
> roll() function which affects other axes, which isn't what happens.

My 2 cents: +1 on a new function, but I'd change the behavior for
positive arguments too.

Currently, the API is (AFAICT): You give the index of the axis you
want to move, and you give the index of the axis that you want the
first axis to be moved in front of. This is super confusing!

I propose that a much better API would be: You give the index of the
axis you want to move, and you give the index you *want* that axis to
have.  So we'd have the invariant:
  b = np.moveaxis(a, i, j)
  assert a.shape[i] == b.shape[j]
This is way easier to think about, at least for me. And it solves the
problem with negative indices too.

BTW, note that that the documentation for rollaxis is actually
self-contradictory at the moment:
   http://docs.scipy.org/doc/numpy/reference/generated/numpy.rollaxis.html
At the top it seems to document the behavior that I propose ("Roll the
specified axis backwards, until it lies *in a given* position."), and
then in the details it describes the actual behavior("The axis is
rolled until it lies *before* this position"). I take this as further
evidence that the current behavior is unnatural and confusing :-).

-- Nathaniel