astrobase.services.mast module¶

This interfaces with the MAST API. The main use for this (for now) is to fill in TIC information for checkplots.

The MAST API service documentation is at:

https://mast.stsci.edu/api/v0/index.html

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

http://astroquery.readthedocs.io

astrobase.services.mast.mast_query(service, params, data=None, apiversion='v0', forcefetch=False, cachedir='~/.astrobase/mast-cache', verbose=True, timeout=10.0, refresh=5.0, maxtimeout=90.0, maxtries=3, raiseonfail=False, jitter=5.0)[source]¶

This queries the STScI MAST service for catalog data.

All results are downloaded as JSON files that are written to cachedir.

Parameters:

service (str) – This is the name of the service to use. See https://mast.stsci.edu/api/v0/_services.html for a list of all available services.
params (dict) – This is a dict containing the input params to the service as described on its details page linked in the service description page on MAST.
data (dict or None) – This contains optional data to upload to the service.
apiversion (str) – The API version of the MAST service to use. This sets the URL that this function will call, using apiversion as key into the MAST_URLS dict above.
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.
raiseonfail (bool) – If this is True, the function will raise an Exception if something goes wrong, instead of returning None.
jitter (float) – This is used to control the scale of the random wait in seconds before starting the query. Useful in parallelized situations.

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.mast.tic_conesearch(ra, decl, radius_arcmin=5.0, apiversion='v0', forcefetch=False, cachedir='~/.astrobase/mast-cache', verbose=True, timeout=10.0, refresh=5.0, maxtimeout=90.0, maxtries=3, jitter=5.0, raiseonfail=False)[source]¶

This runs a TESS Input Catalog cone search on MAST.

If you use this, please cite the TIC paper (Stassun et al 2018; http://adsabs.harvard.edu/abs/2018AJ….156..102S). Also see the “living” TESS input catalog docs:

https://docs.google.com/document/d/1zdiKMs4Ld4cXZ2DW4lMX-fuxAF6hPHTjqjIwGqnfjqI

Also see: https://mast.stsci.edu/api/v0/_t_i_cfields.html for the fields returned by the service and present in the result JSON file.

Parameters:

ra,decl (float) – The center coordinates of the cone-search in decimal degrees.
radius_arcmin (float) – The cone-search radius in arcminutes.
apiversion (str) – The API version of the MAST service to use. This sets the URL that this function will call, using apiversion as key into the MAST_URLS dict above.
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.
jitter (float) – This is used to control the scale of the random wait in seconds before starting the query. Useful in parallelized situations.
raiseonfail (bool) – If this is True, the function will raise an Exception if something goes wrong, instead of returning None.

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.mast.tic_xmatch(ra, decl, radius_arcsec=5.0, apiversion='v0', forcefetch=False, cachedir='~/.astrobase/mast-cache', verbose=True, timeout=90.0, refresh=5.0, maxtimeout=180.0, maxtries=3, jitter=5.0, raiseonfail=False)[source]¶

This does a cross-match with TIC.

Parameters:

ra,decl (np.arrays or lists of floats) – The coordinates that will be cross-matched against the TIC.
radius_arcsec (float) – The cross-match radius in arcseconds.
apiversion (str) – The API version of the MAST service to use. This sets the URL that this function will call, using apiversion as key into the MAST_URLS dict above.
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.
jitter (float) – This is used to control the scale of the random wait in seconds before starting the query. Useful in parallelized situations.
raiseonfail (bool) – If this is True, the function will raise an Exception if something goes wrong, instead of returning None.

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.mast.tic_objectsearch(objectid, idcol_to_use='ID', apiversion='v0', forcefetch=False, cachedir='~/.astrobase/mast-cache', verbose=True, timeout=90.0, refresh=5.0, maxtimeout=180.0, maxtries=3, jitter=5.0, raiseonfail=False)[source]¶

This runs a TIC search for a specified TIC ID.

Parameters:

objectid (str) – The object ID to look up information for.
idcol_to_use (str) – This is the name of the object ID column to use when looking up the provided objectid. This is one of {‘ID’, ‘HIP’, ‘TYC’, ‘UCAC’, ‘TWOMASS’, ‘ALLWISE’, ‘SDSS’, ‘GAIA’, ‘APASS’, ‘KIC’}.
apiversion (str) – The API version of the MAST service to use. This sets the URL that this function will call, using apiversion as key into the MAST_URLS dict above.
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.
jitter (float) – This is used to control the scale of the random wait in seconds before starting the query. Useful in parallelized situations.
raiseonfail (bool) – If this is True, the function will raise an Exception if something goes wrong, instead of returning None.

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