rollaxis() has confusing error messages and should maybe interpret negative start argument differently (Trac #1441)

[thouis]

Original ticket http://projects.scipy.org/numpy/ticket/1441 on 2010-03-31 by trac user kbasye, assigned to unknown.

The rollaxis() function in numeric.py allows negative arguments for both the axis and the start. For the axis, the usual Python interpretation of a negative value applies; the axis is chosen by counting from the back. For the start, however, -1 is not the last possible position, but the second to last. I understand that fixing this is a change in the function's behavior, but at least the existing behavior is undocumented :-).

In both cases, the error messages can be confusing if too-negative values are given because the error raised uses modified values of the arguments and suggests a legal range that's smaller than what the function can actually handle.

Since it's short and I've changed many lines, I'm just going to paste a suggested replacement here rather than a diff - hope that's OK.

def rollaxis(a, axis, start=0):
    """                                                                                                                                        
    Roll the specified axis until it lies in a given position.                                                                                 

    Parameters                                                                                                                                 
    ----------                                                                                                                                 
    a : ndarray                                                                                                                                
        Input array.                                                                                                                           
    axis : int                                                                                                                                 
        The axis to roll.  The positions of the other axes do not                                                                              
        change relative to one another.                                                                                                        
    start : int, optional                                                                                                                      
        The axis is rolled until it lies before this position.                                                                                 

    Returns                                                                                                                                    
    -------                                                                                                                                    
    res : ndarray                                                                                                                              
        Output array.                                                                                                                          

    See Also                                                                                                                                   
    --------                                                                                                                                   
    roll : Roll the elements of an array by a number of positions along a                                                                      
           given axis.                                                                                                                         

    Examples                                                                                                                                   
    --------                                                                                                                                   
    >>> a = np.ones((3,4,5,6))                                                                                                                 
    >>> rollaxis(a, 3, 1).shape                                                                                                                
    (3, 6, 4, 5)                                                                                                                               
    >>> rollaxis(a, 2).shape                                                                                                                   
    (5, 3, 4, 6)                                                                                                                               
    >>> rollaxis(a, 1, 4).shape                                                                                                                
    (3, 5, 6, 4)                                                                                                                               

    First axis becomes the last:                                                                                                               

    >>> rollaxis(a, 0, -1).shape                                                                                                               
    (4, 5, 6, 3)                                                                                                                               

    Last axis becomes the first:                                                                                                               

    >>> rollaxis(a, -1).shape                                                                                                                  
    (6, 3, 4, 5)                                                                                                                               

    """
    n = a.ndim
    orig_axis, orig_start = axis, start
    if axis < 0:
        axis += n
    if start < 0:
        start += n+1
    msg = 'rollaxis: %s (%d) must be >= %d and < %d'
    if not (0 <= axis < n):
        raise ValueError, msg % ('axis', orig_axis, -n, n)
    if not (0 <= start < n+1):
        raise ValueError, msg % ('start', orig_start, -n-1, n+1)
    if (axis < start): # removing axis below will shift the start position                                                                     
        start -= 1
    if axis == start:
        return a
    axes = range(0,n)
    axes.remove(axis)
    axes.insert(start, axis)
    return a.transpose(axes)

[thouis]

@rgommers wrote on 2010-09-21

The documentation in your proposed new version for "start" is actually consistent only with the current behavior. I found rollaxis confusing at first too, but when I read the docstring now it makes sense.

Either way, since you're proposing to modify existing behavior, the correct place to discuss this on the mailing list. Since it will break a lot of existing code I don't think there's a lot of chance this gets accepted though.

Your extra examples and more accurate error message should be included I think even if the proposed change is rejected.

[thouis]

Milestone changed to Unscheduled by @rgommers on 2010-09-21

[thouis]

trac user kbasye wrote on 2010-09-21

Replying to [comment:1 rgommers]:

The documentation in your proposed new version for "start" is actually consistent only with the current behavior. I found rollaxis confusing at first too, but when I read the docstring now it makes sense.

I assume you are referring to the sentence describing the semantics of the 'start' argument: "The axis is rolled until it lies before this position."

I actually don't think this is worded very well; I'd prefer 'at' rather than 'before'. Assuming that the positions of the shape are numbered starting with 0 (which is how the 'axis' argument works), then, as the first example shows, using a 'start' value of 1 rolls the specified axis until it lies at position 1. To me, 'before' position 1 would have to mean 'at' position 0, which isn't what happens. And with that change, the interpretation of '-1' for 'start' should mean the last position, which is how my change would work.

I suppose one reading that would make the current version correct is "The axis is rolled until it lies before <> this position" - in which case you're correct that it doesn't accurately describe the new behavior I propose. But then I don't think there is any good way to describe moving something to the last position (as in the third example), since there's no current axis at position 4 to be 'before' (as it were), which seems like another reason to prefer the 'at' version.

Either way, since you're proposing to modify existing behavior, the correct place to discuss this on the mailing list. Since it will break a lot of existing code I don't think there's a lot of chance this gets accepted though.

Yeah, I know. I'm somewhat tempted to see if folks would go for the addition of moveaxis() which would work this way. Calling this function 'rollaxis' seems sort of odd, given that only one axis moves - compare the roll() function, which really does roll in the usual register sense. BTW, all this came up because it seemed like there really should be a better way to get the first (or any other axis) into the last position than doing np.rollaxis(a, axis, len(a.shape)) but right now I don't think there is. I'll float it on the list and see what happens.

Your extra examples and more accurate error message should be included I think even if the proposed change is rejected.

I'd settle for that.

And thanks for replying!

[BenFrantzDale]

I'd love moveaxis(A, from, to). Rollaxis is perplexing for me as it doesn't seem to allow me to "roll" axes forward.

I think this does it:

def moveaxisto(A, src, dst):
    """Move an axis to a specific position in the shape.."""
    # normalize negative inds:
    src %= ndim(A)
    dst %= ndim(A)
    inds = range(ndim(A))
    del inds[srd]
    if dst > src:
        dst -= 1
    inds = inds[:dst] + [src] + inds[dst:]
    return transpose(A, inds)

[juliantaylor]

is np.swapaxes what you are looking for?

[BenFrantzDale]

Swapaxes isn't what I'm looking for: I want to take one axis and put it somewhere else. I often work with multidimensional arrays of 3D points (a stack of grids of points) and sometimes it makes sense for the 3 dimension to be first as in x, y, z = foo and sometimes it makes sense for it to be last as in passing a planar RGB image to imshow.

It seems like rollaxis sort of does this but not quite: it only seems to work in one direction. And swapaxes winds up transposing other axes as well so a planar 1024x768 image becomes an interleaved 768x1024 image.

[charris]

@BenFrantzDale PRs are welcome.

[shoyer]

For anyone still following this issue, I have a pull request implementing moveaxis up for review in #6630.