Convenience attributes for accessing world-axis-specific information

[DanRyanIrish]

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
  • .values/.grid/.coords: Returns the coordinate values of all pixels as a SkyCoord. Shortcut for NDCube.axis_world_coords
  • coordinate_frame: returns a celestial coordinate frame object based on the WCS info.
  • .crop: Equivalent/Variant of sunpy.map.Map.submap that acts as a more user-friendly interface to NDCube.crop
• coords.spectral
  • .values/.grid/.coords: Returns the coordinate spectral values of all pixels along the spectral axis/axes Shortcut for NDCube.axis_world_coords
  • .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.
• time:
  • .values/.grid/.coords: Returns the coordinate time values of all pixels along the time axis/axes Shortcut for NDCube.axis_world_coords
  • .crop: Convenience method for NDCube.crop for cropping only along the time axis/axes.
• cube.stokes
  • .values/.grid/.coords: Returns the coordinate spectral values of all pixels along the spectral axis/axes Shortcut for NDCube.axis_world_coords
  • .crop: Convenience method for NDCube.crop for cropping only along the stokes axis/axes.

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.

[Cadair]

A related thought on this, it would be nice if you could access a view of the data and coordinate information which is "I want this world coord and a flat dimension of all the other ones". This could for example be used in spectral fitting where you might want to iterate over all the spectra, or in a time lag style computation where you want to iterate over all the timeseries.