Merge pull request #3559 from esdc-esac-esa-int/ESA_euclid-update-get_cutout-method

EUCLIDSWRQ-285 Update get_cutout API and related tests

Author: bsipocz

CHANGES.rst

@@ -29,6 +29,8 @@ esa.euclid
 - The method ``get_spectrum`` accepts the new parameter ``linking_parameter`` to retrieve the spectra by source_id and
   sourcepatch_id. [#3543]
 -  The ``source_id`` kwarg in the ``get_spectrum`` method has been renamed to ``ids``. [#3543]
+- Method ``get_cutout`` has deprecated the 'instrument' and 'id' parameters, providing them has no effect any more. 
+  The method now only supports retrieval of MER (background‑subtracted) image cutouts. [#3559]
 - The ``get_product_list`` method now also returns file_name_list column when the product type belongs to 
   BASIC_DOWNLOAD_DATA_PRODUCTS. [#3562]
 

astroquery/esa/euclid/core.py

@@ -1399,20 +1399,20 @@ def get_product(self, *, file_name=None, product_id=None, schema='sedm', output_
 
         return files
 
-    def get_cutout(self, *, file_path=None, instrument=None, id=None, coordinate, radius, output_file=None,
-                   verbose=False):
+    @deprecated_renamed_argument(('instrument', 'id'), (None, None), since='0.4.12')
+    def get_cutout(self, *, file_path=None, coordinate, radius, output_file=None,
+                   verbose=False, instrument=None, id=None):
         """
-        Downloads a cutout given its file path, instrument and obs_id, and the cutout region
+        Downloads a cutout from a MER mosaic (background-subtracted image) for a given
+        fits file path, centered on a coordinate and with a specified radius.
+
+        This method supports **only MER mosaic cutouts**.
 
         Parameters
         ----------
         file_path : str, mandatory, default None
-            file path for the product on the server
-        instrument : str, mandatory, default None
-            instrument for the product, can be 'VIS' or 'NISP'
-        id : str, mandatory, default None
-            the observation id or tile index for MER products
-        coordinate : astropy.coordinate, mandatory
+            file path for the product on the server (MER mosaic)
+        coordinate : astropy.coordinate or Simbad/VizieR/NED name (str), mandatory
             coordinates center point
         radius : astropy.units, mandatory
             the radius of the cutout to generate
@@ -1426,7 +1426,7 @@ def get_cutout(self, *, file_path=None, instrument=None, id=None, coordinate, ra
         The fits file is downloaded, and the local path where the cutout is saved is returned
         """
 
-        if file_path is None or instrument is None or id is None or coordinate is None or radius is None:
+        if file_path is None or coordinate is None or radius is None:
             raise ValueError(self.__ERROR_MSG_REQUESTED_GENERIC)
 
         # Parse POS
@@ -1438,8 +1438,7 @@ def get_cutout(self, *, file_path=None, instrument=None, id=None, coordinate, ra
         ra = ra_hours * 15.0  # Converts to degrees
         pos = """CIRCLE,{ra},{dec},{radius}""".format(**{'ra': ra, 'dec': dec, 'radius': radius_deg})
 
-        params_dict = {'TAPCLIENT': 'ASTROQUERY', 'FILEPATH': file_path, 'COLLECTION': instrument, 'OBSID': id,
-                       'POS': pos}
+        params_dict = {'TAPCLIENT': 'ASTROQUERY', 'FILEPATH': file_path, 'POS': pos}
 
         replace = os.path.basename(file_path).replace('.fits', '_cutout.fits')
         output_file_full_path, output_dir = self.__set_dirs(output_file=output_file, observation_id=replace)
@@ -1450,12 +1449,12 @@ def get_cutout(self, *, file_path=None, instrument=None, id=None, coordinate, ra
             self.__euclidcutout.load_data(params_dict=params_dict, output_file=output_file_full_path, verbose=verbose)
         except HTTPError as err:
             log.error(
-                f"Cannot retrieve the product for file_path {file_path}, obsId {id}, and collection {instrument}. "
+                f"Cannot retrieve the product for file_path {file_path}. "
                 f"HTTP error: {err}")
             return None
         except Exception as exx:
             log.error(
-                f"Cannot retrieve the product for file_path {file_path}, obsId {id}, and collection {instrument}: "
+                f"Cannot retrieve the product for file_path {file_path}: "
                 f"{str(exx)}")
             return None
 

astroquery/esa/euclid/tests/test_euclidtap.py

@@ -1120,7 +1120,7 @@ def test_get_cutout(capsys):
 
     result = tap.get_cutout(
         file_path='/data/repository/NIR/19704/EUC_NIR_W-STACK_NIR-J-19704_20190718T001858.5Z_00.00.fits',
-        instrument='NISP', id='19704', coordinate=c, radius=r, output_file=None, verbose=True)
+        coordinate=c, radius=r, output_file=None, verbose=True)
 
     assert result is not None
 
@@ -1148,29 +1148,23 @@ def test_get_cutout_exception():
 
     c = coordinates.SkyCoord("187.89d 29.54d", frame='icrs')
     r = 1 * u.arcmin
-    file_path = '/data/repository/NIR/19704/EUC_NIR_W-STACK_NIR-J-19704_20190718T001858.5Z_00.00.fits',
+    file_path = '/data/repository/NIR/19704/EUC_NIR_W-STACK_NIR-J-19704_20190718T001858.5Z_00.00.fits'
 
     tap = EuclidClass(tap_plus_conn_handler=conn_handler, datalink_handler=tap_plus, cutout_handler=cutout_handler,
                       show_server_messages=False)
 
     with pytest.raises(ValueError, match="Radius cannot be greater than 30 arcminutes"):
-        tap.get_cutout(file_path=file_path, instrument='NISP', id='19704', coordinate=c, radius=100 * u.arcmin,
+        tap.get_cutout(file_path=file_path, coordinate=c, radius=100 * u.arcmin,
                        output_file=None)
 
     with pytest.raises(ValueError, match="Missing required argument"):
-        tap.get_cutout(file_path=None, instrument='NISP', id='19704', coordinate=c, radius=r, output_file=None)
+        tap.get_cutout(file_path=None, coordinate=c, radius=r, output_file=None)
 
     with pytest.raises(ValueError, match="Missing required argument"):
-        tap.get_cutout(file_path=file_path, instrument=None, id='19704', coordinate=c, radius=r, output_file=None)
+        tap.get_cutout(file_path=file_path, coordinate=None, radius=r, output_file=None)
 
     with pytest.raises(ValueError, match="Missing required argument"):
-        tap.get_cutout(file_path=file_path, instrument='NISP', id=None, coordinate=c, radius=r, output_file=None)
-
-    with pytest.raises(ValueError, match="Missing required argument"):
-        tap.get_cutout(file_path=file_path, instrument='NISP', id='19704', coordinate=None, radius=r, output_file=None)
-
-    with pytest.raises(ValueError, match="Missing required argument"):
-        tap.get_cutout(file_path=file_path, instrument='NISP', id='19704', coordinate=c, radius=None, output_file=None)
+        tap.get_cutout(file_path=file_path, coordinate=c, radius=None, output_file=None)
 
 
 @patch.object(TapPlus, 'load_data')
@@ -1193,19 +1187,19 @@ def test_get_cutout_exceptions_2(mock_load_data, caplog):
 
     mock_load_data.side_effect = HTTPError("launch_job_async HTTPError")
 
-    tap.get_cutout(file_path='hola.fits', instrument='NISP', id='19704', coordinate=SKYCOORD, radius=1 * u.arcmin,
+    tap.get_cutout(file_path='hola.fits', coordinate=SKYCOORD, radius=1 * u.arcmin,
                    output_file=None)
 
-    mssg = ("Cannot retrieve the product for file_path hola.fits, obsId 19704, and collection NISP. HTTP error: "
+    mssg = ("Cannot retrieve the product for file_path hola.fits. HTTP error: "
             "launch_job_async HTTPError")
     assert caplog.records[0].msg == mssg
 
     mock_load_data.side_effect = Exception("launch_job_async Exception")
 
-    tap.get_cutout(file_path='hola.fits', instrument='NISP', id='19704', coordinate=SKYCOORD, radius=1 * u.arcmin,
+    tap.get_cutout(file_path='hola.fits', coordinate=SKYCOORD, radius=1 * u.arcmin,
                    output_file=None)
 
-    mssg = ("Cannot retrieve the product for file_path hola.fits, obsId 19704, and collection NISP: launch_job_async "
+    mssg = ("Cannot retrieve the product for file_path hola.fits: launch_job_async "
             "Exception")
     assert caplog.records[1].msg == mssg
 

docs/esa/euclid/euclid.rst

@@ -360,12 +360,12 @@ and their sky coverage (in its "fov" field) is queried using ADQL_. Please note:
 1.7. MER Cutouts
 ^^^^^^^^^^^^^^^^
 
-It is also possible to download just small portions of the MER (background subtracted) images. The get_cutout_ allows to download image cutouts and store them locally - for reference, downloading a 1'x1'cutout takes less than one second and the downloaded fits file weights ~5.5 MB. In the example below, the results of Step 1 above are combined with the "file_path" and "file_name" values obtained from the mosaic_product TAP_ table to create the main input of the get_cutout_ method.
+It is also possible to download just small portions of the MER (background subtracted) images. The get_cutout_ allows to download image cutouts and store them locally - for reference, downloading a 1'x1'cutout takes less than one second and the downloaded fits file weights ~5.5 MB. In the example below, the results of Step 1 are used to build the file_path of the MER background-subtracted mosaic, which is the only required product input for the get_cutout method. This method now only retrieves cutouts from MER mosaics.
 
 **Notes:**
 This method...
 
-* makes use of the `Astroquery cutout service <https://astroquery.readthedocs.io/en/latest/image_cutouts/image_cutouts.html>`_ to download a cutout fits image from the Archive, and it only works for MER images. For more advanced use cases please see the Cutouts.ipynb notebook available in the Euclid Datalabs_.
+* makes use of the `Astroquery cutout service <https://astroquery.readthedocs.io/en/latest/image_cutouts/image_cutouts.html>`_ to extract a cutout from a MER (background-subtracted) mosaic. It only supports MER mosaics. For more advanced use cases please see the Cutouts.ipynb notebook available in the Euclid Datalabs_.
 
 * accepts both Astropy SkyCoord_ coordinates and Simbad/VizieR/NED valid names (as string).
 
@@ -375,7 +375,7 @@ Download the cutout...
 .. Skip testing as the example requires a lot of time to download a huge file
 
     >>> file_path  = f"{res['file_path'][0]}/{res['file_name'][0]}"
-    >>> cutout_out = Euclid.get_cutout(file_path=file_path, coordinate='NGC 6505', radius= 0.1 * u.arcmin, output_file='ngc6505_cutout_mer.fits', instrument = 'None',id='None')
+    >>> cutout_out = Euclid.get_cutout(file_path=file_path, coordinate='NGC 6505', radius= 0.1 * u.arcmin, output_file='ngc6505_cutout_mer.fits')
     >>> cutout_out = cutout_out[0]
 
 ...  and inspect its content: