About

This pull request implements a new class, SpectralCoord which aims to represent spectral coordinates (wavelengths, frequencies, energies, velocities) and also encapsulates information about observer and target. This starts from the implementation @nmearl wrote in specutils. Also implemented here is a SpectralQuantity class with default spectral equivalencies as well as a mechanism for keeping track of the doppler convention and rest value.

The motivation behind this class was:

• to provide a high-level object for use in APE 14 spectral WCSes when calling WCS.pixel_to_world - currently we returned a Quantity with no meta-data, whereas now we can let the user know what frame of reference the spectral coordinate is for, the direction of the target, and Doppler rest frequencies/wavelengths and conventions used for spectral axes in velocity (this is all information that is part of the FITS WCS standard)

• to provide a class that could be used in specutils to represent spectral axes (in practice specutils will subclass SpectralCoord into SpectralAxis to provide axis-specific functionality too)

Developers are welcome to start reviewing this PR, but note that there are a few remaining to-dos listed lower down, so this is not at the 'final draft' stage. If you have limited time, you could consider just reviewing the docs to see if you are happy with the API.

Changes to astropy.coordinates

The first set of changes here is to astropy.coordinates - we add a new class SpectralCoord which is a quantity sub-class with metadata and transformation methods. This also includes a new narrative docs page to describe it. This documentation page is not complete in the sense that some of the functionality is not described, but this provides a starting point, and what's there currently is ready for review.

Note that SpectralCoord is deliberately a Quantity sub-class rather than using a more complex infrastructure like SkyCoord with many layers of classes. Since we only care about a single coordinate here, this was found to be the simplest API, and also provides backward-compatibility with the current use of the APE 14 FITS WCS (which previously returned Quantity). We do use coordinate frames/SkyCoord to represent observers and targets though.

I have included a test that does detailed numerical checks against SLALIB - I plan to include more details about how this was done. For a reason I don't understand our galactocentric results are different, and I will be delving into that. For other frames, we typically get ~20m/s agreement for now.

Changes to astropy.units

I've added a SpectralQuantity class which implements a Quantity subclass that automatically includes spectral equivalencies, and keeps track of the doppler convention and rest value.

Changes to astropy.wcs.wcsapi

The second set of changes is to the APE 14 FITS WCS implementation - here we now return SpectralCoord for pixel_to_world - note that we stilll accept Quantity as input for world_to_pixel but in this case we give a warning that there is no observer defined, so no velocity transformation will be carried out.

One big caveat is that for now, the target on the SpectralCoord is set to the reference celestial coordinate in the case of spectral cubes. For cubes with large fields of view, this won't be quite right away from the reference coordinate. But this is already better than the current situation of returning Quantity. So I am planning to add a caveat about this to the APE 14 WCS docs. Properly implementing this may be tricky because it requires interpreting the SSYSOBS keyword which many cubes lack, and in principle this means that even for an LSRK cube the spectral coordinate is actually intended to be constant across slices in the topocentric frame, which means the spectral axis is correlated with the celestial axes. I think this is a little known fact and many cubes may be produced not knowing this assumption, which I think is why the current implementation may actually reflect the way most people use cubes (and pragmatically, it's also a much easier starting point).

git history

The git history was extracted from specutils (where an initial implementation of this class was added), and I've taken care to preserve the PR merge history so that we have references to the original PRs. I can also remove these merge commits if people would prefer, but I think it's quite nice to be able to see the original chunks of work that were done. I'm happy to go with majority opinion!

Remaining to-dos

• Make sure the sign of the transformations is correct
• Include code to generate reference rv file, and provide details of where this comes from
• Include ASDF schema and tag
• Fix tests
• Add changelog entry
• Add test for ASDF serialization
• Try and make some improvements to API based on user feedback
• Write documentation for astropy.wcs changes
• Fix xfailed ASDF serialization tests
• Write what's new entry
• Clean up implementation

Things that will be done later after this PR is merged

• Add docs for SpectralQuantity we discussed below that for now we can avoid overly advertising this, and leaving it to future to decide if we want to.
• Add higher accuracy tests (currently limited by the starlink output precision) Add high accuracy reference tests for SpectralCoord #10248