Merge pull request astropy#2859 from esdc-esac-esa-int/ESA_gaia_GAIAPCR-1290_Include_the_new_DataLink_linking_parameter

Esa gaia gaiapcr 1290 include the new data link linking parameter

Author: bsipocz

CHANGES.rst

@@ -23,6 +23,12 @@ gaia
   for example planned or our unplanned downtimes of the archive, etc. The notification
   will be also visible when accessing the archive through Astroquery. [#2376]
 
+- Datalink can be used with the new parameter linking_parameter. It provides an additional
+  meaning to the source identifiers: source_id, transit_id and image_id.
+  This parameter is optional, in order to be backward compatible, and
+  therefore, if the parameter is not set, the source identifiers are
+  considered as source_id. [#2859]
+
 hsa
 ^^^
 

astroquery/gaia/core.py

@@ -163,10 +163,10 @@ def logout(self, *, verbose=False):
         except HTTPError:
             log.error("Error logging out data server")
 
-    def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL',
-                  retrieval_type="ALL", valid_data=False, band=None,
-                  avoid_datatype_check=False, format="votable", output_file=None,
-                  overwrite_output_file=False, verbose=False):
+    def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL', retrieval_type="ALL",
+                  linking_parameter='SOURCE_ID', valid_data=False, band=None, avoid_datatype_check=False,
+                  format="votable",
+                  output_file=None, overwrite_output_file=False, verbose=False):
         """Loads the specified table
         TAP+ only
 
@@ -194,6 +194,11 @@ def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL',
             For GAIA DR4, possible values will be ['EPOCH_PHOTOMETRY', 'RVS', 'XP_CONTINUOUS', 'XP_SAMPLED',
             'MCMC_GSPPHOT', 'MCMC_MSC', 'EPOCH_ASTROMETRY', 'RV_EPOCH_SINGLE', 'RV_EPOCH_DOUBLE', 'RVS_EPOCH' or
             'RVS_TRANSIT']
+        linking_parameter : str, optional, default SOURCE_ID, valid values: SOURCE_ID, TRANSIT_ID, IMAGE_ID
+            By default, all the identifiers are considered as source_id
+            SOURCE_ID: the identifiers are considered as source_id
+            TRANSIT_ID: the identifiers are considered as transit_id
+            IMAGE_ID: the identifiers are considered as sif_observation_id
         valid_data : bool, optional, default False
             By default, the epoch photometry service returns all available data, including
             data rows where flux is null and/or the rejected_by_photometry flag is set to True.
@@ -272,6 +277,14 @@ def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL',
         params_dict['RETRIEVAL_TYPE'] = str(retrieval_type)
         params_dict['USE_ZIP_ALWAYS'] = 'true'
 
+        valid_param = {'SOURCE_ID', 'TRANSIT_ID', 'IMAGE_ID'}
+        if linking_parameter not in valid_param:
+            raise ValueError(
+                f"Invalid linking_parameter value '{linking_parameter}' (Valid values: {', '.join(valid_param)})")
+        else:
+            if linking_parameter != 'SOURCE_ID':
+                params_dict['LINKING_PARAMETER'] = linking_parameter
+
         if path != '':
             try:
                 os.mkdir(path)

astroquery/gaia/tests/test_gaiatap.py

@@ -195,6 +195,31 @@ def load_data_monkeypatched(self, params_dict, output_file, verbose):
         output_file=tmp_path / "output_file")
 
 
+def test_load_data_linking_parameter(monkeypatch, tmp_path):
+
+    def load_data_monkeypatched(self, params_dict, output_file, verbose):
+        assert params_dict == {
+            "VALID_DATA": "true",
+            "ID": "1,2,3,4",
+            "FORMAT": "votable",
+            "RETRIEVAL_TYPE": "epoch_photometry",
+            "DATA_STRUCTURE": "INDIVIDUAL",
+            "LINKING_PARAMETER": "TRANSIT_ID",
+            "USE_ZIP_ALWAYS": "true"}
+        assert output_file == str(tmp_path / "output_file")
+        assert verbose is True
+
+    monkeypatch.setattr(TapPlus, "load_data", load_data_monkeypatched)
+
+    GAIA_QUERIER.load_data(
+        ids="1,2,3,4",
+        retrieval_type="epoch_photometry",
+        linking_parameter="TRANSIT_ID",
+        valid_data=True,
+        verbose=True,
+        output_file=tmp_path / "output_file")
+
+
 def test_get_datalinks(monkeypatch):
 
     def get_datalinks_monkeypatched(self, ids, verbose):