Cutout2D: Inconsistent array convention (needs documentation)

[msgordon]

The ordered pair convention for Cutout2D is inconsistent and somewhat surprising. While the position argument is specified as (x, y), the size argument is reversed. From the documentation:

If size has two elements, they should be in (ny, nx) order.

While the (y, x) order is standard convention for most numpy/scipy functions, it is not intuitive to specify the position and size in reverse order from each other within the same function call.

[pllim]

This might be one of those "the ship has sailed" kind of things, but I'll let @mwcraig , @crawfordsm , or @MSeifert04 chime in.

[bsipocz]

Adding the label as per the comment above.

[mwcraig]

@larrybradley may have opinions here too...

[hamogu]

I agree that it's probably too late to change, but at least we should make it more obvious in the docs that this is inconsistent. (And add it to the list of things we'll break if we ever do a python2->python3 style backwards-breaking step).

[pllim]

And add it to the list of things we'll break if we ever do a python2->python3 style backwards-breaking step

@hamogu , can you please clarify? What does x, y ordering have to do with PY2-PY3 transition? Also, we already removed PY2 support in master, so everything breaks in PY2 now unless you stick to v2.x series.

[hamogu]

@pllim It has nothing to do with the py2-> py3 transition itself. All I'm saying is that this is something we might want to change if we ever do an astropy release that breaks backwards-compatibility.
There are packages in the Python ecosystem that found that they had accumulated so many inconsistencies that they just could not bear it any longer and then they made a big release that broke a lot of stuff. The prime example for the is "Python" itself - when Guido decided to launch the Python 3 series all packages that depend on Python (i.e. ALL python packages) need to adapt to that.

I don't know if we ever get to that point in astropy, maybe astropy 10.x? ;-)

[pllim]

Ah, gotcha! For now, I'll mark this as a documentation issue.

[SG004]

I am extraordinarily new at this, but I would like to make a pull request for this, if you'd let me.

[astrofrog]

As an aside, I've made a new wiki page which we could use to track non-ideal APIs we are stuck with (in case we do ever have an opportunity to break things in future): https://github.com/astropy/astropy/wiki/Future-API-considerations

[astrofrog]

@SG004 - yes feel free to open a pull request! As noted in the comments above, this is about clarifying things in the documentation not changing the behavior of Cutout2D

[larrybradley]

To play devil's advocate 😈 , what would you want to change? Input positions (not indices!), especially for a 2D array, are commonly expected to be in (x, y) order and that agrees with the API of other packages (e.g. matplotlib, photutils). Similarly, shape or size parameters are usually expressed (e.g. scipy and numpy functions) in axis (e.g. (y, x)) order. I agree that this is a potential source of confusion and it should be very well documented, but I think the API is actually consistent with other packages/functions with regard to the inputs. I can't think of any other function offhand where both position and size/shape are inputs.

[msgordon]

You're right that the position and shape orderings are not inconsistent with conventions in other libraries. However, the original reason for my post is that I can't remember any library where the orderings are mixed within the same function call. From the discussion here, it sounds like a potential solution is a very clear warning bubble or something.