Convenience attributes for accessing world-axis-specific information #811

Describe the feature

A deliberate design decision of ndcube was to make its functionality valid for any number of axes and combination of physical types. While this has generally been a success and strength, multiple instances of user feedback have highlighted the desire for a simpler and more intuitive way of accessing coordinate values for common, well-known physical types. These include spectral, spatial/celestial, time, and stokes.

This issue provide a place where thoughts on the design of such an interface can be hashed out. Two starting suggestions include:

• Add convenience coordinate methods to NDCube #709: add properties directly to NDCube that are shortcuts for axis_world_coords
• Coords Class for NDCube #710: develop a coords class can be attached to NDCube. It would provide similar properties, in addition to other helpful coordinate-related info/functionality.
• There may be a better 3rd or 4th option out there...

Proposed solution

A coords class that can be attached to an NDCube, e.g. cube.coords, which introduces sets of APIs for specific world axis types. This can be used to incorporate various APIs, such as some provided by classes like sunpy.map.Map. Each world axis API can exist under its own class and accessed via a named attribute on the coords class. These can include:

• coords.celestial
• coords.spectral
• coords.time
• coords.stokes

These could have the following functionalities:

• coords.celestial
  • .coords/.coords_values: Returns the coordinate values of all pixels as a SkyCoord. Shortcut for NDCube.axis_world_coords / axis_world_coords_values.
  • coordinate_frame: returns a celestial coordinate frame object based on the WCS info.
  • .crop: Convenience method for NDCube.crop for cropping only along the celestial axes.
• coords.spectral
  • .coords/.coords_values: Returns the coordinate values of all pixels as a SpectralCoord. Shortcut for NDCube.axis_world_coords / axis_world_coords_values.
  • .wavelength, .energy, .frequency: Returns the coordinate values of pixels as wavelength, energy or frequency.
  • .wavelength_unit, .energy_unit, .frequency_unit: The unit in which each property is returned. Can be set by the user.
  • .crop: Convenience method for NDCube.crop for cropping only along the wavelength axis/axes.
• coords.time:
  • .coords/.coords_values: Returns the coordinate values of all pixels as a Time. Shortcut for NDCube.axis_world_coords / axis_world_coords_values.
  • .crop: Convenience method for NDCube.crop for cropping only along the time axis/axes.
• coords.stokes
  • .coords/.coords_values: Returns the coordinate values of all pixels as a StokesCoord. Shortcut for NDCube.axis_world_coords / axis_world_coords_values.
  • I, Q etc (all possible options depending on what's in the WCS) to crop the cube to that component.

More thoughts to follow...

Other related functionalities that aren't necessarily world axis specific:

• .observer_coordinate: A SkyCoord giving the location of the observer, if such information is inferrable from the WCS. (Is this already available from APE-14 wcses?)
• .light_travel_time(): Takes in a SkyCoord and returns the difference in light travel time between an origin and the input location(s), relative to that between the origin and observer location.
  • If origin not provided, its default is the observer coordinate.
  • There's a question of how to handle the case where the SkyCoords have different obstimes. Perhaps a kwarg which allows only the locations to be considered, or also the difference in times to be included.
  • Perhaps something like this already does/should exist in astropy SkyCoord.