ObservationsClass

class astroquery.mast.ObservationsClass(mast_token=None)

Bases: astroquery.mast.core.MastQueryWithLogin

MAST Observations query class.

Class for querying MAST observational data.

Methods Summary

__call__(*args, **kwargs)	init a fresh copy of self
authenticated()
disable_cloud_dataset()	Disables downloading public files from S3 instead of MAST
download_file(uri, *[, local_path, ...])	Downloads a single file based on the data URI
download_products(products, *[, ...])	Download data products.
enable_cloud_dataset([provider, profile, ...])	Enable downloading public files from S3 instead of MAST.
filter_products(products, *[, mrp_only, ...])	Takes an Table of MAST observation data products and filters it based on given filters.
get_cloud_uri(data_product, *[, ...])	For a given data product, returns the associated cloud URI.
get_cloud_uris(data_products, *[, ...])	Takes an Table of data products and returns the associated cloud data uris.
get_metadata(query_type)	Returns metadata about the requested query type.
get_product_list(*args, **kwargs)	Queries the service and returns a table object.
get_product_list_async(observations)	Given a "Product Group Id" (column name obsid) returns a list of associated data products.
list_missions()	Lists data missions archived by MAST and avaiable through astroquery.mast.
login([token, store_token, reenter_token])	Log into the MAST portal.
logout()	Log out of current MAST session.
query_criteria(*args, **kwargs)	Queries the service and returns a table object.
query_criteria_async(*[, pagesize, page])	Given an set of criteria, returns a list of MAST observations.
query_criteria_count(*[, pagesize, page])	Given an set of filters, returns the number of MAST observations meeting those criteria.
query_object(*args, **kwargs)	Queries the service and returns a table object.
query_object_async(objectname, *[, radius, ...])	Given an object name, returns a list of MAST observations.
query_object_count(objectname, *[, radius, ...])	Given an object name, returns the number of MAST observations.
query_region(*args, **kwargs)	Queries the service and returns a table object.
query_region_async(coordinates, *[, radius, ...])	Given a sky position and radius, returns a list of MAST observations.
query_region_count(coordinates, *[, radius, ...])	Given a sky position and radius, returns the number of MAST observations in that region.
resolve_object(objectname)	Resolves an object name to a position on the sky.
session_info([verbose])	Displays information about current MAST user, and returns user info dictionary.

Methods Documentation

__call__(*args, **kwargs)

init a fresh copy of self

authenticated()

disable_cloud_dataset()

Disables downloading public files from S3 instead of MAST

download_file(uri, *, local_path=None, base_url=None, cache=True, cloud_only=False)

Downloads a single file based on the data URI

Parameters

uristr

The product dataURI, e.g. mast:JWST/product/jw00736-o039_t001_miri_ch1-long_x1d.fits

local_pathstr

Directory in which the files will be downloaded. Defaults to current working directory.

base_url: str

A base url to use when downloading. Default is the MAST Portal API

cachebool

Default is True. If file is found on disk it will not be downloaded again.

cloud_onlybool, optional

Default False. If set to True and cloud data access is enabled (see enable_cloud_dataset) files that are not found in the cloud will be skipped rather than downloaded from MAST as is the default behavior. If cloud access is not enables this argument as no affect.

Returns

status: str

download status message. Either COMPLETE, SKIPPED, or ERROR.

msgstr

An error status message, if any.

urlstr

The full url download path

download_products(products, *, download_dir=None, cache=True, curl_flag=False, mrp_only=False, cloud_only=False, **filters)

Download data products. If cloud access is enabled, files will be downloaded from the cloud if possible.

Parameters

productsstr, list, Table

Either a single or list of obsids (as can be given to get_product_list), or a Table of products (as is returned by get_product_list)

download_dirstr, optional

Optional. Directory to download files to. Defaults to current directory.

cachebool, optional

Default is True. If file is found on disc it will not be downloaded again. Note: has no affect when downloading curl script.

curl_flagbool, optional

Default is False. If true instead of downloading files directly, a curl script will be downloaded that can be used to download the data files at a later time.

mrp_onlybool, optional

Default False. When set to true only “Minimum Recommended Products” will be returned.

cloud_onlybool, optional

Default False. If set to True and cloud data access is enabled (see enable_cloud_dataset) files that are not found in the cloud will be skipped rather than downloaded from MAST as is the default behavior. If cloud access is not enables this argument as no affect.

**filters

Filters to be applied. Valid filters are all products fields returned by get_metadata("products") and ‘extension’ which is the desired file extension. The Column Name (or ‘extension’) is the keyword, with the argument being one or more acceptable values for that parameter. Filter behavior is AND between the filters and OR within a filter set. For example: productType=”SCIENCE”,extension=[“fits”,”jpg”]

Returns

responseTable

The manifest of files downloaded, or status of files on disk if curl option chosen.

enable_cloud_dataset(provider='AWS', profile=None, verbose=True)

Enable downloading public files from S3 instead of MAST. Requires the boto3 library to function.

Parameters

providerstr

Which cloud data provider to use. We may in the future support multiple providers, though at the moment this argument is ignored.

profilestr

Profile to use to identify yourself to the cloud provider (usually in ~/.aws/config).

verbosebool

Default True. Logger to display extra info and warning.

filter_products(products, *, mrp_only=False, extension=None, **filters)

Takes an Table of MAST observation data products and filters it based on given filters.

Parameters

productsTable

Table containing data products to be filtered.

mrp_onlybool, optional

Default False. When set to true only “Minimum Recommended Products” will be returned.

extensionstring or array, optional

Default None. Option to filter by file extension.

**filters

Filters to be applied. Valid filters are all products fields listed here. The column name is the keyword, with the argument being one or more acceptable values for that parameter. Filter behavior is AND between the filters and OR within a filter set. For example: productType=”SCIENCE”,extension=[“fits”,”jpg”]

Returns

responseTable

get_cloud_uri(data_product, *, include_bucket=True, full_url=False)

For a given data product, returns the associated cloud URI. If the product is from a mission that does not support cloud access an exception is raised. If the mission is supported but the product cannot be found in the cloud, the returned path is None.

Parameters

data_productRow

Product to be converted into cloud data uri.

include_bucketbool

Default True. When false returns the path of the file relative to the top level cloud storage location. Must be set to False when using the full_url argument.

full_urlbool

Default False. Return an HTTP fetchable url instead of a cloud uri. Must set include_bucket to False to use this option.

Returns

responsestr or None

Cloud URI generated from the data product. If the product cannot be found in the cloud, None is returned.

get_cloud_uris(data_products, *, include_bucket=True, full_url=False)

Takes an Table of data products and returns the associated cloud data uris.

Parameters

data_productsTable

Table containing products to be converted into cloud data uris.

include_bucketbool

Default True. When false returns the path of the file relative to the top level cloud storage location. Must be set to False when using the full_url argument.

full_urlbool

Default False. Return an HTTP fetchable url instead of a cloud uri. Must set include_bucket to False to use this option.

Returns

responselist

List of URIs generated from the data products, list way contain entries that are None if data_products includes products not found in the cloud.

get_metadata(query_type)

Returns metadata about the requested query type.

Parameters

query_typestr

The query to get metadata for. Options are observations, and products.

Returns

responseTable

The metadata table.

get_product_list(*args, **kwargs)

Queries the service and returns a table object.

Given a “Product Group Id” (column name obsid) returns a list of associated data products. See column documentation here.

Parameters

observationsstr or Row or list/Table of same

Row/Table of MAST query results (e.g. output from query_object) or single/list of MAST Product Group Id(s) (obsid). See description here.

Returns

tableA Table object.

get_product_list_async(observations)

Given a “Product Group Id” (column name obsid) returns a list of associated data products. See column documentation here.

Parameters

observationsstr or Row or list/Table of same

Row/Table of MAST query results (e.g. output from query_object) or single/list of MAST Product Group Id(s) (obsid). See description here.

Returns

responselist of Response

list_missions()

Lists data missions archived by MAST and avaiable through astroquery.mast.

Returns

responselist

List of available missions.

login(token=None, store_token=False, reenter_token=False)

Log into the MAST portal.

Parameters

tokenstring, optional

Default is None. The token to authenticate the user. This can be generated at https://auth.mast.stsci.edu/token?suggested_name=Astroquery&suggested_scope=mast:exclusive_access. If not supplied, it will be prompted for if not in the keyring or set via $MAST_API_TOKEN

store_tokenbool, optional

Default False. If true, MAST token will be stored securely in your keyring.

reenter_tokenbool, optional

Default False. Asks for the token even if it is already stored in the keyring or $MAST_API_TOKEN environment variable. This is the way to overwrite an already stored password on the keyring.

logout()

Log out of current MAST session.

query_criteria(*args, **kwargs)

Queries the service and returns a table object.

Given an set of criteria, returns a list of MAST observations. Valid criteria are returned by get_metadata("observations")

Parameters

pagesizeint, optional

Can be used to override the default pagesize. E.g. when using a slow internet connection.

pageint, optional

Can be used to override the default behavior of all results being returned to obtain one sepcific page of results.

**criteria

Criteria to apply. At least one non-positional criteria must be supplied. Valid criteria are coordinates, objectname, radius (as in query_region and query_object), and all observation fields returned by the get_metadata("observations"). The Column Name is the keyword, with the argument being one or more acceptable values for that parameter, except for fields with a float datatype where the argument should be in the form [minVal, maxVal]. For non-float type criteria wildcards maybe used (both * and % are considered wildcards), however only one wildcarded value can be processed per criterion. RA and Dec must be given in decimal degrees, and datetimes in MJD. For example: filters=[“FUV”,”NUV”],proposal_pi=”Ost*”,t_max=[52264.4586,54452.8914]

Returns

tableA Table object.

query_criteria_async(*, pagesize=None, page=None, **criteria)

Given an set of criteria, returns a list of MAST observations. Valid criteria are returned by get_metadata("observations")

Parameters

pagesizeint, optional

Can be used to override the default pagesize. E.g. when using a slow internet connection.

pageint, optional

Can be used to override the default behavior of all results being returned to obtain one sepcific page of results.

**criteria

Criteria to apply. At least one non-positional criteria must be supplied. Valid criteria are coordinates, objectname, radius (as in query_region and query_object), and all observation fields returned by the get_metadata("observations"). The Column Name is the keyword, with the argument being one or more acceptable values for that parameter, except for fields with a float datatype where the argument should be in the form [minVal, maxVal]. For non-float type criteria wildcards maybe used (both * and % are considered wildcards), however only one wildcarded value can be processed per criterion. RA and Dec must be given in decimal degrees, and datetimes in MJD. For example: filters=[“FUV”,”NUV”],proposal_pi=”Ost*”,t_max=[52264.4586,54452.8914]

Returns

responselist of Response

query_criteria_count(*, pagesize=None, page=None, **criteria)

Given an set of filters, returns the number of MAST observations meeting those criteria.

Parameters

pagesizeint, optional

Can be used to override the default pagesize. E.g. when using a slow internet connection.

pageint, optional

Can be used to override the default behavior of all results being returned to obtain one sepcific page of results.

**criteria

Criteria to apply. At least one non-positional criterion must be supplied. Valid criteria are coordinates, objectname, radius (as in query_region and query_object), and all observation fields listed here. The Column Name is the keyword, with the argument being one or more acceptable values for that parameter, except for fields with a float datatype where the argument should be in the form [minVal, maxVal]. For non-float type criteria wildcards maybe used (both * and % are considered wildcards), however only one wildcarded value can be processed per criterion. RA and Dec must be given in decimal degrees, and datetimes in MJD. For example: filters=[“FUV”,”NUV”],proposal_pi=”Ost*”,t_max=[52264.4586,54452.8914]

Returns

responseint

query_object(*args, **kwargs)

Queries the service and returns a table object.

Given an object name, returns a list of MAST observations. See column documentation here.

Parameters

objectnamestr

The name of the target around which to search.

radiusstr or Quantity object, optional

Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.

pageint, optional

Defaulte None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

tableA Table object.

query_object_async(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Given an object name, returns a list of MAST observations. See column documentation here.

Parameters

objectnamestr

The name of the target around which to search.

radiusstr or Quantity object, optional

Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.

pageint, optional

Defaulte None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

responselist of Response

query_object_count(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Given an object name, returns the number of MAST observations.

Parameters

objectnamestr

The name of the target around which to search.

radiusstr or Quantity object, optional

The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Can be used to override the default pagesize. E.g. when using a slow internet connection.

pageint, optional

Can be used to override the default behavior of all results being returned to obtain one sepcific page of results.

Returns

responseint

query_region(*args, **kwargs)

Queries the service and returns a table object.

Given a sky position and radius, returns a list of MAST observations. See column documentation here.

Parameters

coordinatesstr or coordinates object

The target around which to search. It may be specified as a string or as the appropriate coordinates object.

radiusstr or Quantity object, optional

Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.

pageint, optional

Default None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

tableA Table object.

query_region_async(coordinates, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Given a sky position and radius, returns a list of MAST observations. See column documentation here.

Parameters

coordinatesstr or coordinates object

The target around which to search. It may be specified as a string or as the appropriate coordinates object.

radiusstr or Quantity object, optional

Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.

pageint, optional

Default None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

responselist of Response

query_region_count(coordinates, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Given a sky position and radius, returns the number of MAST observations in that region.

Parameters

coordinatesstr or coordinates object

The target around which to search. It may be specified as a string or as the appropriate coordinates object.

radiusstr or Quantity object, optional

The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.

pagesizeint, optional

Can be used to override the default pagesize for. E.g. when using a slow internet connection.

pageint, optional

Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

responseint

resolve_object(objectname)

Resolves an object name to a position on the sky.

Parameters

objectnamestr

Name of astronomical object to resolve.

Returns

responseSkyCoord

The sky position of the given object.

session_info(verbose=True)

Displays information about current MAST user, and returns user info dictionary.

Parameters

verbosebool, optional

Default True. Set to False to suppress output to stdout.

Returns

responsedict