ObservationsClass

class astroquery.mast.ObservationsClass(mast_token=None)

Bases: MastQueryWithLogin

MAST Observations query class.

Class for querying MAST observational data.

Attributes Summary

cache_location

Methods Summary

__call__(*args, **kwargs)	init a fresh copy of self
authenticated()
clear_cache()	Removes all cache files.
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, ...])	Filters an Table of data products based on given filters.
get_cloud_uri(data_product, *[, ...])	For a given data product, returns the associated cloud URI.
get_cloud_uris([data_products, ...])	Given an Table of data products or query criteria and filter parameters, 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.
get_unique_product_list(observations, *[, ...])	Given a "Product Group Id" (column name obsid), returns a list of associated data products with unique dataURIs.
list_missions()	Lists data missions archived by MAST and available 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.
reset_cache_location()	Resets the cache location to the default astropy cache
resolve_object(objectname, *[, resolver, ...])	Resolves an object name to a position on the sky.
session_info([verbose])	Displays information about current MAST user, and returns user info dictionary.

Attributes Documentation

cache_location

Methods Documentation

__call__(*args, **kwargs)

init a fresh copy of self

authenticated()

clear_cache()

Removes all cache files.

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, verbose=True)

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 or filename to which the file 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.

verbosebool, optional

Default True. Whether to show download progress in the console.

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, flat=False, cache=True, curl_flag=False, mrp_only=False, cloud_only=False, verbose=True, **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.

flatbool, optional

Default is False. If set to True, and download_dir is specified, it will put all files into download_dir without subdirectories. Or if set to True and download_dir is not specified, it will put files in the current directory, again with no subdirs. The default of False puts files into the standard directory structure of “mastDownload/<obs_collection>/<obs_id>/”. If curl_flag=True, the flat flag has no effect, as astroquery does not control how MAST generates the curl download script.

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.

verbosebool, optional

Default True. Whether to show download progress in the console.

**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)

Filters an Table of data products 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

Column-based filters to apply to the products table. Valid filters are all products fields listed here.

Each keyword corresponds to a column name in the table, with the argument being one or more acceptable values for that column. AND logic is applied between filters.

Within each column’s filter set:

• Positive (non-negated) values are combined with OR logic.

• Any negated values (prefixed with “!”) are combined with AND logic against the ORed positives. This results in: (NOT any_negatives) AND (any_positives) Examples: productType=['A', 'B', '!C'] → (productType != C) AND (productType == A OR productType == B) size=['!14400', '<20000'] → (size != 14400) AND (size < 20000)

For columns with numeric data types (int or float), filter values can be expressed in several ways:

• A single number: size=100

• A range in the form “start..end”: size="100..1000"

• A comparison operator followed by a number: size=">=1000"

• A list of expressions (OR logic): size=[100, "500..1000", ">=1500"]

Returns:

responseTable

Filtered table of data products.

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

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=None, *, include_bucket=True, full_url=False, pagesize=None, page=None, mrp_only=False, extension=None, filter_products={}, return_uri_map=False, verbose=True, **criteria)

Given an Table of data products or query criteria and filter parameters, returns the associated cloud data URIs.

Parameters:

data_productsTable, list

Table containing products or list of MAST uris to be converted into cloud data uris. If provided, this will supercede page_size, page, or any keyword arguments passed in as criteria.

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.

pagesizeint, optional

Default None. Can be used to override the default pagesize when making a query. E.g. when using a slow internet connection. Query criteria must also be provided.

pageint, optional

Default None. Can be used to override the default behavior of all results being returned for a query to obtain one specific page of results. Query criteria must also be provided.

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.

filter_productsdict, optional

Filters to be applied to data products. Valid filters are all products fields listed here. The column name as a string is the key. The corresponding value is 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”]}

return_uri_mapbool, optional

Default False. If set to True, returns a dictionary mapping the original data product URIs to their corresponding cloud URIs. This is useful for tracking which products were successfully converted to cloud URIs.

verbosebool, optional

Default True. Whether to issue warnings if a product cannot be found in the cloud.

**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

List of URIs generated from the data products. May 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. Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. See column documentation here.

To return unique data products, use Observations.get_unique_product_list.

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.

batch_sizeint, optional

Default 500. Number of obsids to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.

Returns:

tableA Table object.

get_product_list_async(observations, *, batch_size=500)

Given a “Product Group Id” (column name obsid) returns a list of associated data products. Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. See column documentation here.

To return unique data products, use Observations.get_unique_product_list.

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.

batch_sizeint, optional

Default 500. Number of obsids to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.

Returns:

responselist of Response

A list of asynchronous response objects for each batch request.

get_unique_product_list(observations, *, batch_size=500)

Given a “Product Group Id” (column name obsid), returns a list of associated data products with unique dataURIs. Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. 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.

batch_sizeint, optional

Default 500. Number of obsids to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.

Returns:

unique_productsTable

Table containing products with unique dataURIs.

list_missions()

Lists data missions archived by MAST and available 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://ssoportal.stsci.edu/idp/profile/SAML2/Redirect/SSO?execution=e1s1 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 specific page of results.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

**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, resolver=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 specific page of results.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

**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, resolver=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 specific page of results.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

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

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

Returns:

tableA Table object.

query_object_async(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None, resolver=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.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

Returns:

responselist of Response

query_object_count(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None, resolver=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 specific page of results.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

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

reset_cache_location()

Resets the cache location to the default astropy cache

resolve_object(objectname, *, resolver=None, resolve_all=False)

Resolves an object name to a position on the sky.

Parameters:

objectnamestr

Name of astronomical object to resolve.

resolverstr, optional

The resolver to use when resolving a named target into coordinates. Valid options are “SIMBAD” and “NED”. If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. If resolve_all is True, this parameter will be ignored. Default is None.

resolve_allbool, optional

If True, will try to resolve the object name using all available resolvers (“NED”, “SIMBAD”). Function will return a dictionary where the keys are the resolver names and the values are the resolved coordinates. Default is False.

Returns:

responseSkyCoord, dict

If resolve_all is False, returns a SkyCoord object with the resolved coordinates. If resolve_all is True, returns a dictionary where the keys are the resolver names and the values are SkyCoord objects with the resolved coordinates.

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