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)[source]

Bases: TapPlus

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

Constructor

Parameters:
urlstr, mandatory if no host is specified, default None

TAP URL

hoststr, optional, default None

host name

server_contextstr, optional, default None

server context

tap_contextstr, optional, default None

tap context

upload_contextstr, optional, default None

upload context

table_edit_contextstr, optional, default None

context for all actions to be performed over a existing table

data_contextstr, optional, default None

data context

datalink_contextstr, optional, default None

datalink context

portint, optional, default ‘80’

HTTP port

sslportint, optional, default ‘443’

HTTPS port

default_protocol_is_httpsbool, optional, default False

Specifies whether the default protocol to be used is HTTPS

connhandlerconnection handler object, optional, default None

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

use_names_over_idsWhen 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.

verbosebool, 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_LINKING_PARAMETERS = {'IMAGE_ID', 'SOURCE_ID', 'TRANSIT_ID'}

Methods Documentation

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

Parameters:
coordinatestr or astropy.coordinate, mandatory

coordinates center point

radiusstr or astropy.units, mandatory

radius

table_namestr, optional, default main gaia table name doing the cone search against
ra_column_namestr, optional, default ra column in main gaia table

ra column doing the cone search against

dec_column_namestr, optional, default dec column in main gaia table

dec column doing the cone search against

output_filestr, 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_formatstr, optional, default ‘votable_gzip’
results format. Available formats are: ‘votable’, ‘votable_plain’,

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

verbosebool, optional, default ‘False’

flag to display information about the process

dump_to_filebool, 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=())[source]

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

Parameters:
coordinatestr or astropy.coordinate, mandatory

coordinates center point

radiusstr or astropy.units, mandatory

radius

table_namestr, optional, default main gaia table name doing the cone search against
ra_column_namestr, optional, default ra column in main gaia table

ra column doing the cone search against

dec_column_namestr, optional, default dec column in main gaia table

dec column doing the cone search against

backgroundbool, optional, default ‘False’

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

output_filestr, 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_formatstr, optional, default ‘votable_gzip’
results format. Available formats are: ‘votable’, ‘votable_plain’,

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

verbosebool, optional, default ‘False’

flag to display information about the process

dump_to_filebool, 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)[source]

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

Parameters:
tableTable, 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)[source]

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_astr, mandatory

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

full_qualified_table_name_bstr, mandatory

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

results_table_namestr, mandatory

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

radiusfloat (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.

backgroundbool, optional, default ‘False’

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

verbosebool, 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)[source]

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_namestr, mandatory

a full qualified table name (i.e. schema name and table name, “user_<user_name>.<table_name>” )

table_a_column_rastr, mandatory

the ‘ra’ column in the table table_a_full_qualified_name

table_a_column_decstr, mandatory

the ‘dec’ column in the table table_a_full_qualified_name

table_b_full_qualified_namestr, optional, default MAIN_GAIA_TABLE

a full qualified table name (i.e. schema name and table name, “user_<user_name>.<table_name>” )

table_b_column_rastr, optional, default MAIN_GAIA_TABLE_RA

the ‘ra’ column in the table table_b_full_qualified_name

table_b_column_decstr, default MAIN_GAIA_TABLE_DEC

the ‘dec’ column in the table table_b_full_qualified_name

results_namestr, optional, default None

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

radiusfloat (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.

backgroundbool, optional, default ‘False’

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

verbosebool, optional, default ‘False’

flag to display information about the process

Returns:
A Job object

Gets datalinks associated to the provided identifiers TAP+ only

Parameters:
idsstr, int, str list or int list, mandatory

list of identifiers

linking_parameterstr, 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

verbosebool, 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()[source]

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)[source]

Launches a synchronous job

Parameters:
querystr, mandatory

query to be executed

namestr, optional, default None

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

output_filestr, 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_formatstr, 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.

verbosebool, optional, default ‘False’

flag to display information about the process

dump_to_filebool, optional, default ‘False’

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

upload_resourcestr, optional, default None

resource to be uploaded to UPLOAD_SCHEMA

upload_table_namestr, 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)[source]

Launches an asynchronous job

Parameters:
querystr, mandatory

query to be executed

namestr, optional, default None

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

output_filestr, 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_formatstr, 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.

verbosebool, optional, default ‘False’

flag to display information about the process

dump_to_filebool, optional, default ‘False’

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

backgroundbool, optional, default ‘False’

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

upload_resourcestr, optional, default None

resource to be uploaded to UPLOAD_SCHEMA

upload_table_namestr, optional, default None

resource temporary table name associated to the uploaded resource. This argument is required if upload_resource is provided.

autorunboolean, 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)[source]

Loads the specified table TAP+ only

Parameters:
idsstr, 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_typestr, 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’, ‘RESIDUAL_IMAGE’]. 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. Note that for ‘RESIDUAL_IMAGE’, only the format ‘fits’ can be used. Since the fits files only contain images, the returned table will be empty. Therefore, set ‘output_file’ to save the files to get access to their content.

linking_parameterstr, 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_databool, 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.

formatstr, 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_fileboolean, optional, default False

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

verbosebool, 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)[source]

Loads the specified user TAP+ only

Parameters:
user_idstr, mandatory

user id to load

verbosebool, optional, default ‘False’

flag to display information about the process

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

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:
userstr, default None

login name

passwordstr, default None

user password

credentials_filestr, default None

file containing user and password in two lines

verbosebool, optional, default ‘False’

flag to display information about the process

login_gui(*, verbose=False)[source]

Performs a login using a GUI dialog

Parameters:
verbosebool, optional, default ‘False’

flag to display information about the process

logout(*, verbose=False)[source]

Performs a logout

Parameters:
verbosebool, optional, default ‘False’

flag to display information about the process

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

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

Parameters:
coordinatestr or astropy.coordinates, mandatory

coordinates center point

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

radius (deg)

widthstr or astropy.units if no ‘radius’ is provided

box width

heightstr or astropy.units if no ‘radius’ is provided

box height

verbosebool, 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=())[source]

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

Parameters:
coordinatestr or astropy.coordinates, mandatory

coordinates center point

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

radius

widthstr or astropy.units if no ‘radius’ is provided

box width

heightstr or astropy.units if no ‘radius’ is provided

box height

verbosebool, 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).