Merge pull request #2936 from esdc-esac-esa-int/ESA_gaia_define_linking_param_get_datalinks

GAIA: Include the parameter linking_parameter in the function get_datalinks

Author: bsipocz

CHANGES.rst

@@ -45,6 +45,8 @@ gaia
 
 - For the functions cone_search, cone_search_async, launch_job and launch_job_async the data can be retrieved for the json output_format [##2927]
 
+- The method ``get_datalinks`` can be used with the new parameter linking_parameter. It completes PR #2859. [#2936]
+
 
 hsa
 ^^^

astroquery/gaia/__init__.py

@@ -37,6 +37,8 @@ class Conf(_config.ConfigNamespace):
                                       'RVS_EPOCH',
                                       'RVS_TRANSIT']
 
+    VALID_LINKING_PARAMETERS = {'SOURCE_ID', 'TRANSIT_ID', 'IMAGE_ID'}
+
 
 conf = Conf()
 

astroquery/gaia/core.py

@@ -46,6 +46,7 @@ class GaiaClass(TapPlus):
     MAIN_GAIA_TABLE_DEC = conf.MAIN_GAIA_TABLE_DEC
     ROW_LIMIT = conf.ROW_LIMIT
     VALID_DATALINK_RETRIEVAL_TYPES = conf.VALID_DATALINK_RETRIEVAL_TYPES
+    VALID_LINKING_PARAMETERS = conf.VALID_LINKING_PARAMETERS
     GAIA_MESSAGES = "notification?action=GetNotifications"
 
     def __init__(self, *, tap_plus_conn_handler=None,
@@ -174,7 +175,7 @@ def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL', retr
 
         Parameters
         ----------
-        ids : str list, mandatory
+        ids :  str, int, str list or int list, mandatory
             list of identifiers
         data_release: str, optional, default None
             data release from which data should be taken. E.g. 'Gaia DR3'
@@ -287,10 +288,10 @@ def load_data(self, ids, *, data_release=None, data_structure='INDIVIDUAL', retr
         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:
+        if linking_parameter not in self.VALID_LINKING_PARAMETERS:
             raise ValueError(
-                f"Invalid linking_parameter value '{linking_parameter}' (Valid values: {', '.join(valid_param)})")
+                f"Invalid linking_parameter value '{linking_parameter}' (Valid values: "
+                f"{', '.join(self.VALID_LINKING_PARAMETERS)})")
         else:
             if linking_parameter != 'SOURCE_ID':
                 params_dict['LINKING_PARAMETER'] = linking_parameter
@@ -388,22 +389,77 @@ def __get_data_files(output_file, path):
 
         return files
 
-    def get_datalinks(self, ids, *, verbose=False):
+    def get_datalinks(self, ids, *, linking_parameter='SOURCE_ID', verbose=False):
         """Gets datalinks associated to the provided identifiers
         TAP+ only
 
         Parameters
         ----------
-        ids : str list, mandatory
+        ids : str, int, str list or int list, mandatory
             list of identifiers
+        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
         verbose : bool, optional, default 'False'
             flag to display information about the process
 
         Returns
         -------
         A table object
+
+        Examples
+        --------
+        Id formats.
+
+        -- Gaia.get_datalinks(iids=1104405489608579584) # single id as an int
+
+        -- Gaia.get_datalinks(ids='1104405489608579584, 1809140662896080256') # multiple ids as a str
+
+        -- Gaia.get_datalinks(ids=(1104405489608579584, 1809140662896080256)) # multiple ids as an int list
+
+        -- Gaia.get_datalinks(ids=('1104405489608579584','1809140662896080256')) # multiple ids as str list
+        -- Gaia.get_datalinks(ids='4295806720-38655544960') # range of ids as a str
+
+        -- Gaia.get_datalinks(ids='4295806720-38655544960, 549755818112-1275606125952') # multiple ranges of ids as
+        a str
+
+        -- Gaia.get_datalinks(ids=('4295806720-38655544960', '549755818112-1275606125952') # multiple ranges of ids
+        as a str list
+
+        -- Gaia.get_datalinks(ids='Gaia DR3 1104405489608579584') # single designator
+        -- Gaia.get_datalinks(ids='Gaia DR3 1104405489608579584, Gaia DR3 1809140662896080256') # multiple
+        designators as a str
+
+        -- Gaia.get_datalinks(ids=('Gaia DR3 1104405489608579584','Gaia DR3 1809140662896080256')) # multiple
+        designators as a str list
+
+        -- Gaia.get_datalinks(ids='Gaia DR3 4295806720-Gaia DR3 38655544960') # range of designators as a str
+
+        -- Gaia.get_datalinks(ids='Gaia DR3 4295806720-Gaia DR3 38655544960, Gaia DR3 549755818112-Gaia DR3
+        1275606125952') # multiple ranges of designators as a str
+
+        -- Gaia.get_datalinks(ids=('Gaia DR3 4295806720-Gaia DR3 38655544960', 'Gaia DR3 549755818112-Gaia DR3
+        1275606125952')) # multiple ranges of designators as a str list
+
+        -- Gaia.get_datalinks(ids='Gaia DR3 4295806720-Gaia DR3 38655544960, Gaia DR2 549755818112-Gaia DR2
+        1275606125952') # multiple ranges of designators with difference releases as a str
+
+        -- Gaia.get_datalinks(ids=('Gaia DR3 4295806720-Gaia DR3 38655544960', 'Gaia DR2 549755818112-Gaia DR2
+        1275606125952')) # multiple ranges of designators with difference releases as a str list
         """
-        return self.__gaiadata.get_datalinks(ids=ids, verbose=verbose)
+
+        if linking_parameter not in self.VALID_LINKING_PARAMETERS:
+            raise ValueError(
+                f"Invalid linking_parameter value '{linking_parameter}' (Valid values: "
+                f"{', '.join(self.VALID_LINKING_PARAMETERS)})")
+
+        final_linking_parameter = None
+        if linking_parameter != 'SOURCE_ID':
+            final_linking_parameter = linking_parameter
+
+        return self.__gaiadata.get_datalinks(ids=ids, linking_parameter=final_linking_parameter, verbose=verbose)
 
     def __query_object(self, coordinate, *, radius=None, width=None, height=None,
                        async_job=False, verbose=False, columns=()):
@@ -412,20 +468,20 @@ def __query_object(self, coordinate, *, radius=None, width=None, height=None,
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
+        coordinate : str or astropy.coordinate, mandatory
             coordinates center point
-        radius : astropy.units if no 'width' nor 'height' are provided
+        radius : str or astropy.units if no 'width' nor 'height' are provided
             radius (deg)
-        width : astropy.units if no 'radius' is provided
+        width : str or astropy.units if no 'radius' is provided
             box width
-        height : astropy.units if no 'radius' is provided
+        height : str or astropy.units if no 'radius' is provided
             box height
         async_job : bool, optional, default 'False'
             executes the query (job) in asynchronous/synchronous mode (default
             synchronous)
         verbose : bool, optional, default 'False'
             flag to display information about the process
-        columns: list, optional, default []
+        columns: list, optional, default ()
             if empty, all columns will be selected
 
         Returns
@@ -486,18 +542,19 @@ def __query_object(self, coordinate, *, radius=None, width=None, height=None,
 
     def query_object(self, coordinate, *, radius=None, width=None, height=None,
                      verbose=False, columns=()):
-        """Launches a job
+        """Launches a synchronous cone search for the input search radius or the box on the sky, sorted by angular
+        separation
         TAP & TAP+
 
         Parameters
         ----------
-        coordinate : astropy.coordinates, mandatory
+        coordinate : str or astropy.coordinates, mandatory
             coordinates center point
-        radius : astropy.units if no 'width'/'height' are provided
+        radius : str or astropy.units if no 'width'/'height' are provided
             radius (deg)
-        width : astropy.units if no 'radius' is provided
+        width : str or astropy.units if no 'radius' is provided
             box width
-        height : astropy.units if no 'radius' is provided
+        height : str or astropy.units if no 'radius' is provided
             box height
         verbose : bool, optional, default 'False'
             flag to display information about the process
@@ -514,18 +571,19 @@ def query_object(self, coordinate, *, radius=None, width=None, height=None,
 
     def query_object_async(self, coordinate, *, radius=None, width=None,
                            height=None, verbose=False, columns=()):
-        """Launches a job (async)
+        """Launches an asynchronous cone search for the input search radius or the box on the sky, sorted by angular
+        separation
         TAP & TAP+
 
         Parameters
         ----------
-        coordinate : astropy.coordinates, mandatory
+        coordinate : str or astropy.coordinates, mandatory
             coordinates center point
-        radius : astropy.units if no 'width'/'height' are provided
+        radius : str or astropy.units if no 'width'/'height' are provided
             radius
-        width : astropy.units if no 'radius' is provided
+        width : str or astropy.units if no 'radius' is provided
             box width
-        height : astropy.units if no 'radius' is provided
+        height : str or astropy.units if no 'radius' is provided
             box height
         verbose : bool, optional, default 'False'
             flag to display information about the process
@@ -569,7 +627,7 @@ def __cone_search(self, coordinate, radius, *, table_name=None,
             when the job is executed in asynchronous mode, this flag specifies
             whether the execution will wait until results are available
         output_file : str, optional, default None
-            file name where the results are saved if dump_to_file is True.
+            file name where the results are saved if ``dump_to_file`` is True.
             If this parameter is not provided, the jobid is used instead
         output_format : str, optional, default 'votable_gzip'
             results format. Available formats are: 'votable', 'votable_plain',
@@ -647,17 +705,17 @@ def cone_search(self, coordinate, *, radius=None,
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
+        coordinate : str or astropy.coordinate, mandatory
             coordinates center point
-        radius : astropy.units, mandatory
+        radius : str or astropy.units, mandatory
             radius
         table_name : str, optional, default main gaia table name doing the cone search against
         ra_column_name : str, optional, default ra column in main gaia table
             ra column doing the cone search against
         dec_column_name : str, optional, default dec column in main gaia table
             dec column doing the cone search against
         output_file : str, optional, default None
-            file name where the results are saved if dump_to_file is True.
+            file name where the results are saved if ``dump_to_file`` is True.
             If this parameter is not provided, the jobid is used instead
         output_format : str, optional, default 'votable_gzip'
             results format. Available formats are: 'votable', 'votable_plain',
@@ -697,9 +755,9 @@ def cone_search_async(self, coordinate, *, radius=None,
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
+        coordinate : str or astropy.coordinate, mandatory
             coordinates center point
-        radius : astropy.units, mandatory
+        radius : str or astropy.units, mandatory
             radius
         table_name : str, optional, default main gaia table name doing the cone search against
         ra_column_name : str, optional, default ra column in main gaia table
@@ -711,7 +769,7 @@ def cone_search_async(self, coordinate, *, radius=None,
             specifies whether
             the execution will wait until results are available
         output_file : str, optional, default None
-            file name where the results are saved if dump_to_file is True.
+            file name where the results are saved if ``dump_to_file`` is True.
             If this parameter is not provided, the jobid is used instead
         output_format : str, optional, default 'votable_gzip'
             results format. Available formats are: 'votable', 'votable_plain',
@@ -772,6 +830,15 @@ def __getCoordInput(self, value, msg):
 
     @staticmethod
     def correct_table_units(table):
+        """Correct format in the units of the columns
+        TAP & TAP+
+
+        Parameters
+        ----------
+        table : `~astropy.table.Table`, mandatory
+            change the format of the units in the columns of the input table: '.' by ' ' and "'" by ""
+        """
+
         for cn in table.colnames:
             col = table[cn]
             if isinstance(col.unit, u.UnrecognizedUnit):
@@ -877,7 +944,7 @@ def launch_job(self, query, *, name=None, output_file=None,
         name : str, optional, default None
             custom name defined by the user for the job that is going to be created
         output_file : str, optional, default None
-            file name where the results are saved if dump_to_file is True.
+            file name where the results are saved if ``dump_to_file`` is True.
             If this parameter is not provided, the jobid is used instead
         output_format : str, optional, default 'votable_gzip'
             results format. Available formats are: 'votable_gzip', 'votable', 'votable_plain',
@@ -892,7 +959,7 @@ def launch_job(self, query, *, name=None, output_file=None,
             resource to be uploaded to UPLOAD_SCHEMA
         upload_table_name : str, optional, default None
             resource temporary table name associated to the uploaded resource.
-            This argument is required if upload_resource is provided.
+            This argument is required if ``upload_resource`` is provided.
 
         Returns
         -------
@@ -922,7 +989,7 @@ def launch_job_async(self, query, *, name=None, output_file=None,
         name : str, optional, default None
             custom name defined by the user for the job that is going to be created
         output_file : str, optional, default None
-            file name where the results are saved if dump_to_file is True.
+            file name where the results are saved if ``dump_to_file`` is True.
             If this parameter is not provided, the jobid is used instead
         output_format : str, optional, default 'votable_gzip'
             results format. Available formats are: 'votable_gzip', 'votable', 'votable_plain',
@@ -940,7 +1007,7 @@ def launch_job_async(self, query, *, name=None, output_file=None,
             resource to be uploaded to UPLOAD_SCHEMA
         upload_table_name : str, optional, default None
             resource temporary table name associated to the uploaded resource.
-            This argument is required if upload_resource is provided.
+            This argument is required if ``upload_resource`` is provided.
         autorun : boolean, optional, default True
             if 'True', sets 'phase' parameter to 'RUN',
             so the framework can start the job.