astro query:docs

- Index
- Modules

### Navigation

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

# 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:
      uri str

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

      local_path str

        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

      cache bool

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

      cloud_only bool, 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.

      verbose bool, optional

        Default 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, 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:
      products str, 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_dir str, optional

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

      flat bool, 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.

      cache bool, 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_flag bool, 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_only bool, optional

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

      cloud_only bool, 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.

      verbose bool, 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:
      response `Table`

        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:
      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, *, mrp_only=False, extension=None, **filters)

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

    Parameters:
      products `Table`

        Table containing data products to be filtered.

      mrp_only bool, optional

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

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

        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_product `Row`, str

        Product to be converted into cloud data uri.

      include_bucket bool

        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_url bool

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

    Returns:
      response str 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_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_bucket bool

        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_url bool

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

      pagesize int, 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.

      page int, 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_only bool, optional

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

      extension string or array, optional

        Default None. Option to filter by file extension.

      filter_products dict, 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_map bool, 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.

      verbose bool, 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:
      response list

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

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

    Returns:
      response `Table`

        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:
      observations str 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:
      table A `Table` object.
  get_product_list_async(observations)

    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:
      observations str 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:
      response list of `Response`
  get_unique_product_list(observations)

    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:
      observations str 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:
      unique_products `Table`

        Table containing products with unique dataURIs.

  list_missions()

    Lists data missions archived by MAST and available through `astroquery.mast`.

    Returns:
      response list

        List of available missions.

  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 an set of criteria, returns a list of MAST observations. Valid criteria are returned by `get_metadata("observations")`

    Parameters:
      pagesize int, optional

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

      page int, optional

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

      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. 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:
      table A `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:
      pagesize int, optional

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

      page int, optional

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

      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. 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:
      response list 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:
      pagesize int, optional

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

      page int, optional

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

      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. 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:
      response int
  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:
      objectname str

        The name of the target around which to search.

      radius str 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.

      pagesize int, 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.

      page int, optional

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

      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. Default is None.

    Returns:
      table A `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:
      objectname str

        The name of the target around which to search.

      radius str 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.

      pagesize int, 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.

      page int, optional

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

      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. Default is None.

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

        The name of the target around which to search.

      radius str 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.

      pagesize int, optional

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

      page int, optional

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

      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. Default is None.

    Returns:
      response int
  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:
      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, 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.

      pagesize int, 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.

      page int, optional

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

    Returns:
      table A `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:
      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, 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.

      pagesize int, 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.

      page int, optional

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

    Returns:
      response list 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:
      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, optional

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

      pagesize int, optional

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

      page int, optional

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

    Returns:
      response int
  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