MastMissionsClass#
- class astroquery.mast.MastMissionsClass(*, mission='hst', mast_token=None)[source]#
Bases:
MastQueryWithLoginMastMissions search class. Class that allows direct programmatic access to retrieve metadata via the MAST search API for a given mission.
Attributes Summary
Return a list of available missions in the MAST Search API.
Methods Summary
__call__(*args, **kwargs)init a fresh copy of self
Removes all cache files.
download_file(uri, *[, local_path, cache, ...])Downloads a single file based on the data URI.
download_products(products, *[, ...])Download specified data products.
enable_cloud_dataset([provider, profile, ...])filter_products(products, *[, extension])Filters an
Tableof mission data products based on given filters.Return a list of available missions in the MAST Search API.
get_cloud_uri_map([products, ...])Given an
Tableof data products or query criteria and filter parameters, returns the associated cloud data URIs.For a mission, return a list of all searchable columns and their descriptions
Return the Dataset ID keyword for the selected mission.
get_product(uri, *[, mission])Reads a data product file directly from a URI into an appropriate in-memory object based on file type.
get_product_list(*args, **kwargs)Queries the service and returns a table object.
get_product_list_async(datasets, *[, batch_size])Given a dataset ID or list of dataset IDs, returns a list of associated data products.
get_unique_product_list(datasets, *[, ...])Given a dataset ID or list of dataset IDs, returns a list of associated data products with unique filenames.
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(*[, coordinates, ...])Given a set of search criteria, returns a list of mission metadata.
query_object(*args, **kwargs)Queries the service and returns a table object.
query_object_async(object_names, *[, ...])Given an object name (or names), returns a list of matching rows.
query_region(*args, **kwargs)Queries the service and returns a table object.
query_region_async(coordinates, *[, radius, ...])Given a sky position (or positions) and radius, returns a list of matching dataset IDs.
read_product(uri, *[, mission])Resets the cache location to the default astropy cache
resolve_object(object_name, *[, 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
- available_missions#
Return a list of available missions in the MAST Search API.
- cache_location#
- mission#
Methods Documentation
- __call__(*args, **kwargs)#
init a fresh copy of self
- authenticated()#
- clear_cache()#
Removes all cache files.
- disable_cloud_dataset()#
Deprecated since version v0.4.8: This function is non-operational and will be removed in a future release.
Disables downloading public files from S3 instead of MAST.
- download_file(uri, *, local_path=None, cache=True, mission=None, verbose=True)[source]#
Downloads a single file based on the data URI.
- Parameters:
- uristr
The product filename or URI to be downloaded.
- local_pathstr
Directory or filename to which the file will be downloaded. Defaults to current working directory.
- cachebool
Default is True. If file is found on disk, it will not be downloaded again.
- missionstr, optional
The mission to which the file belongs. If not provided, the current value of the
missionattribute will be used.- verbosebool, optional
Default is 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, extension=None, verbose=True, **filters)[source]#
Download specified data products.
- Parameters:
- productsstr, list of str,
Table, or list of dict Either a single or list of dataset IDs (e.g., as input for
get_product_list), a Table of products (e.g., as output fromget_product_list), or a JSON file or data from the MAST subscription service containing product information.- download_dirstr or Path, optional
Directory for file downloads. Defaults to current directory.
- flatbool, optional
Default is False. If False, puts files into the standard directory structure of “mastDownload/<mission>/<dataset ID>/”. If True, places files directly in
download_dirwithout subdirectories.- cachebool, optional
Default is True. If file is found on disc, it will not be downloaded again.
- extensionstring or list, optional
Default is None. Filter by file extension.
- verbosebool, optional
Default is True. Whether to show download progress in the console.
- **filters
Column-based filters to be applied. 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, OR logic within each filter set. For example: type=”science”, extension=[“fits”,”jpg”]
- productsstr, list of str,
- Returns:
- manifest
Table A table manifest showing downloaded file locations and statuses.
- manifest
- enable_cloud_dataset(provider='AWS', profile=None, verbose=True)#
Deprecated since version v0.4.8: This function is non-operational and will be removed in a future release.
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, *, extension=None, **filters)[source]#
Filters an
Tableof mission data products based on given filters.- Parameters:
- products
Table Table containing data products to be filtered.
- extensionstring or array, optional
Default is None. Filters by file extension(s), matching any specified extensions.
- **filters
Column-based filters to apply to the products table.
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:
file_suffix=['A', 'B', '!C']→ (file_suffix != C) AND (file_suffix == A OR file_suffix == 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=100A 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"]
- products
- Returns:
- response
Table Filtered Table of data products.
- response
- get_available_missions()[source]#
Return a list of available missions in the MAST Search API.
- Returns:
- missionslist
List of available missions in MAST Search API.
- get_cloud_uri_map(products=None, *, include_bucket=True, full_url=False, extension=None, filter_products={}, mission=None, verbose=True)[source]#
Given an
Tableof data products or query criteria and filter parameters, returns the associated cloud data URIs.- Parameters:
- products
Table, 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.
- 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”]}
- missionstr, optional
The mission to which the data products belong. If not provided, the current value of the
missionattribute will be used.- verbosebool, optional
Default True. Whether to issue warnings if a product cannot be found in the cloud.
- products
- Returns:
- mapdict
Dictionary mapping the original data product URIs to their corresponding cloud URIs.
- get_column_list()[source]#
For a mission, return a list of all searchable columns and their descriptions
- Returns:
- response
Tablethat contains columns names, types, and descriptions
- response
- get_dataset_kwd()[source]#
Return the Dataset ID keyword for the selected mission. If the keyword is unknown, returns None.
- Returns:
- keywordstr or None
Dataset ID keyword or None if unknown.
- get_product(uri, *, mission=None, **kwargs)[source]#
Reads a data product file directly from a URI into an appropriate in-memory object based on file type. Supported file types are FITS and ASDF.
FITS files are opened with
openand are downloaded and cached on disk. ASDF files are opened directly from the presigned S3 URL usingopenandopen, without being downloaded to disk.
- get_product_list(*args, **kwargs)#
Queries the service and returns a table object.
Given a dataset ID or list of dataset IDs, returns a list of associated data products.
To return unique data products, use
MastMissions.get_unique_product_list.- Parameters:
- datasetsstr, list,
Row,Column,Table Row/Table of MastMissions query results (e.g. output from
query_object) or single/list of dataset ID(s).- batch_sizeint, optional
Default 1000. Number of dataset IDs to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.
- datasetsstr, list,
- Returns:
- tableA
Tableobject.
- tableA
- get_product_list_async(datasets, *, batch_size=1000)[source]#
Given a dataset ID or list of dataset IDs, returns a list of associated data products.
To return unique data products, use
MastMissions.get_unique_product_list.- Parameters:
- datasetsstr, list,
Row,Column,Table Row/Table of MastMissions query results (e.g. output from
query_object) or single/list of dataset ID(s).- batch_sizeint, optional
Default 1000. Number of dataset IDs to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.
- datasetsstr, list,
- Returns:
- responselist of
Response
- responselist of
- get_unique_product_list(datasets, *, batch_size=1000)[source]#
Given a dataset ID or list of dataset IDs, returns a list of associated data products with unique filenames.
- Parameters:
- datasetsstr, list,
Row,Column,Table Row/Table of MastMissions query results (e.g. output from
query_object) or single/list of dataset ID(s).- batch_sizeint, optional
Default 1000. Number of dataset IDs to include in each batch request to the server. If you experience timeouts or connection errors, consider lowering this value.
- datasetsstr, list,
- Returns:
- unique_products
Table Table containing products with unique URIs.
- unique_products
- 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 a set of search criteria, returns a list of mission metadata.
- Parameters:
- coordinatesstr, iterable of str, or
coordinatesobject Coordinate target(s) around which to search. Can be specified as: - A single coordinate string or
SkyCoordobject - A comma-separated string of coordinates (e.g., “10.0 20.0, 15.0 25.0”) - An iterable of coordinate strings or coordinate objects- object_namesstr or iterable of str, optional
Object name target(s) around which to search. Can be specified as: - A single object name string - A comma-separated string of object names (e.g., “M31, M51, NGC 1234”) - An iterable of object name strings If both
coordinatesandobject_namesare provided, they are combined.- radiusstr or
Quantityobject Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used. The maximum supported query radius is 30 arcminutes.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- resolverstr, optional
Default is None. 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.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Criteria to apply. Valid criteria include coordinates, object_names, radius (as in
query_regionandquery_objectfunctions), and all fields listed in the column documentation for the mission being queried. List of all valid fields that can be used to match results on criteria can be retrieved by callingget_column_listfunction. To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- coordinatesstr, iterable of str, or
- Returns:
- tableA
Tableobject.
- tableA
- Raises:
- InvalidQueryError
If the query radius is larger than the limit (30 arcminutes).
- query_criteria_async(*, coordinates=None, object_names=None, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, resolver=None, count_only=False, **criteria)[source]#
Given a set of search criteria, returns a list of mission metadata.
- Parameters:
- coordinatesstr, iterable of str, or
coordinatesobject Coordinate target(s) around which to search. Can be specified as: - A single coordinate string or
SkyCoordobject - A comma-separated string of coordinates (e.g., “10.0 20.0, 15.0 25.0”) - An iterable of coordinate strings or coordinate objects- object_namesstr or iterable of str, optional
Object name target(s) around which to search. Can be specified as: - A single object name string - A comma-separated string of object names (e.g., “M31, M51, NGC 1234”) - An iterable of object name strings If both
coordinatesandobject_namesare provided, they are combined.- radiusstr or
Quantityobject Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used. The maximum supported query radius is 30 arcminutes.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- resolverstr, optional
Default is None. 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.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Criteria to apply. Valid criteria include coordinates, object_names, radius (as in
query_regionandquery_objectfunctions), and all fields listed in the column documentation for the mission being queried. List of all valid fields that can be used to match results on criteria can be retrieved by callingget_column_listfunction. To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- coordinatesstr, iterable of str, or
- Returns:
- responselist of
Response
- responselist of
- Raises:
- InvalidQueryError
If the query radius is larger than the limit (30 arcminutes).
- query_object(*args, **kwargs)#
Queries the service and returns a table object.
Given an object name (or names), returns a list of matching rows.
- Parameters:
- object_namesstr or iterable of str, optional
Object name target(s) around which to search. Can be specified as: - A single object name string - A comma-separated string of object names (e.g., “M31, M51, NGC 1234”) - An iterable of object name strings If both
coordinatesandobject_namesare provided, they are combined.- radiusstr or
Quantityobject, optional Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- resolverstr, optional
Default is None. 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.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Other mission-specific criteria arguments. All valid filters can be found using
get_column_listfunction. For example, one can specify the output columns(select_cols) or use other filters(conditions). To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- Returns:
- tableA
Tableobject.
- tableA
- query_object_async(object_names, *, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, resolver=None, count_only=False, **criteria)[source]#
Given an object name (or names), returns a list of matching rows.
- Parameters:
- object_namesstr or iterable of str, optional
Object name target(s) around which to search. Can be specified as: - A single object name string - A comma-separated string of object names (e.g., “M31, M51, NGC 1234”) - An iterable of object name strings If both
coordinatesandobject_namesare provided, they are combined.- radiusstr or
Quantityobject, optional Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- resolverstr, optional
Default is None. 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.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Other mission-specific criteria arguments. All valid filters can be found using
get_column_listfunction. For example, one can specify the output columns(select_cols) or use other filters(conditions). To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- Returns:
- responselist of
Response
- responselist of
- query_region(*args, **kwargs)#
Queries the service and returns a table object.
Given a sky position (or positions) and radius, returns a list of matching dataset IDs.
- Parameters:
- coordinatesstr, iterable of str, or
coordinatesobject The target(s) around which to search. Can be specified as: - A single coordinate string or
SkyCoordobject - A comma-separated string of coordinates (e.g., “10.0 20.0, 15.0 25.0”) - An iterable of coordinate strings orcoordinatesobjects- radiusstr or
Quantityobject Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used. The maximum supported query radius is 30 arcminutes.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Other mission-specific criteria arguments. All valid filters can be found using
get_column_listfunction. For example, one can specify the output columns(select_cols) or use other filters(conditions). To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- coordinatesstr, iterable of str, or
- Returns:
- tableA
Tableobject.
- tableA
- Raises:
- InvalidQueryError
If the query radius is larger than the limit (30 arcminutes).
- query_region_async(coordinates, *, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, count_only=False, **criteria)[source]#
Given a sky position (or positions) and radius, returns a list of matching dataset IDs.
- Parameters:
- coordinatesstr, iterable of str, or
coordinatesobject The target(s) around which to search. Can be specified as: - A single coordinate string or
SkyCoordobject - A comma-separated string of coordinates (e.g., “10.0 20.0, 15.0 25.0”) - An iterable of coordinate strings orcoordinatesobjects- radiusstr or
Quantityobject Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by
Angle. The appropriateQuantityobject fromunitsmay also be used. The maximum supported query radius is 30 arcminutes.- limitint
Default is 5000. The maximum number of dataset IDs in the results.
- offsetint
Default is 0. The number of records you wish to skip before selecting records.
- select_cols: iterable or str or None, optional
Default is None. Names of columns that will be included in the result table. If None, a default set of columns will be returned. Can either be an iterable of column names, a comma-separated string of column names, or ‘all’/’*’ to return all available columns.
- count_onlybool, optional
Default is False. If True, only the count of matching datasets will be returned.
- **criteria
Other mission-specific criteria arguments. All valid filters can be found using
get_column_listfunction. For example, one can specify the output columns(select_cols) or use other filters(conditions). To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values. For the Roman mission, you can also use the special “pass_id” keyword as an alias for the “pass” column, which is a reserved keyword in Python.
- coordinatesstr, iterable of str, or
- Returns:
- responselist of
Response
- responselist of
- Raises:
- InvalidQueryError
If the query radius is larger than the limit (30 arcminutes).
- read_product(uri, *, mission=None, **kwargs)[source]#
Deprecated since version v0.4.12: The read_product function is deprecated and may be removed in a future version. Use get_product instead.
Deprecated. Use
get_productinstead.
- reset_cache_location()#
Resets the cache location to the default astropy cache
- resolve_object(object_name, *, resolver=None, resolve_all=False)#
Resolves an object name to a position on the sky.
- Parameters:
- object_namestr
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_allis 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:
- 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