astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- MAST Queries (`astroquery.mast`) »
- MastMissionsClass

# MastMissionsClass

class astroquery.mast.MastMissionsClass(*, mission='hst', mast_token=None)

  Bases: `MastQueryWithLogin`

  MastMissions search class. Class that allows direct programmatic access to retrieve metadata via the MAST search API for a given mission.

  Attributes Summary

  `cache_location` |
  `mission` |

  Methods Summary

  `__call__`(*args, **kwargs) | init a fresh copy of self
  `authenticated`() |
  `clear_cache`() | Removes all cache files.
  `disable_cloud_dataset`() |
  `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 `Table` of mission data products based on given filters.
  `get_column_list`() | For a mission, return a list of all searchable columns and their descriptions
  `get_dataset_kwd`() | Return the Dataset ID keyword for the selected mission.
  `get_product_list`(*args, **kwargs) | Queries the service and returns a table object.
  `get_product_list_async`(datasets) | 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`(objectname, *[, radius, ...]) | Given an object name, 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 and radius, returns a list of matching dataset IDs.
  `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
  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, verbose=True)

    Downloads a single file based on the data URI.

    Parameters:
      uri str

        The product dataURI

      local_path str

        Directory or filename to which the file will be downloaded. Defaults to current working directory.

      cache bool

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

      verbose bool, optional

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

    Returns:
      status: str

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

      msg str

        An error status message, if any.

      url str

        The full URL download path.

  download_products(products, *, download_dir=None, flat=False, cache=True, extension=None, verbose=True, **filters)

    Download specified data products.

    Parameters:
      products str, list, `Table`

        Either a single or list of dataset IDs (e.g., as input for `get_product_list`), or a Table of products (e.g., as output from `get_product_list`)

      download_dir str or Path, optional

        Directory for file downloads. Defaults to current directory.

      flat bool, 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_dir` without subdirectories.

      cache bool, optional

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

      extension string or list, optional

        Default is None. Filter by file extension.

      verbose bool, 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”]

    Returns:
      manifest `Table`

        A table manifest showing downloaded file locations and statuses.

  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:
      provider str

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

      profile str

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

      verbose bool

        Default True. Logger to display extra info and warning.

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

    Filters an `Table` of mission data products based on given filters.

    Parameters:
      products `Table`

        Table containing data products to be filtered.

      extension string 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=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:
      response `Table`

        Filtered Table of data products.

  get_column_list()

    For a mission, return a list of all searchable columns and their descriptions

    Returns:
      response `Table` that contains columns names, types, and descriptions
  get_dataset_kwd()

    Return the Dataset ID keyword for the selected mission. If the keyword is unknown, returns None.

    Returns:
      keyword str or None

        Dataset ID keyword or None if unknown.

  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:
      datasets str, list, `Row`, `Column`, `Table`

        Row/Table of MastMissions query results (e.g. output from `query_object`) or single/list of dataset ID(s).

    Returns:
      table A `Table` object.
  get_product_list_async(datasets)

    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:
      datasets str, list, `Row`, `Column`, `Table`

        Row/Table of MastMissions query results (e.g. output from `query_object`) or single/list of dataset ID(s).

    Returns:
      response list of `Response`
  get_unique_product_list(datasets)

    Given a dataset ID or list of dataset IDs, returns a list of associated data products with unique filenames.

    Parameters:
      datasets str, list, `Row`, `Column`, `Table`

        Row/Table of MastMissions query results (e.g. output from `query_object`) or single/list of dataset ID(s).

    Returns:
      unique_products `Table`

        Table containing products with unique URIs.

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

    Log into the MAST portal.

    Parameters:
      token string, 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_token bool, optional

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

      reenter_token bool, 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:
      coordinates str or `coordinates` object

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

      objectname str

        The name of the target around which to search.

      radius str or `Quantity` object

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

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

      **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` functions), 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 calling `get_column_list` function. To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values.

    Returns:
      table A `Table` object.
  query_criteria_async(*, coordinates=None, objectname=None, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, resolver=None, **criteria)

    Given a set of search criteria, returns a list of mission metadata.

    Parameters:
      coordinates str or `coordinates` object

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

      objectname str

        The name of the target around which to search.

      radius str or `Quantity` object

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

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

      **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` functions), 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 calling `get_column_list` function. To filter by multiple values for a single column, pass in a list of values or a comma-separated string of values.

    Returns:
      response list of `Response`
  query_object(*args, **kwargs)

    Queries the service and returns a table object.

    Given an object name, returns a list of matching rows.

    Parameters:
      objectname str

        The name of the target around which to search.

      radius str or `Quantity` object, optional

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

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

      **criteria

        Other mission-specific criteria arguments. All valid filters can be found using `get_column_list` function. 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.

    Returns:
      table A `Table` object.
  query_object_async(objectname, *, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, resolver=None, **criteria)

    Given an object name, returns a list of matching rows.

    Parameters:
      objectname str

        The name of the target around which to search.

      radius str or `Quantity` object, optional

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

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

      **criteria

        Other mission-specific criteria arguments. All valid filters can be found using `get_column_list` function. 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.

    Returns:
      response list of `Response`
  query_region(*args, **kwargs)

    Queries the service and returns a table object.

    Given a sky position and radius, returns a list of matching dataset IDs.

    Parameters:
      coordinates str or `coordinates` object

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

      radius str or `Quantity` object

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

      **criteria

        Other mission-specific criteria arguments. All valid filters can be found using `get_column_list` function. 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.

    Returns:
      table A `Table` object.
  query_region_async(coordinates, *, radius=<Quantity 3. arcmin>, limit=5000, offset=0, select_cols=None, **criteria)

    Given a sky position and radius, returns a list of matching dataset IDs.

    Parameters:
      coordinates str or `coordinates` object

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

      radius str or `Quantity` object

        Default is 3 arcminutes. The radius around the coordinates to search within. The string must be parsable by `Angle`. The appropriate `Quantity` object from `units` may also be used.

      limit int

        Default is 5000. The maximum number of dataset IDs in the results.

      offset int

        Default is 0. The number of records you wish to skip before selecting records.

      select_cols: list, 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.

      **criteria

        Other mission-specific criteria arguments. All valid filters can be found using `get_column_list` function. 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.

    Returns:
      response list of `Response`
  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:
      objectname str

        Name of astronomical object to resolve.

      resolver str, 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_all bool, 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:
      response `SkyCoord`, 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:
      verbose bool, optional

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

    Returns:
      response dict