astrobase.services.gaia module

This queries the GAIA catalog for object lists in specified areas of the sky. The main use of this module is to generate realistic spatial distributions of stars for variability recovery simulations in combination with colors and luminosities from the TRILEGAL galaxy model.

If you use this module, please cite the GAIA papers as outlined at:

https://gaia.esac.esa.int/documentation//GDR1/Miscellaneous/sec_credit_and_citation_instructions.html

Much of this module is derived from the example given at:

http://gea.esac.esa.int/archive-help/commandline/index.html

For a more general and useful interface to the GAIA catalog, see the astroquery package by A. Ginsburg, B. Sipocz, et al.:

http://astroquery.readthedocs.io/en/latest/gaia/gaia.html

astrobase.services.gaia.tap_query(querystr, gaia_mirror=None, data_release='dr2', returnformat='csv', forcefetch=False, cachedir='~/.astrobase/gaia-cache', verbose=True, timeout=15.0, refresh=2.0, maxtimeout=300.0, maxtries=3, complete_query_later=False)[source]

This queries the GAIA TAP service using an ADQL query string.

Parameters:
  • querystr (str) – This is the ADQL query string. See: http://www.ivoa.net/documents/ADQL/2.0 for the specification and http://gea.esac.esa.int/archive-help/adql/index.html for GAIA-specific additions.
  • gaia_mirror ({'gaia','heidelberg','vizier'} or None) – This is the key used to select a GAIA catalog mirror from the GAIA_URLS dict above. If set, the specified mirror will be used. If None, a random mirror chosen from that dict will be used.
  • data_release ({'dr2', 'edr3'}) – The Gaia data release to use for the query. This provides hints for which table to use for the GAIA mirror being queried.
  • returnformat ({'csv','votable','json'}) – The returned file format to request from the GAIA catalog service.
  • forcefetch (bool) – If this is True, the query will be retried even if cached results for it exist.
  • cachedir (str) – This points to the directory where results will be downloaded.
  • verbose (bool) – If True, will indicate progress and warn of any issues.
  • timeout (float) – This sets the amount of time in seconds to wait for the service to respond to our initial request.
  • refresh (float) – This sets the amount of time in seconds to wait before checking if the result file is available. If the results file isn’t available after refresh seconds have elapsed, the function will wait for refresh seconds continuously, until maxtimeout is reached or the results file becomes available.
  • maxtimeout (float) – The maximum amount of time in seconds to wait for a result to become available after submitting our query request.
  • maxtries (int) – The maximum number of tries (across all mirrors tried) to make to either submit the request or download the results, before giving up.
  • completequerylater (bool) – If set to True, a submitted query that does not return a result before maxtimeout has passed will be cancelled but its input request parameters and the result URL provided by the service will be saved. If this function is then called later with these same input request parameters, it will check if the query finally finished and a result is available. If so, will download the results instead of submitting a new query. If it’s not done yet, will start waiting for results again. To force launch a new query with the same request parameters, set the forcefetch kwarg to True.
Returns:

This returns a dict of the following form:

{'params':dict of the input params used for the query,
 'provenance':'cache' or 'new download',
 'result':path to the file on disk with the downloaded data table}

Return type:

dict
astrobase.services.gaia.objectlist_conesearch(racenter, declcenter, searchradiusarcsec, gaia_mirror=None, data_release='dr2', columns=('source_id', 'ra', 'dec', 'phot_g_mean_mag', 'l', 'b', 'parallax', 'parallax_error', 'pmra', 'pmra_error', 'pmdec', 'pmdec_error'), extra_filter=None, returnformat='csv', forcefetch=False, cachedir='~/.astrobase/gaia-cache', verbose=True, timeout=15.0, refresh=2.0, maxtimeout=300.0, maxtries=3, complete_query_later=True)[source]

This queries the GAIA TAP service for a list of objects near the coords.

Runs a conesearch around (racenter, declcenter) with radius in arcsec of searchradiusarcsec.

Parameters:
  • racenter,declcenter (float) – The center equatorial coordinates in decimal degrees.
  • searchradiusarcsec (float) – The search radius of the cone-search in arcseconds.
  • gaia_mirror ({'gaia','heidelberg','vizier'} or None) – This is the key used to select a GAIA catalog mirror from the GAIA_URLS dict above. If set, the specified mirror will be used. If None, a random mirror chosen from that dict will be used.
  • data_release ({'dr2', 'edr3'}) – The Gaia data release to use for the query.
  • columns (sequence of str) – This indicates which columns from the GAIA table to request for the objects found within the search radius.
  • extra_filter (str or None) – If this is provided, must be a valid ADQL filter string that is used to further filter the cone-search results.
  • returnformat ({'csv','votable','json'}) – The returned file format to request from the GAIA catalog service.
  • forcefetch (bool) – If this is True, the query will be retried even if cached results for it exist.
  • cachedir (str) – This points to the directory where results will be downloaded.
  • verbose (bool) – If True, will indicate progress and warn of any issues.
  • timeout (float) – This sets the amount of time in seconds to wait for the service to respond to our initial request.
  • refresh (float) – This sets the amount of time in seconds to wait before checking if the result file is available. If the results file isn’t available after refresh seconds have elapsed, the function will wait for refresh seconds continuously, until maxtimeout is reached or the results file becomes available.
  • maxtimeout (float) – The maximum amount of time in seconds to wait for a result to become available after submitting our query request.
  • maxtries (int) – The maximum number of tries (across all mirrors tried) to make to either submit the request or download the results, before giving up.
  • completequerylater (bool) – If set to True, a submitted query that does not return a result before maxtimeout has passed will be cancelled but its input request parameters and the result URL provided by the service will be saved. If this function is then called later with these same input request parameters, it will check if the query finally finished and a result is available. If so, will download the results instead of submitting a new query. If it’s not done yet, will start waiting for results again. To force launch a new query with the same request parameters, set the forcefetch kwarg to True.
Returns:

This returns a dict of the following form:

{'params':dict of the input params used for the query,
 'provenance':'cache' or 'new download',
 'result':path to the file on disk with the downloaded data table}

Return type:

dict
astrobase.services.gaia.objectlist_radeclbox(radeclbox, gaia_mirror=None, data_release='dr2', columns=('source_id', 'ra', 'dec', 'phot_g_mean_mag', 'l', 'b', 'parallax, parallax_error', 'pmra', 'pmra_error', 'pmdec', 'pmdec_error'), extra_filter=None, returnformat='csv', forcefetch=False, cachedir='~/.astrobase/gaia-cache', verbose=True, timeout=15.0, refresh=2.0, maxtimeout=300.0, maxtries=3, complete_query_later=True)[source]

This queries the GAIA TAP service for a list of objects in an equatorial coordinate box.

Parameters:
  • radeclbox (sequence of four floats) –

    This defines the box to search in:

    [ra_min, ra_max, decl_min, decl_max]
  • gaia_mirror ({'gaia','heidelberg','vizier'} or None) – This is the key used to select a GAIA catalog mirror from the GAIA_URLS dict above. If set, the specified mirror will be used. If None, a random mirror chosen from that dict will be used.
  • data_release ({'dr2', 'edr3'}) – The Gaia data release to use for the query.
  • columns (sequence of str) – This indicates which columns from the GAIA table to request for the objects found within the search radius.
  • extra_filter (str or None) – If this is provided, must be a valid ADQL filter string that is used to further filter the cone-search results.
  • returnformat ({'csv','votable','json'}) – The returned file format to request from the GAIA catalog service.
  • forcefetch (bool) – If this is True, the query will be retried even if cached results for it exist.
  • cachedir (str) – This points to the directory where results will be downloaded.
  • verbose (bool) – If True, will indicate progress and warn of any issues.
  • timeout (float) – This sets the amount of time in seconds to wait for the service to respond to our initial request.
  • refresh (float) – This sets the amount of time in seconds to wait before checking if the result file is available. If the results file isn’t available after refresh seconds have elapsed, the function will wait for refresh seconds continuously, until maxtimeout is reached or the results file becomes available.
  • maxtimeout (float) – The maximum amount of time in seconds to wait for a result to become available after submitting our query request.
  • maxtries (int) – The maximum number of tries (across all mirrors tried) to make to either submit the request or download the results, before giving up.
  • completequerylater (bool) – If set to True, a submitted query that does not return a result before maxtimeout has passed will be cancelled but its input request parameters and the result URL provided by the service will be saved. If this function is then called later with these same input request parameters, it will check if the query finally finished and a result is available. If so, will download the results instead of submitting a new query. If it’s not done yet, will start waiting for results again. To force launch a new query with the same request parameters, set the forcefetch kwarg to True.
Returns:

This returns a dict of the following form:

{'params':dict of the input params used for the query,
 'provenance':'cache' or 'new download',
 'result':path to the file on disk with the downloaded data table}

Return type:

dict

This queries the GAIA TAP service for a single GAIA source ID.

Parameters:
  • gaiaid (str) – The source ID of the object whose info will be collected.
  • gaia_mirror ({'gaia','heidelberg','vizier'} or None) – This is the key used to select a GAIA catalog mirror from the GAIA_URLS dict above. If set, the specified mirror will be used. If None, a random mirror chosen from that dict will be used.
  • data_release ({'dr2', 'edr3'}) – The Gaia data release to use for the query.
  • columns (sequence of str) – This indicates which columns from the GAIA table to request for the objects found within the search radius.
  • returnformat ({'csv','votable','json'}) – The returned file format to request from the GAIA catalog service.
  • forcefetch (bool) – If this is True, the query will be retried even if cached results for it exist.
  • cachedir (str) – This points to the directory where results will be downloaded.
  • verbose (bool) – If True, will indicate progress and warn of any issues.
  • timeout (float) – This sets the amount of time in seconds to wait for the service to respond to our initial request.
  • refresh (float) – This sets the amount of time in seconds to wait before checking if the result file is available. If the results file isn’t available after refresh seconds have elapsed, the function will wait for refresh seconds continuously, until maxtimeout is reached or the results file becomes available.
  • maxtimeout (float) – The maximum amount of time in seconds to wait for a result to become available after submitting our query request.
  • maxtries (int) – The maximum number of tries (across all mirrors tried) to make to either submit the request or download the results, before giving up.
  • completequerylater (bool) – If set to True, a submitted query that does not return a result before maxtimeout has passed will be cancelled but its input request parameters and the result URL provided by the service will be saved. If this function is then called later with these same input request parameters, it will check if the query finally finished and a result is available. If so, will download the results instead of submitting a new query. If it’s not done yet, will start waiting for results again. To force launch a new query with the same request parameters, set the forcefetch kwarg to True.
Returns:

This returns a dict of the following form:

{'params':dict of the input params used for the query,
 'provenance':'cache' or 'new download',
 'result':path to the file on disk with the downloaded data table}

Return type:

dict