EUCLIDSWRQ-250 new method for the mage Access Protocol (SIAP)

Jorge Fernandez Hernandez · Jorge Fernandez Hernandez · commit f9d15beb75f3 · 2026-01-21T21:21:58.000+01:00
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -36,6 +36,11 @@ gaia
 - New datalink DR4 retrieval type RESIDUAL_IMAGE. [#3489]
 - The method ``load_data`` parses ecsv files [#3500].
 
+esa.euclid
+^^^^^^^^^^
+
+- New method get_sia to access the Simple Image Access Protocol (SIAP) v2.0 [#3506]
+
 esa.hubble
 ^^^^^^^^^^
 
diff --git a/astroquery/esa/euclid/__init__.py b/astroquery/esa/euclid/__init__.py
@@ -25,14 +25,22 @@ class Conf(_config.ConfigNamespace):
                                             "ID is given preference. To give name preference, set the value to True:")
 
     ENVIRONMENTS = {'IDR': {'url_server': 'https://easidr.esac.esa.int/', 'main_table': 'catalogue.mer_catalogue',
-                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination'},
+                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination',
+                            'data_set_release_part1': 'environment', 'data_set_release_part2': 'activity_code',
+                            'data_set_release_part3': 'version'},
                     'OTF': {'url_server': 'https://easotf.esac.esa.int/', 'main_table': 'catalogue.mer_catalogue',
-                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination'},
+                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination',
+                            'data_set_release_part1': 'activity_code', 'data_set_release_part2': 'patch_id',
+                            'data_set_release_part3': 'version'},
                     'REG': {'url_server': 'https://easreg.esac.esa.int/',
                             'main_table': 'catalogue.mer_final_catalog_fits_file_regreproc1_r2',
-                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination'},
+                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination',
+                            'data_set_release_part1': 'environment', 'data_set_release_part2': 'activity_code',
+                            'data_set_release_part3': 'version'},
                     'PDR': {'url_server': 'https://eas.esac.esa.int/', 'main_table': 'catalogue.mer_catalogue',
-                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination'}
+                            'main_table_ra_column': 'right_ascension', 'main_table_dec_column': 'declination',
+                            'data_set_release_part1': 'environment', 'data_set_release_part2': 'activity_code',
+                            'data_set_release_part3': 'version'}
                     }
 
     OBSERVATION_STACK_PRODUCTS = ['DpdNirStackedFrame', 'DpdVisStackedFrame']
diff --git a/astroquery/esa/euclid/core.py b/astroquery/esa/euclid/core.py
@@ -11,12 +11,13 @@
 import pprint
 import tarfile
 import zipfile
+from collections.abc import Iterable
+from datetime import datetime
+
 from astropy import units
 from astropy import units as u
 from astropy.coordinates import Angle
 from astropy.units import Quantity
-from collections.abc import Iterable
-from datetime import datetime
 from requests.exceptions import HTTPError
 
 from astroquery import log
@@ -43,7 +44,7 @@ class EuclidClass(TapPlus):
     __VALID_DATALINK_RETRIEVAL_TYPES = conf.VALID_DATALINK_RETRIEVAL_TYPES
 
     def __init__(self, *, environment='PDR', tap_plus_conn_handler=None, datalink_handler=None, cutout_handler=None,
-                 verbose=False, show_server_messages=True):
+                 sia_handler=None, verbose=False, show_server_messages=True):
         """Constructor for EuclidClass.
 
         Parameters
@@ -56,6 +57,8 @@ def __init__(self, *, environment='PDR', tap_plus_conn_handler=None, datalink_ha
             HTTP(s) connection hander (creator). If no handler is provided, a new one is created.
         cutout_handler : cutout connection handler object, optional, default None
             HTTP(s) connection hander (creator). If no handler is provided, a new one is created.
+        sia_handler : siap connection handler object, optional, default None
+            HTTP(s) connection hander (creator). If no handler is provided, a new one is created.
         verbose : bool, optional, default 'True'
             flag to display information about the process
         show_server_messages : bool, optional, default 'True'
@@ -70,6 +73,9 @@ def __init__(self, *, environment='PDR', tap_plus_conn_handler=None, datalink_ha
         self.main_table = conf.ENVIRONMENTS[self.environment]['main_table']
         self.main_table_ra = conf.ENVIRONMENTS[self.environment]['main_table_ra_column']
         self.main_table_dec = conf.ENVIRONMENTS[self.environment]['main_table_dec_column']
+        self.dsr_1 = conf.ENVIRONMENTS[self.environment]['data_set_release_part1']
+        self.dsr_2 = conf.ENVIRONMENTS[self.environment]['data_set_release_part2']
+        self.dsr_3 = conf.ENVIRONMENTS[self.environment]['data_set_release_part3']
 
         url_server = conf.ENVIRONMENTS[environment]['url_server']
 
@@ -113,6 +119,20 @@ def __init__(self, *, environment='PDR', tap_plus_conn_handler=None, datalink_ha
         else:
             self.__euclidcutout = cutout_handler
 
+        if sia_handler is None:
+            self.__euclidsia = TapPlus(url=url_server,
+                                       server_context="sas-sia",
+                                       tap_context="tap-server",
+                                       upload_context="Upload",
+                                       table_edit_context="TableTool",
+                                       data_context="sia2/query",
+                                       datalink_context="datalink",
+                                       verbose=verbose,
+                                       client_id='ASTROQUERY',
+                                       use_names_over_ids=conf.USE_NAMES_OVER_IDS)
+        else:
+            self.__euclidsia = sia_handler
+
         if show_server_messages:
             self.get_status_messages()
 
@@ -632,6 +652,8 @@ def login(self, *, user=None, password=None, credentials_file=None, verbose=Fals
             self.__eucliddata.login(user=tap_user, password=tap_password, verbose=verbose)
             log.info(f"Login to Euclid cutout service: {self.__euclidcutout._TapPlus__getconnhandler().get_host_url()}")
             self.__euclidcutout.login(user=tap_user, password=tap_password, verbose=verbose)
+            log.info(f"Login to Euclid sia service: {self.__euclidsia._TapPlus__getconnhandler().get_host_url()}")
+            self.__euclidsia.login(user=tap_user, password=tap_password, verbose=verbose)
         except HTTPError as err:
             log.error('Error logging in data or cutout services: %s' % (str(err)))
             log.error("Logging out from TAP server")
@@ -676,6 +698,14 @@ def login_gui(self, verbose=False):
             log.error("Logging out from TAP server")
             TapPlus.logout(self, verbose=verbose)
 
+        try:
+            log.info(f"Login to Euclid sia server: {self.__euclidsia._TapPlus__getconnhandler().get_host_url()}")
+            self.__euclidsia.login(user=tap_user, password=tap_password, verbose=verbose)
+        except HTTPError as err:
+            log.error('Error logging in sia server: %s' % (str(err)))
+            log.error("Logging out from TAP server")
+            TapPlus.logout(self, verbose=verbose)
+
     def logout(self, verbose=False):
         """
         Performs a logout
@@ -711,6 +741,12 @@ def logout(self, verbose=False):
         except HTTPError as err:
             log.error('Error logging out cutout server: %s' % (str(err)))
 
+        try:
+            self.__euclidsia.logout(verbose=verbose)
+            log.info("Euclid sia server logout OK")
+        except HTTPError as err:
+            log.error('Error logging out sia server: %s' % (str(err)))
+
     @staticmethod
     def __get_quantity_input(value, msg):
         if value is None:
@@ -1235,6 +1271,113 @@ def get_product(self, *, file_name=None, product_id=None, schema='sedm', output_
 
         return files
 
+    def get_sia(self, *, search_type='CIRCLE', ra, dec, radius, calibration=2, instrument='ALL', band=None,
+                collection='sedm', dsr_part1=None, dsr_part2=None, dsr_part3=None, output_file=None, verbose=False):
+        """
+        Description
+        -----------
+
+        Access the Euclid Observation Images by VO SIAP v2.0. This service will return public images from Calibrated
+        and Stacked NISP and VIS images, MER Mosaics from VIS and NISP and Level 1 (RAW) images for NISP and VIS
+
+        Parameters
+        ----------
+        search_type : str, mandatory, default None
+            search region: CIRCLE or BOX
+        ra : float (degrees), str or astropy.coordinate, mandatory
+            right ascension
+        dec : float (degrees), str or astropy.coordinate, mandatory
+            declination
+        radius : float (degrees), str or astropy.coordinate, mandatory
+            search radius of the cutout to generate
+        calibration: int, optional, default 2
+            calibration level according to ObsCore VO standard: 0 (raw instrumental data), 1 (instrumental data in a
+            standard format), 2 (science ready data) or 3 (enhanced data products).
+        instrument: str, mandatory, default ALL
+            instrument name: ALL, VIS or NISP
+        band: str, optional, default None
+            filter name only valid if instrument is different from ALL: VIS for instrument VIS or NIR_H, NIR_J, NIR_Y
+            or NISP for instrument NISP
+        collection : str, mandatory, default sedm
+            the name of the data collection
+        dsr_part1: str, optional, default None
+            the data set release part 1: for OTF environment, the activity code; for REG and IDR, the target environment
+        dsr_part2: str, optional, default None
+            the data set release part 2: for OTF environment, the patch id (a positive integer); for REG and IDR,
+            the activity code
+        dsr_part3: str, optional, default None
+            the data set release part 3: for OTF, REG and IDR environment, the version (a integer greater than 1)
+        output_file : string, optional, default None
+            file where the results are saved.
+        verbose : bool, optional, default 'False'
+            flag to display information about the process
+
+        Returns
+        -------
+        A table object or votable file
+        """
+
+        valid_search_types = {'CIRCLE', 'BOX'}
+        valid_calibrations = {0: 'CALIB_ZERO', 1: 'CALIB_ONE', 2: 'CALIB_TWO', 3: 'CALIB_THREE'}
+        valid_instruments = {'ALL', 'VIS', 'NISP'}
+        valid_band_vis = {'VIS'}
+        valid_band_nisp = {'NIR_H', 'NIR_J', 'NIR_Y', 'NISP'}
+
+        if search_type not in valid_search_types:
+            raise ValueError(f"Invalid search tyype {search_type}")
+
+        if calibration is not None and calibration not in valid_calibrations:
+            raise ValueError(f"Invalid calibration {calibration}")
+
+        if instrument not in valid_instruments:
+            raise ValueError(f"Invalid instrument {instrument}")
+
+        if instrument == 'ALL' and band is not None:
+            raise ValueError(f"For instrument {instrument} band must be None")
+
+        if instrument == 'VIS' and band is not None and band not in valid_band_vis:
+            raise ValueError(f"Invalid band {band} for instrument {instrument}")
+
+        if instrument == 'NISP' and band is not None and band not in valid_band_nisp:
+            raise ValueError(f"Invalid band {band} for instrument {instrument}")
+
+        ra_deg = self.coordinates_degrees(ra)
+        dec_deg = self.coordinates_degrees(dec)
+        radius_deg = self.coordinates_degrees(radius)
+
+        params_dict = dict()
+        params_dict['TAPCLIENT'] = 'ASTROQUERY'
+        params_dict[
+            'POS'] = f"{search_type},{ra_deg.to_value(u.deg)},{dec_deg.to_value(u.deg)},{radius_deg.to_value(u.deg)}"
+        params_dict['INSTRUMENT'] = instrument
+        params_dict['COLLECTION'] = collection
+
+        if calibration is not None:
+            params_dict['CALIB'] = valid_calibrations[calibration]
+
+        if instrument != 'ALL' and band is not None:
+            params_dict['BAND'] = band
+
+        if dsr_part1 is not None:
+            params_dict['DSP1'] = dsr_part1
+
+        if dsr_part2 is not None:
+            params_dict['DSP2'] = dsr_part2
+
+        if dsr_part3 is not None:
+            params_dict['DSP3'] = dsr_part3
+
+        return self.__euclidsia.load_data(params_dict=params_dict, output_file=output_file, http_method='GET',
+                                          verbose=verbose)
+
+    def coordinates_degrees(self, coord):
+
+        if not isinstance(coord, units.Quantity):
+            radius_quantity = Quantity(value=coord, unit=u.deg)
+        else:
+            radius_quantity = coord.to(u.deg)
+        return radius_quantity
+
     def get_cutout(self, *, file_path=None, instrument=None, id=None, coordinate, radius, output_file=None,
                    verbose=False):
         """
diff --git a/astroquery/esa/euclid/tests/test_euclidtap.py b/astroquery/esa/euclid/tests/test_euclidtap.py
@@ -6,22 +6,21 @@
 European Space Astronomy Centre (ESAC)
 European Space Agency (ESA)
 """
-import glob
-import os
-import shutil
-from datetime import datetime
-from pathlib import Path
-from unittest.mock import patch
-
 import astropy.units as u
+import glob
 import numpy as np
+import os
 import pytest
+import shutil
 from astropy import coordinates
 from astropy.coordinates.sky_coordinate import SkyCoord
 from astropy.table import Column, Table
 from astropy.units import Quantity
 from astropy.utils.data import get_pkg_data_filename
+from datetime import datetime
+from pathlib import Path
 from requests import HTTPError
+from unittest.mock import patch
 
 from astroquery.esa.euclid.core import EuclidClass
 from astroquery.esa.euclid.core import conf
@@ -43,6 +42,8 @@
 TABLE_FILE_NAME = get_pkg_data_filename(os.path.join("data", '1714556098855O-result.vot'), package=package)
 TABLE_DATA = Path(TABLE_FILE_NAME).read_text()
 
+TABLE_SIA_FILE_NAME = get_pkg_data_filename(os.path.join("data", 'sia_test.vot'), package=package)
+
 RADIUS = 1 * u.deg
 SKYCOORD = SkyCoord(ra=19 * u.deg, dec=20 * u.deg, frame="icrs")
 
@@ -1433,6 +1434,57 @@ def test_load_async_job(mock_querier_async):
     assert job.jobid == jobid
 
 
+def test_get_sia(monkeypatch):
+    def load_data_monkeypatched(self, params_dict, output_file, http_method, verbose):
+        return Table.read(TABLE_SIA_FILE_NAME, format='votable')
+
+    monkeypatch.setattr(TapPlus, "load_data", load_data_monkeypatched)
+    euclid = EuclidClass(show_server_messages=False)
+
+    table = euclid.get_sia(ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+    assert isinstance(table, Table)
+    assert table['file_name'][
+               0] == 'EUC_MER_BGSUB-MOSAIC-VIS_TILE101007315-D84386_20230826T000856.482420Z_00.00.fits.gz'
+
+    table = euclid.get_sia(ra=89.0, dec=-66.0, radius=1.0, dsr_part1='CALBLOCK', dsr_part2='PV-023', dsr_part3=1,
+                           verbose=True)
+    assert isinstance(table, Table)
+    assert table['file_name'][
+               0] == 'EUC_MER_BGSUB-MOSAIC-VIS_TILE101007315-D84386_20230826T000856.482420Z_00.00.fits.gz'
+
+
+def test_get_sia_exceptions(monkeypatch):
+    def load_data_monkeypatch(self, params_dict, output_file, http_method, verbose):
+        return Table()
+
+    monkeypatch.setattr(TapPlus, "load_data", load_data_monkeypatch)
+    euclid = EuclidClass(show_server_messages=False)
+
+    error_message = "Invalid search tyype XX"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(search_type='XX', ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+    error_message = "Invalid instrument XX"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(instrument='XX', ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+    error_message = "For instrument ALL band must be None"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(instrument='ALL', band='XX', ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+    error_message = "Invalid band NIR_H for instrument VIS"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(instrument='VIS', band='NIR_H', ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+    error_message = "Invalid band VIS for instrument NISP"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(instrument='NISP', band='VIS', ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+    error_message = "Invalid calibration 5"
+    with pytest.raises(ValueError, match=error_message):
+        euclid.get_sia(calibration=5, ra=89.0, dec=-66.0, radius=1.0, verbose=True)
+
+
 def remove_temp_dir():
     dirs = glob.glob('./temp_*')
     for dir_path in dirs:
diff --git a/docs/esa/euclid/euclid.rst b/docs/esa/euclid/euclid.rst
