Unify FITS read classmethods

We should unify the FITS read classmethods in Gammapy.

You can browse what we currently have here: https://github.com/gammapy/gammapy/search?utf8=✓&q="def+read(cls"&type=Code

This PR is triggered by https://github.com/gammapy/gammapy/pull/537#issuecomment-222380381, where for SkyMap @adonath so far has been calling astropy.io.fits.getdata (see here for other places where it’s called), while in many other places we’ve been calling astropy.io.fits.open and in addition accepted a hdu argument that was then used to select the HDU. This is also what others have been doing, e.g. Table.read in Astropy or spectral_cube.SpectralCube.read accept the hdu keyword and not the ext keyword that getdata takes. This is confusing for users if read methods behave differently for different classes in Gammapy.

I think I like this API and calling astropy.io.fits.open followed by HDU selection best

    def read(cls, filename, format=None, hdu=None, **kwargs):
        """Read from FITS file.

        Parameters
        ----------
        filename : str
            The file to read the cube from
        hdu : int or str
            For FITS files, the HDU to read in (can be the ID or name of an
            HDU).
        kwargs : dict
            Passed to :func:`~astropy.io.fits.open`.
        """

and then an implementation similar to https://github.com/radio-astro-tools/spectral-cube/blob/master/spectral_cube/io/fits.py which mostly does the handling of the hdu=None case to make it convenient if there is only one good HDU in the FITS file for this kind of object (e.g. one 2-dim image), and if there are several, uses the first and emits a warning. This could be mostly contained in one or a few helper functions in gammapy.utils.fits.

For cases where multiple HDUs aaa and bbb are needed (like SkyCube.read I guess we should add hdu_aaa and hdu_bbb keyword arguments to read?

We also have to make a decision on whether we want to accept the HDU as part of the filename in brackets and implement the gammapy.utils.fits.get_hdu helper function or remove it. I think this could be convenient for command line tools.

@OlgaVorokh @adonath @joleroi - Thoughts? (If you don’t like the basic plan of calling astropy.io.fits.open and adding an hdu option, please point out why and ideally propose an alternative.)

[adonath]

@joleroi Good point, I actually like the option to pass an ImageHDU or BintableHDU to the .read() method as well, instead of having an additional method from_hdu(). It makes a smaller and more intuitive (to me…) API. E.g. Table.read() takes HDU objects as well.

[cdeil]

I think now this is working properly both for the old SkyImage and the new Map.

Example from above with SkyImage:

>>> from gammapy.image import SkyImage
>>> filename = '$GAMMAPY_EXTRA/datasets/exclusion_masks/tevcat_exclusion.fits'
>>> image = SkyImage.read(filename)
>>> image.data.shape
(1800, 3600)
>>> image.wcs
WCS Keywords

Number of WCS axes: 2
CTYPE : 'GLON-CAR'  'GLAT-CAR'  
CRVAL : 0.0  0.0  
CRPIX : 1800.5  900.5  
PC1_1 PC1_2  : 1.0  0.0  
PC2_1 PC2_2  : 0.0  1.0  
CDELT : -0.1  0.1  
NAXIS : 3600  1800

And with Map:

>>> from gammapy.maps import Map
>>> filename = '/Users/deil/code/gammapy-extra/datasets/exclusion_masks/tevcat_exclusion.fits'
>>> m = Map.read(filename)
>>> m.data.shape
(1800, 3600)
>>> m.geom.wcs
WCS Keywords

Number of WCS axes: 2
CTYPE : 'GLON-CAR'  'GLAT-CAR'  
CRVAL : 0.0  0.0  
CRPIX : 1800.5  900.5  
PC1_1 PC1_2  : 1.0  0.0  
PC2_1 PC2_2  : 0.0  1.0  
CDELT : -0.1  0.1  
NAXIS : 3600  1800

Closing this issue now.

I’ll open a PR with improvements to FITS table I/O (that was discussed a bit above) later today.