astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- Gaia TAP+ (`astroquery.gaia`) »
- GaiaClass

# GaiaClass

class astroquery.gaia.GaiaClass(*, tap_plus_conn_handler=None, datalink_handler=None, gaia_tap_server='https://gea.esac.esa.int/', gaia_data_server='https://gea.esac.esa.int/', tap_server_context='tap-server', data_server_context='data-server', verbose=False, show_server_messages=True)

  Bases: `TapPlus`

  Proxy class to default TapPlus object (pointing to Gaia Archive)

  Constructor

  Parameters:
    url str, mandatory if no host is specified, default None

      TAP URL

    host str, optional, default None

      host name

    server_context str, optional, default None

      server context

    tap_context str, optional, default None

      tap context

    upload_context str, optional, default None

      upload context

    table_edit_context str, optional, default None

      context for all actions to be performed over a existing table

    data_context str, optional, default None

      data context

    datalink_context str, optional, default None

      datalink context

    port int, optional, default ‘80’

      HTTP port

    sslport int, optional, default ‘443’

      HTTPS port

    default_protocol_is_https bool, optional, default False

      Specifies whether the default protocol to be used is HTTPS

    connhandler connection handler object, optional, default None

      HTTP(s) connection hander (creator). If no handler is provided, a new one is created.

    use_names_over_ids When `True` use the `name` attributes of columns as the

      names of columns in the `astropy.table.Table` instance. Since names are not guaranteed to be unique, this may cause some columns to be renamed by appending numbers to the end. Otherwise (default), use the ID attributes as the column names.

    verbose bool, optional, default ‘True’

      flag to display information about the process

  Attributes Summary

  `GAIA_MESSAGES` |
  `MAIN_GAIA_TABLE` |
  `MAIN_GAIA_TABLE_DEC` |
  `MAIN_GAIA_TABLE_RA` |
  `ROW_LIMIT` |
  `USE_NAMES_OVER_IDS` | When `True` use the `name` attributes of columns as the names of columns in the `astropy.table.Table` instance.
  `VALID_DATALINK_RETRIEVAL_TYPES` |
  `VALID_LINKING_PARAMETERS` |

  Methods Summary

  `cone_search`(coordinate, *[, radius, ...]) | Cone search sorted by distance (sync.) TAP & TAP+
  `cone_search_async`(coordinate, *[, radius, ...]) | Cone search sorted by distance (async) TAP & TAP+
  `correct_table_units`(table) | Correct format in the units of the columns TAP & TAP+
  `cross_match`(*, full_qualified_table_name_a, ...) | Performs a positional cross-match between the specified tables.
  `cross_match_basic`(*, ...[, ...]) | Performs a positional cross-match between the specified tables.
  `get_datalinks`(ids, *[, linking_parameter, ...]) | Gets datalinks associated to the provided identifiers TAP+ only
  `get_status_messages`() | Retrieve the messages to inform users about the status of Gaia TAP
  `launch_job`(query, *[, name, output_file, ...]) | Launches a synchronous job
  `launch_job_async`(query, *[, name, ...]) | Launches an asynchronous job
  `load_data`(ids, *[, data_release, ...]) | Loads the specified table TAP+ only
  `load_user`(user_id, *[, verbose]) | Loads the specified user TAP+ only
  `login`(*[, user, password, credentials_file, ...]) | Performs a login.
  `login_gui`(*[, verbose]) | Performs a login using a GUI dialog
  `logout`(*[, verbose]) | Performs a logout
  `query_object`(coordinate, *[, radius, width, ...]) | Launches a synchronous cone search for the input search radius or the box on the sky, sorted by angular separation TAP & TAP+
  `query_object_async`(coordinate, *[, radius, ...]) | Launches an asynchronous cone search for the input search radius or the box on the sky, sorted by angular separation TAP & TAP+

  Attributes Documentation

  GAIA_MESSAGES = 'notification?action=GetNotifications'
  MAIN_GAIA_TABLE = None
  MAIN_GAIA_TABLE_DEC = 'dec'
  MAIN_GAIA_TABLE_RA = 'ra'
  ROW_LIMIT = 50
  USE_NAMES_OVER_IDS = True

    When `True` use the `name` attributes of columns as the names of columns in the `astropy.table.Table` instance. Since names are not guaranteed to be unique, this may cause some columns to be renamed by appending numbers to the end. Otherwise, use the ID attributes as the column names.

  VALID_DATALINK_RETRIEVAL_TYPES = ['EPOCH_PHOTOMETRY', 'XP_CONTINUOUS', 'XP_SAMPLED', 'RVS', 'MEAN_SPECTRUM_RVS', 'MCMC_GSPPHOT', 'MCMC_GSP_PHOT', 'MCMC_MSC', 'EPOCH_ASTROMETRY', 'EPOCH_SPECTRUM_RVS', 'EPOCH_ASTROMETRY_CROWDED_FIELD', 'EPOCH_PHOTOMETRY_CROWDED_FIELD', 'EPOCH_IMAGE', 'EPOCH_PHOTOMETRY_CCD', 'EPOCH_SPECTRUM_XP_SSO', 'EPOCH_SPECTRUM_XP_CROWDING', 'MEAN_SPECTRUM_XP', 'EPOCH_SPECTRUM_XP', 'CROWDED_FIELD_IMAGE', 'EPOCH_ASTROMETRY_BRIGHT', 'MEAN_SPECTRUM_XP_GRAVLENS', 'EPOCH_FLAGS_NSS', 'EPOCH_PARAMETERS_RVS_SINGLE', 'EPOCH_PARAMETERS_RVS_DOUBLE', 'EPOCH_FLAGS_VARI']
  VALID_LINKING_PARAMETERS = {'IMAGE_ID', 'SOURCE_ID', 'TRANSIT_ID'}

  Methods Documentation

  cone_search(coordinate, *, radius=None, table_name=None, ra_column_name='ra', dec_column_name='dec', output_file=None, output_format='votable_gzip', verbose=False, dump_to_file=False, columns=())

    Cone search sorted by distance (sync.) TAP & TAP+

    Parameters:
      coordinate str or astropy.coordinate, mandatory

        coordinates center point

      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. 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’,

          ‘fits’, ‘csv’, ‘ecsv’ and ‘json’, default is ‘votable’.

      verbose bool, optional, default ‘False’

        flag to display information about the process

      dump_to_file bool, optional, default ‘False’

        if True, the results are saved in a file instead of using memory

      columns: list, optional, default ()

        if empty, all columns will be selected

    Returns:
      A Job object
  cone_search_async(coordinate, *, radius=None, table_name=None, ra_column_name='ra', dec_column_name='dec', background=False, output_file=None, output_format='votable_gzip', verbose=False, dump_to_file=False, columns=())

    Cone search sorted by distance (async) TAP & TAP+

    Parameters:
      coordinate str or astropy.coordinate, mandatory

        coordinates center point

      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

      background bool, optional, default ‘False’

        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. 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’,

          ‘fits’, ‘csv’, ‘ecsv’ and ‘json’, default is ‘votable’.

      verbose bool, optional, default ‘False’

        flag to display information about the process

      dump_to_file bool, optional, default ‘False’

        if True, the results are saved in a file instead of using memory

      columns: list, optional, default ()

        if empty, all columns will be selected

    Returns:
      A Job object
  static correct_table_units(table)

    Correct format in the units of the columns TAP & TAP+

    Parameters:
      table `Table`, mandatory

        change the format of the units in the columns of the input table: ‘.’ by ‘ ‘ and “’” by “”

  cross_match(*, full_qualified_table_name_a, full_qualified_table_name_b, results_table_name, radius=1.0, background=False, verbose=False)

    Performs a positional cross-match between the specified tables.

    The result is a join table (stored in the user storage area) with the identifies of both tables and the distance. TAP+ only

    Parameters:
      full_qualified_table_name_a str, mandatory

        a full qualified table name (i.e. schema name and table name)

      full_qualified_table_name_b str, mandatory

        a full qualified table name (i.e. schema name and table name)

      results_table_name str, mandatory

        a table name without schema. The schema is set to the user one

      radius float (arc. seconds), str or astropy.coordinate, optional, default 1.0

        radius (valid range: 0.1-10.0). For an astropy.coordinate any angular unit is valid, but its value in arc sec must be contained within the valid range.

      background bool, optional, default ‘False’

        when the job is executed in asynchronous mode, this flag specifies whether the execution will wait until results are available

      verbose bool, optional, default ‘False’

        flag to display information about the process

    Returns:
      A Job object
  cross_match_basic(*, table_a_full_qualified_name, table_a_column_ra, table_a_column_dec, table_b_full_qualified_name=None, table_b_column_ra='ra', table_b_column_dec='dec', results_name=None, radius=1.0, background=False, verbose=False)

    Performs a positional cross-match between the specified tables.

    This method simples the execution of the method `cross_match` since it carries out the following steps in one step:

    > 1. updates the user table metadata to flag the positional RA/Dec columns;

    > 2. launches a positional cross-match as an asynchronous query;

    > 3. returns all the columns from both tables plus the angular distance (deg) for the cross-matched sources.

    The result is a join table with the identifies of both tables and the distance (degrees), that is returned without metadata units. If desired, units can be added using the Units package of Astropy as follows: results[‘separation’].unit = u.degree. To speed up the cross-match, pass the biggest table to the `table_b_full_qualified_name` parameter. TAP+ only

    Parameters:
      table_a_full_qualified_name str, mandatory

        a full qualified table name (i.e. schema name and table name)

      table_a_column_ra str, mandatory

        the ‘ra’ column in the table table_a_full_qualified_name

      table_a_column_dec str, mandatory

        the ‘dec’ column in the table table_a_full_qualified_name

      table_b_full_qualified_name str, optional, default MAIN_GAIA_TABLE

        a full qualified table name (i.e. schema name and table name)

      table_b_column_ra str, optional, default MAIN_GAIA_TABLE_RA

        the ‘ra’ column in the table table_b_full_qualified_name

      table_b_column_dec str, default MAIN_GAIA_TABLE_DEC

        the ‘dec’ column in the table table_b_full_qualified_name

      results_name str, optional, default None

        custom name defined by the user for the job that is going to be created

      radius float (arc. seconds), str or astropy.coordinate, optional, default 1.0

        radius (valid range: 0.1-10.0). For an astropy.coordinate any angular unit is valid, but its value in arc sec must be contained within the valid range.

      background bool, optional, default ‘False’

        when the job is executed in asynchronous mode, this flag specifies whether the execution will wait until results are available

      verbose bool, optional, default ‘False’

        flag to display information about the process

    Returns:
      A Job object
  get_datalinks(ids, *, linking_parameter='SOURCE_ID', verbose=False)

    Gets datalinks associated to the provided identifiers TAP+ only

    Parameters:
      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 different 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 different releases as a str list

  get_status_messages()

    Retrieve the messages to inform users about the status of Gaia TAP

  launch_job(query, *, name=None, output_file=None, output_format='votable_gzip', verbose=False, dump_to_file=False, upload_resource=None, upload_table_name=None)

    Launches a synchronous job

    Parameters:
      query str, mandatory

        query to be executed

      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. 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’,

          ‘fits’, ‘csv’, ‘ecsv’ and ‘json’, default is ‘votable_gzip’. Returned results for ‘votable_gzip’, ‘ecsv’ and ‘fits’ formats are compressed gzip files.

      verbose bool, optional, default ‘False’

        flag to display information about the process

      dump_to_file bool, optional, default ‘False’

        if True, the results are saved in a file instead of using memory

      upload_resource str, optional, default 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.

    Returns:
      A Job object
  launch_job_async(query, *, name=None, output_file=None, output_format='votable_gzip', verbose=False, dump_to_file=False, background=False, upload_resource=None, upload_table_name=None, autorun=True)

    Launches an asynchronous job

    Parameters:
      query str, mandatory

        query to be executed

      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. 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’,

          ‘fits’, ‘csv’ and ‘json’, default is ‘votable_gzip’. Returned results for ‘votable_gzip’ ‘ecsv’ and ‘fits’ format are compressed gzip files.

      verbose bool, optional, default ‘False’

        flag to display information about the process

      dump_to_file bool, optional, default ‘False’

        if True, the results are saved in a file instead of using memory

      background bool, optional, default ‘False’

        when the job is executed in asynchronous mode, this flag specifies whether the execution will wait until results are available

      upload_resource str, optional, default 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.

      autorun boolean, optional, default True

        if ‘True’, sets ‘phase’ parameter to ‘RUN’, so the framework can start the job.

    Returns:
      A Job object
  load_data(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', dump_to_file=False, overwrite_output_file=False, verbose=False, output_file=None)

    Loads the specified table TAP+ only

    Parameters:
      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’. By default, it takes the current default one.

      data_structure: str, optional, default ‘INDIVIDUAL’

        It can be ‘INDIVIDUAL’ or ‘RAW’: ‘INDIVIDUAL’ means products are provided in separate files for each sourceId. All files are zipped in a single bundle, even if only one source/file is considered ‘RAW’ means products are provided following a Data Model similar to that used in the MDB, meaning in particular that parameters stored as arrays will remain as such. A single file is provided for the data of all sourceIds together, but in this case there will be always be one row per sourceId.

      retrieval_type str, optional, default ‘ALL’ to retrieve all data from the list of sources

        Retrieval type identifier: For Gaia DR2, the only possible values is [‘EPOCH_PHOTOMETRY’] For Gaia DR3, the possible values are [‘EPOCH_PHOTOMETRY’, ‘RVS’, ‘XP_CONTINUOUS’, ‘XP_SAMPLED’, ‘MCMC_GSPPHOT’, ‘MCMC_MSC’] For Gaia DR4, the possible values will be [‘EPOCH_PHOTOMETRY’, ‘MEAN_SPECTRUM_RVS’, ‘MCMC_GSP_PHOT’, ‘EPOCH_ASTROMETRY’, ‘EPOCH_SPECTRUM_RVS’, ‘EPOCH_ASTROMETRY_CROWDED_FIELD’, ‘EPOCH_PHOTOMETRY_CROWDED_FIELD’, ‘EPOCH_IMAGE’, ‘EPOCH_PHOTOMETRY_CCD’, ‘EPOCH_SPECTRUM_XP_SSO’, ‘EPOCH_SPECTRUM_XP_CROWDING’, ‘MEAN_SPECTRUM_XP’, ‘EPOCH_SPECTRUM_XP’, ‘CROWDED_FIELD_IMAGE’, ‘EPOCH_ASTROMETRY_BRIGHT’, ‘MEAN_SPECTRUM_XP_GRAVLENS’, ‘EPOCH_FLAGS_NSS’, ‘EPOCH_PARAMETERS_RVS_SINGLE’, ‘EPOCH_PARAMETERS_RVS_DOUBLE’, ‘EPOCH_FLAGS_VARI’]. Note that for ‘CROWDED_FIELD_IMAGE’, only the format ‘fits’ can be used, and its image, in the principal header, will not be available in the returned dictionary. Set ‘output_file’ to retrieve all data: image + tables.

      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. In order to retrieve only valid data (data rows where flux is not null and/or the rejected_by_photometry flag is set to False) this request parameter should be included with valid_data=True.

      avoid_datatype_check: boolean, optional, default False.

        By default, this value will be set to False. If it is set to ‘true’ the Datalink items tags will not be checked.

      format str, optional, default ‘votable’

        Loading format. Other available formats are ‘csv’, ‘ecsv’,’votable_plain’, ‘json’ and ‘fits’

      dump_to_file: boolean, optional, default False.

        If it is true, a compressed directory named “datalink_output_<time_stamp>.zip” with all the DataLink files is made in the current working directory. The <time_stamp> format follows the ISO 8601 standard: “YYYYMMDD_HHMMSS.mmmmmm”.

      overwrite_output_file boolean, optional, default False

        To overwrite the output file (“datalink_output.zip”) if it already exists.

      verbose bool, optional, default ‘False’

        Flag to display information about the process

    Returns:
      A dictionary where the keys are the file names and its value is a list of astropy.table.table.Table objects
  load_user(user_id, *, verbose=False)

    Loads the specified user TAP+ only

    Parameters:
      user_id str, mandatory

        user id to load

      verbose bool, optional, default ‘False’

        flag to display information about the process

    Returns:
      A user
  login(*, user=None, password=None, credentials_file=None, verbose=False)

    Performs a login. User and password arguments can be used or a file that contains username and password (2 lines: one for username and the following one for the password). If no arguments are provided, a prompt asking for username and password will appear.

    Parameters:
      user str, default None

        login name

      password str, default None

        user password

      credentials_file str, default None

        file containing user and password in two lines

      verbose bool, optional, default ‘False’

        flag to display information about the process

  login_gui(*, verbose=False)

    Performs a login using a GUI dialog

    Parameters:
      verbose bool, optional, default ‘False’

        flag to display information about the process

  logout(*, verbose=False)

    Performs a logout

    Parameters:
      verbose bool, optional, default ‘False’

        flag to display information about the process

  query_object(coordinate, *, radius=None, width=None, height=None, verbose=False, columns=())

    Launches a synchronous cone search for the input search radius or the box on the sky, sorted by angular separation TAP & TAP+

    Parameters:
      coordinate str or astropy.coordinates, mandatory

        coordinates center point

      radius str or astropy.units if no ‘width’/’height’ are provided

        radius (deg)

      width str or astropy.units if no ‘radius’ is provided

        box width

      height str or astropy.units if no ‘radius’ is provided

        box height

      verbose bool, optional, default ‘False’

        flag to display information about the process

      columns: list, optional, default ()

        if empty, all columns will be selected

    Returns:
      The job results (astropy.table).
  query_object_async(coordinate, *, radius=None, width=None, height=None, verbose=False, columns=())

    Launches an asynchronous cone search for the input search radius or the box on the sky, sorted by angular separation TAP & TAP+

    Parameters:
      coordinate str or astropy.coordinates, mandatory

        coordinates center point

      radius str or astropy.units if no ‘width’/’height’ are provided

        radius

      width str or astropy.units if no ‘radius’ is provided

        box width

      height str or astropy.units if no ‘radius’ is provided

        box height

      verbose bool, optional, default ‘False’

        flag to display information about the process

      columns: list, optional, default ()

        if empty, all columns will be selected

    Returns:
      The job results (astropy.table).