Add option to create HipsSurveyProperties from survey name

docs/getting_started.rst

@@ -26,21 +26,16 @@ To draw a sky image from HiPS image tiles with the `hips` package, follow the fo
          coordsys='galactic', projection='AIT',
     )
 
-
-2. Specify the HiPS survey you want by creating a `~hips.HipsSurveyProperties` object.
+2. Specify the HiPS survey you want.
 
    A good address that lists available HiPS data is http://aladin.u-strasbg.fr/hips/list ::
 
-    from hips import HipsSurveyProperties
-    url = 'http://alasky.unistra.fr/DSS/DSS2Merged/properties'
-    hips_survey = HipsSurveyProperties.fetch(url)
-
+    hips_survey = 'CDS/P/DSS2/red'
 
 3. Call the `~hips.make_sky_image` function to fetch the HiPS data
    and draw it, returning an object of `~hips.HipsDrawResult`::
 
     from hips import make_sky_image
-
     result = make_sky_image(geometry, hips_survey, 'fits')
 
 Of course, you could change the parameters to chose any sky image geometry and

hips/draw/simple.py

@@ -4,7 +4,7 @@
 import numpy as np
 from PIL import Image
 from astropy.io import fits
-from typing import List, Tuple
+from typing import List, Tuple, Union
 from astropy.wcs.utils import proj_plane_pixel_scales
 from skimage.transform import ProjectiveTransform, warp
 from ..tiles import HipsSurveyProperties, HipsTile, HipsTileMeta
@@ -35,7 +35,7 @@ class HipsPainter:
     ----------
     geometry : `~hips.utils.WCSGeometry`
         An object of WCSGeometry
-    hips_survey : str or `~hips.HipsSurveyProperties`
+    hips_survey : `str` or `~hips.HipsSurveyProperties`
         HiPS survey properties
     tile_format : {'fits', 'jpg', 'png'}
         Format of HiPS tile
@@ -61,7 +61,7 @@ class HipsPainter:
     (1000, 2000)
     """
 
-    def __init__(self, geometry: WCSGeometry, hips_survey: HipsSurveyProperties, tile_format: str) -> None:
+    def __init__(self, geometry: WCSGeometry, hips_survey: Union[str, HipsSurveyProperties], tile_format: str) -> None:
         self.geometry = geometry
         self.hips_survey = HipsSurveyProperties.make(hips_survey)
         self.tile_format = tile_format
@@ -382,7 +382,7 @@ def plot_mpl_single_tile(geometry: WCSGeometry, tile: HipsTile, image: np.ndarra
     ax.imshow(image, origin='lower')
 
 
-def make_sky_image(geometry: WCSGeometry, hips_survey: HipsSurveyProperties, tile_format: str) -> 'HipsDrawResult':
+def make_sky_image(geometry: WCSGeometry, hips_survey: Union[str, HipsSurveyProperties], tile_format: str) -> 'HipsDrawResult':
     """Make sky image: fetch tiles and draw.
 
     The example for this can be found on the :ref:`gs` page.
@@ -391,16 +391,16 @@ def make_sky_image(geometry: WCSGeometry, hips_survey: HipsSurveyProperties, til
     ----------
     geometry : `~hips.utils.WCSGeometry`
         Geometry of the output image
-    hips_survey : str or `~hips.HipsSurveyProperties`
+    hips_survey : `str` or `~hips.HipsSurveyProperties`
         HiPS survey properties
     tile_format : {'fits', 'jpg', 'png'}
         Format of HiPS tile to use
         (some surveys are available in several formats, so this extra argument is needed)
 
     Returns
     -------
-    image : `~numpy.ndarray`
-        Output image pixels
+    result : `~hips.HipsDrawResult`
+        HipsDrawResult object
     """
     painter = HipsPainter(geometry, hips_survey, tile_format)
     painter.run()

hips/tiles/surveys.py

@@ -3,7 +3,7 @@
 from io import StringIO
 from csv import DictWriter
 import urllib.request
-from typing import List
+from typing import List, Union
 from astropy.table import Table
 from .tile import HipsTileMeta
 
@@ -44,15 +44,10 @@ class HipsSurveyProperties:
     def __init__(self, data: OrderedDict) -> None:
         self.data = data
 
-    # TODO for Adeel: implement this (add docstring & test)
     @classmethod
-    def from_name(cls, name):
-        """
-        """
+    def from_name(cls, name: str) -> 'HipsSurveyProperties':
+        """Create object from Survey ID (`HipsSurveyProperties`)."""
         # TODO: implement some kind of caching for HipsSurveyPropertiesList
-        # Also update the getting started example to use this simple solution.
-        # Discuss with Thomas how to do it.
-        # See https://github.com/hipspy/hips/issues/81
         surveys = HipsSurveyPropertiesList.fetch()
         for survey in surveys.data:
             if survey.data['ID'].strip() == name.strip():
@@ -61,16 +56,14 @@ def from_name(cls, name):
         raise KeyError(f'Survey not found: {name}')
 
     @classmethod
-    def make(cls, hips_survey):
-        """Convenience constructor from string or existing object."""
-        return hips_survey
-        # TODO for Adeel: Implement the `HipsSurveyProperties.from_name` and add a test for this lookup by name
-        # if isinstance(hips_survey, str):
-        #     hips_survey = HipsSurveyProperties.from_name(hips_survey)
-        # elif isinstance(hips_survey, HipsSurveyProperties):
-        #     pass
-        # else:
-        #     raise TypeError(f'hips_survey must be str or HipsSurveyProperties. You gave {type(hips_survey)}')
+    def make(cls, hips_survey: Union[str, HipsSurveyProperties]) -> 'HipsSurveyProperties':
+        """Convenience constructor for from_string classmethod or existing object (`HipsSurveyProperties`)."""
+        if isinstance(hips_survey, str):
+            return HipsSurveyProperties.from_name(hips_survey)
+        elif isinstance(hips_survey, HipsSurveyProperties):
+            return hips_survey
+        else:
+            raise TypeError(f'hips_survey must be of type `str` or `HipsSurveyProperties`. You gave {type(hips_survey)}')
 
     @classmethod
     def read(cls, filename: str) -> 'HipsSurveyProperties':

hips/tiles/tests/test_surveys.py

@@ -11,33 +11,44 @@ class TestHipsSurveyProperties:
     @classmethod
     def setup_class(cls):
         filename = get_pkg_data_filename('data/properties.txt')
-        cls.hips_survey = HipsSurveyProperties.read(filename)
+        cls.survey = HipsSurveyProperties.read(filename)
+
+    @remote_data
+    def test_from_name(self):
+        survey = HipsSurveyProperties.from_name('CDS/P/2MASS/color')
+        assert survey.title == '2MASS color J (1.23 microns), H (1.66 microns), K (2.16 microns)'
+
+    @remote_data
+    def test_make(self):
+        survey = HipsSurveyProperties.make('CDS/P/EGRET/Dif/300-500')
+        assert survey.title == 'EGRET Dif 300-500'
+        self.survey = HipsSurveyProperties.make(self.survey)
 
     def test_title(self):
-        assert self.hips_survey.title == 'DSS colored'
+        assert self.survey.title == 'DSS colored'
 
     def test_hips_version(self):
-        assert self.hips_survey.hips_version == '1.31'
+        assert self.survey.hips_version == '1.31'
 
     def test_hips_frame(self):
-        assert self.hips_survey.hips_frame == 'equatorial'
+        assert self.survey.hips_frame == 'equatorial'
 
     def test_astropy_frame(self):
-        assert self.hips_survey.astropy_frame == 'icrs'
+        assert self.survey.astropy_frame == 'icrs'
 
     def test_hips_order(self):
-        assert self.hips_survey.hips_order == 9
+        assert self.survey.hips_order == 9
 
     def test_tile_format(self):
-        assert self.hips_survey.tile_format == 'jpeg'
+        assert self.survey.tile_format == 'jpeg'
 
     def test_base_url(self):
         expected = 'http://alasky.u-strasbg.fr/DSS/DSSColor'
-        assert self.hips_survey.base_url == expected
+        assert self.survey.base_url == expected
 
     def test_tile_default_url(self):
         tile_meta = HipsTileMeta(order=9, ipix=54321, file_format='fits')
-        url = self.hips_survey.tile_url(tile_meta)
+        url = self.survey.tile_url(tile_meta)
         assert url == 'http://alasky.u-strasbg.fr/DSS/DSSColor/Norder9/Dir50000/Npix54321.fits'
 
     @staticmethod
@@ -85,8 +96,6 @@ def test_fetch(self):
         surveys = HipsSurveyPropertiesList.fetch()
         assert len(surveys.data) > 3
 
-        # TODO: look up survey by name here
-        # Otherwise this will break when the list changes
-        survey = surveys.data[0]
+        survey = HipsSurveyProperties.from_name('CDS/P/2MASS/H')
         assert survey.title == '2MASS H (1.66 microns)'
         assert survey.hips_order == 9