Spherical_offsets_to method - #4338

Responding to a comment from @mhvk from #4209:

The one question I have is whether the spherical_offsets should return the approximate answers, or just do the full transformation and return the longitude and latitude in the new system (which are equal to those offsets). My tendency is towards the latter, as I think our aim should be to give the right result, even if it is substantially slower than the quick calculation for small offsets (this is also what we decided about angular separation, after long discussion...).

In the current implementation, it's the "approximate" answer. I think this is good, because sometimes people actually want the dra_cos(dec) answer because that's a convention *and_ is quite a bit faster. Once #4339 is implemented, we should definitely make it clear in the spherical_offsets_to docstring (and perhaps the non-small-angle warning message) how to use that approach to get a more right answer, though.

The other similar methods are separation and position_angle, so for consistency this should be spherical_offset (singular without the _to).

If you think about finding methods by tab completion and finding methods by doing coord.<TAB>, then something like offset_spherical will have greater contrast than spherical_offset. But I don't feel that strongly about this...

@eteq - am OK with having just the simple version here. Do agree with @taldcroft on the name, and that there should be no warning.

@mhvk @taldcroft

The other similar methods are separation and position_angle, so for consistency this should be spherical_offset (singular without the _to).

My thinking here is that this is subtly different from both separation and position_angle in that the order really matters. That is, you get completely the wrong answer for from.spherical_offset(to) vs. to.spherical_offset(from). By contrast, separation has no sign and hence order doesn't matter, while for position_angle both answers are "right" and only differ by 180 degrees. So the to is there to make it harder to forget that it's from.<whatever>(to) rather than to.<whatever>(from). But if you still both think consistency is better with that in mind, I can drop the _to.

I see the point about offset_spherical vs. spherical_offset, though, and agree.

@eteq - I would say that position angle being off by 180 degrees is just as wrong as being off by the sign for the offset. Position angle has a unique definition [1] and when combined with separation can unambiguously reproduce the offset from source 1 to source 2.

[1] Not necessarily in all of astronomy, but within astropy.

@eteq - I think on balance I prefer it without the _to; I agree with @taldcroft that for the position one really is in the same boat (and we're now introducing barycentric corrections which also involve getting stuff you need to add to the original value to get to where you want to be).

As for the name, I think I'd actually prefer spherical_offset over offset_spherical, but since I don't feel the offset is particularly "spherical", my overall preference would be to just go for offset.

I'd be OK with offset as well, and agree with the point that it's actually not (locally) spherical since the numbers effectively assume a flat tangent plane. Any of the options without _to would be fine by me.

I restarted the failing Travis build and it again died hard after less than a minute with some configuration problem.

@eteq - Can you rebase, please?

This PR is independent of #4339, right?

I'm uneasy adding approximate offset methods because they fail badly near poles or for large offsets. Offsets based on great circles work well everywhere, and have a very natural interpretation based on change in longitude and latitude (e.g. RA and Dec): distance along the arc of a great circle = sqrt(dlong^2 + dlat^2), orientation of arc at starting point relative to the direction of increasing longitude = atan2(dlat, dlong). This gives the right answer for points on an image, even if the image is taken very near the pole (and if the long/lat axes align with image x/y, the deltas are simply pixels with appropriate scaling).

@cdeil - yes this is independent, but, as @r-owen points out, it may be we don't want to actually do this given - probably we want an interface that looks like this PR for convenience, but the implementation should perhaps be more accurate.

There were initially two main reasons for this function:

1. it was trivial to implement "before" Create AstrometricFrame #4339 (but that's irrelevant because Create AstrometricFrame #4339 is addressed by Implemented Astrometric frame #4524)
2. sometimes it's useful to have the "bad" approximation because it's what at least some older telescopes/finding charts/etc assume.

1 is now irrelevant, and 2 I think I've been persuaded it shouldn't be the default. The question is: should we still have an option to get the bad approximation to address use case 2? Something like coo1.spherical_offsets_to(coo2, bad_approximation=True) (@r-owen, @mhvk?)

I'd much prefer not to give the option of bad approximations, at least in the absence of a concrete reason why it is important (telescopes/finding charts arguably not being one: if they're that bad, the correct answer will almost certainly be a good enough approximation to the bad one!).

In this particular case, I also feel that the bad approximation is so simple that we can simply leave it for the user to code if s/he really needs it.

p.s. You may recall we had a long discussion about angular separation, where we considered giving the option of less accurate but faster methods, but ended up with deciding just to include the good one only.