Change a few method names in astropy.wcs - #210

(another possibility would be to use to_world and to_pixel, but only if it doesn't cause ambiguity)

+1 This seems more understandable...
If others agree, it would be worth pointing out the @deprecated decorator in astropy.io.fits.util (which at some point needs to be moved elsewhere). This can be used to mark old functions as deprecated and direct users to what they should use instead.
Currently it only works for functions, but that's 95% of the cases where I've needed it anyways (other cases include: deprecating entire classes, in which case you can put the decorator on the class's __init__(), deprecating attributes, in which case you can convert that attribute to a property and mark it as deprecated, and finally deprecating function arguments, which just has to be done by manually issuing a DeprecationWarning).

We had a discussion way back when all this was first written. It was decided to be take this more explicit approach because the SIP and distortion image transformations are not invertible (they could be iteratively, but at present the code doesn't allow that), and it was deemed confusing that pix2sky(sky2pix(X)) != X. It also makes it clear where we break off from being FITS WCS/wcslib compatible. I think it's a very important distinction to make and maybe that could be more clear in the docs. So I'm not terribly for consolidating those methods -- if we did, I would recommend having sip, det2im and imdist all as separate keywords, and perhaps throw wcs (indicating core WCS) on there as well.

I think the naming change from sky to world makes sense.

Ok - I'll defer to you regarding keeping the methods separate or combining, as I don't feel too strongly about that. I guess I'm trying to think more about what will happen when we want to start implementing other WCS types, as we'll probably want a common API for all WCS objects. What would the lowest common denominator be for all these classes - the presence of wcs_pixel2world/wcs_world2pixel?

If we implement other WCS types, they won't be WCS any longer, right? I tend to think of WCS as the format defined in the FITS WCS documents -- there's lots of other ways to transform to/from world coordinates, but I wouldn't want to call them WCS for the sake of confusion. Maybe what we need to think of is a "Transformation" ABC that has transform_forward and transform_backward methods (or transform and inv_transform methods?).

Regarding other transformation classes, the current implementation of NDData (https://github.com/astropy/astropy/blob/master/astropy/nddata/nddata.py) has a wcs attribute that was used more in the sense of pixel to real world transformations, not just FITS WCS. I don't mind if we call it something else, e.g. transform, but I guess I'm wondering whether it wouldn't make sense for all transformation objects to at least share some common API elements?

For example, one could imagine having a tool to plot a Spectrum1D object. Would that tool need to test for the type of transformation, and call different methods depending on whether it's e.g. FITS WCS, or a table or function-based transformation? Or could we provide a common API, so that tools that such tools can remain agnostic about the type of transformation? I understand that this would be possible if the full (FITS) WCS transformation was easily reversible, but I'm wondering whether the fact it's not stops us from being able to provide a common API?

Just a quick thought - if we do want to reserve the name wcs for FITS-WCS, should we maybe consider having a more general top-level sub-package, e.g. trans or transform, and have wcs be a sub-package of that?

On the other hand, can we actually think of concrete examples of non-WCS transformations we might need? For instance, after digging around a bit, it does look like WCS supports table lookup transformations?

@astrofrog I would have a wcs package and a subpackage called fits-wcs. What do you think?

@astrofrog: I'm all for a common API to transformations -- I think we should just use the generic term "transformation" rather than "wcs". I think we agree on that, if I follow correctly.

pywcs does support table lookup transformations, but it's not part of wcslib itself and I'm not aware of any other tools that support it. (Most of Paper IV remains unimplemented anywhere, but we implemented the table lookup part of it ourselves).

@mdboom: I see where you're coming from with transformation (isn't that what it's called in matplotlib as well). I like world coordinate system as it specifically relates to coordinates and that's what we're implementing. Maybe "mapping" is a more appropriate term.

@wkerzendorf: mapping (to my mind) suggests a mapping of discrete elements rather than a continuous function. But I don't have a strong feeling about it.

I agree that mapping means more a 1-to-1 relation (which is more of a specific type of transformation).

After thinking about this some more, (FITS) WCS is such an integral part of astronomy that one possibility is just to keep it where it is for now, and implement more generic transformation wrapping at the level of NDData for example (since that is where it would be used).

In any case, wherever we do implement the more generic transformations, I agree that transformation or maybe the more concise transform or trans could be used. If we keep it separate from NDData, then we could move wcs to astropy.trans.wcs...

Maybe we can just merge this PR for now, and open a new issue to discuss more generic transformations once there is a need for them? (so that we actually have some use cases)

Agreed. Merging this and created new Issue #211.