astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- ALMA Queries (`astroquery.alma`) »
- AlmaClass

# AlmaClass

class astroquery.alma.AlmaClass

  Bases: `QueryWithLogin`

  Attributes Summary

  `TIMEOUT` |
  `USERNAME` |
  `archive_url` |
  `auth` |
  `cycle0_table` | Return a table of Cycle 0 Project IDs and associated UIDs.
  `datalink` |
  `datalink_url` |
  `sia` |
  `sia_url` |
  `tap` |
  `tap_url` |

  Methods Summary

  `download_and_extract_files`(urls, *[, ...]) | Given a list of tarball URLs, it extracts all the FITS files (or whatever matches the regex)
  `download_files`(files, *[, savedir, cache, ...]) | Given a list of file URLs, download them
  `get_adhoc_service_access_url`(adhoc_service) |
  `get_adhoc_service_parameter`(adhoc_service, ...) |
  `get_cycle0_uid_contents`(uid) | List the file contents of a UID from Cycle 0.
  `get_data_info`(uids, *[, expand_tarfiles, ...]) | Return information about the data associated with ALMA uid(s)
  `get_files_from_tarballs`(downloaded_files, *) | Given a list of successfully downloaded tarballs, extract files with names matching a specified regular expression.
  `get_project_metadata`(projectid, *[, cache]) | Get the metadata - specifically, the project abstract - for a given project ID.
  `help`([cache]) | Return the valid query parameters
  `help_tap`() |
  `is_datalink_adhoc_service`(adhoc_service) |
  `is_proprietary`(uid) | Given an ALMA UID, query the servers to determine whether it is proprietary or not.
  `login`([username, store_password, ...]) | Login to the ALMA Science Portal.
  `query`(*args, **kwargs) | Queries the service and returns a table object.
  `query_async`(payload, *[, public, science, ...]) | Perform a generic query with user-specified payload
  `query_object`(*args, **kwargs) | Queries the service and returns a table object.
  `query_object_async`(object_name, *[, public, ...]) | Query the archive for a source name.
  `query_region`(*args, **kwargs) | Queries the service and returns a table object.
  `query_region_async`(coordinate, radius, *[, ...]) | Query the ALMA archive with a source name and radius
  `query_sia`(*[, pos, band, time, pol, ...]) | Use standard SIA2 attributes to query the ALMA SIA service.
  `query_tap`(query, *[, maxrec, uploads]) | Send query to the ALMA TAP. Results in `TAPResults` format.
  `retrieve_data_from_uid`(uids, *[, cache]) | Stage & Download ALMA data.

  Attributes Documentation

  TIMEOUT = 60
  USERNAME = ''
  archive_url = 'https://almascience.org'
  auth
  cycle0_table

    Return a table of Cycle 0 Project IDs and associated UIDs.

    The table is distributed with astroquery and was provided by Felix Stoehr.

  datalink
  datalink_url
  sia
  sia_url
  tap
  tap_url

  Methods Documentation

  download_and_extract_files(urls, *, delete=True, regex='.*\\.fits$', include_asdm=False, path='cache_path', verbose=True)

    Given a list of tarball URLs, it extracts all the FITS files (or whatever matches the regex)

    Parameters:
      urls str or list

        A single URL or a list of URLs

      include_asdm bool

        Only affects cycle 1+ data. If set, the ASDM files will be downloaded in addition to the script and log files. By default, though, this file will be downloaded and deleted without extracting any information: you must change the regex if you want to extract data from an ASDM tarball

  download_files(files, *, savedir=None, cache=True, continuation=True, skip_unauthorized=True, verify_only=False)

    Given a list of file URLs, download them

    Note: Given a list with repeated URLs, each will only be downloaded once, so the return may have a different length than the input list

    Parameters:
      files list

        List of URLs to download

      savedir None or str

        The directory to save to. Default is the cache location.

      cache bool

        Cache the download?

      continuation bool

        Attempt to continue where the download left off (if it was broken)

      skip_unauthorized bool

        If you receive “unauthorized” responses for some of the download requests, skip over them. If this is False, an exception will be raised.

      verify_only bool

        Option to go through the process of checking the files to see if they’re the right size, but not actually download them. This option may be useful if a previous download run failed partway.

  get_adhoc_service_access_url(adhoc_service)
  get_adhoc_service_parameter(adhoc_service, parameter_id)
  get_cycle0_uid_contents(uid)

    List the file contents of a UID from Cycle 0. Will raise an error if the UID is from cycle 1+, since those data have been released in a different and more consistent format. See https://almascience.nrao.edu/documents-and-tools/cycle-2/ALMAQA2Productsv1.01.pdf for details.

  get_data_info(uids, *, expand_tarfiles=False, with_auxiliary=True, with_rawdata=True)

    Return information about the data associated with ALMA uid(s)

    Parameters:
      uids list or str

        A list of valid UIDs or a single UID. UIDs should have the form: ‘uid://A002/X391d0b/X7b’

      expand_tarfiles bool

        False to return information on the tarfiles packages containing the data or True to return information about individual files in these packages

      with_auxiliary bool

        True to include the auxiliary packages, False otherwise

      with_rawdata bool

        True to include raw data, False otherwise

    Returns:
      Table with results or None. Table has the following columns: id (UID),
      access_url (URL to access data), service_def, content_length, content_type (MIME
      type), semantics, description (optional), error_message (optional)
  get_files_from_tarballs(downloaded_files, *, regex='.*\\.fits$', path='cache_path', verbose=True)

    Given a list of successfully downloaded tarballs, extract files with names matching a specified regular expression. The default is to extract all FITS files

    NOTE: alma now supports direct listing and downloads of tarballs. See `get_data_info` and `download_and_extract_files`

    Parameters:
      downloaded_files list

        A list of downloaded files. These should be paths on your local machine.

      regex str

        A valid regular expression

      path‘cache_path’ or str

        If ‘cache_path’, will use the astroquery.Alma cache directory (`Alma.cache_location`), otherwise will use the specified path. Note that the subdirectory structure of the tarball will be maintained.

    Returns:
      filelist list

        A list of the extracted file locations on disk

  get_project_metadata(projectid, *, cache=True)

    Get the metadata - specifically, the project abstract - for a given project ID.

  help(cache=True)

    Return the valid query parameters

  help_tap()
  is_datalink_adhoc_service(adhoc_service)
  is_proprietary(uid)

    Given an ALMA UID, query the servers to determine whether it is proprietary or not.

  login(username=None, store_password=False, reenter_password=False, auth_urls=['asa.alma.cl', 'rh-cas.alma.cl'])

    Login to the ALMA Science Portal.

    Parameters:
      username str, optional

        Username to the ALMA Science Portal. If not given, it should be specified in the config file.

      store_password bool, optional

        Stores the password securely in your keyring. Default is False.

      reenter_password bool, optional

        Asks for the password even if it is already stored in the keyring. This is the way to overwrite an already stored passwork on the keyring. Default is False.

  query(*args, **kwargs)

    Queries the service and returns a table object.

    Perform a generic query with user-specified payload

    Parameters:
      payload dictionary

        Please consult the `help` method

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      legacy_columns bool

        True to return the columns from the obsolete ALMA advanced query, otherwise return the current columns based on ObsCore model.

      get_query_payload bool

        Flag to indicate whether to simply return the payload.

      maxrec integer

        Cap on the amount of records returned. Default is no limit.

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprints as `regions` objects.

      Table with results. Columns are those in the ALMA ObsCore model
      (see ``help_tap``) unless ``legacy_columns`` argument is set to True.
    Returns:
      table A `Table` object.
  query_async(payload, *, public=True, science=True, legacy_columns=False, get_query_payload=False, maxrec=None, enhanced_results=False, **kwargs)

    Perform a generic query with user-specified payload

    Parameters:
      payload dictionary

        Please consult the `help` method

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      legacy_columns bool

        True to return the columns from the obsolete ALMA advanced query, otherwise return the current columns based on ObsCore model.

      get_query_payload bool

        Flag to indicate whether to simply return the payload.

      maxrec integer

        Cap on the amount of records returned. Default is no limit.

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprints as `regions` objects.

    Returns:
      Table with results. Columns are those in the ALMA ObsCore model
      (see `help_tap`) unless `legacy_columns` argument is set to True.
  query_object(*args, **kwargs)

    Queries the service and returns a table object.

    Query the archive for a source name.

    Parameters:
      object_name str

        The object name. Will be resolved by astropy.coord.SkyCoord

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprint as `regions` objects.

      payload dict

        Dictionary of additional keywords. See `help`.

    Returns:
      table A `Table` object.
  query_object_async(object_name, *, public=True, science=True, payload=None, enhanced_results=False, **kwargs)

    Query the archive for a source name.

    Parameters:
      object_name str

        The object name. Will be resolved by astropy.coord.SkyCoord

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprint as `regions` objects.

      payload dict

        Dictionary of additional keywords. See `help`.

  query_region(*args, **kwargs)

    Queries the service and returns a table object.

    Query the ALMA archive with a source name and radius

    Parameters:
      coordinates str / `astropy.coordinates`

        the identifier or coordinates around which to query.

      radius str / `Quantity`, optional

        the radius of the region

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      payload dict

        Dictionary of additional keywords. See `help`.

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprints as `regions` objects.

    Returns:
      table A `Table` object.
  query_region_async(coordinate, radius, *, public=True, science=True, payload=None, enhanced_results=False, **kwargs)

    Query the ALMA archive with a source name and radius

    Parameters:
      coordinates str / `astropy.coordinates`

        the identifier or coordinates around which to query.

      radius str / `Quantity`, optional

        the radius of the region

      public bool

        True to return only public datasets, False to return private only, None to return both

      science bool

        True to return only science datasets, False to return only calibration, None to return both

      payload dict

        Dictionary of additional keywords. See `help`.

      enhanced_results bool

        True to return a table with quantities instead of just values. It also returns the footprints as `regions` objects.

  query_sia(*, pos=None, band=None, time=None, pol=None, field_of_view=None, spatial_resolution=None, spectral_resolving_power=None, exptime=None, timeres=None, publisher_did=None, facility=None, collection=None, instrument=None, data_type=None, calib_level=None, target_name=None, res_format=None, maxrec=None, **kwargs)

    Use standard SIA2 attributes to query the ALMA SIA service.

    Parameters:
      pos single or list of tuples

        angle units (default: deg) the positional region(s) to be searched for data. Each region can be expressed as a tuple representing a CIRCLE, RANGE or POLYGON as follows: (ra, dec, radius) - for CIRCLE. (angle units - defaults to) (long1, long2, lat1, lat2) - for RANGE (angle units required) (ra, dec, ra, dec, ra, dec … ) ra/dec points for POLYGON all in angle units

      band scalar, tuple(interval) or list of tuples

        (spectral units (default: meter) the energy interval(s) to be searched for data.

      time single or list of `Time` or compatible strings

        the time interval(s) to be searched for data.

      pol single or list of str from `pyvo.dam.obscore.POLARIZATION_STATES`

        the polarization state(s) to be searched for data.

      field_of_view single or list of tuples

        angle units (default arcsec) the range(s) of field of view (size) to be searched for data

      spatial_resolution single or list of tuples

        angle units required the range(s) of spatial resolution to be searched for data

      spectral_resolving_power single or list of tuples

        the range(s) of spectral resolving power to be searched for data

      exptime single or list of tuples

        time units (default: second) the range(s) of exposure times to be searched for data

      timeres single of list of tuples

        time units (default: second) the range(s) of temporal resolution to be searched for data

      publisher_did single or list of str

        specifies the unique identifier of dataset(s). It is global because it must include information regarding the publisher (obs_publisher_did in ObsCore)

      collection single or list of str

        name of the collection that the data belongs to

      facility single or list of str

        specifies the name of the facility (usually telescope) where the data was acquired.

      instrument single or list of str

        specifies the name of the instrument with which the data was acquired.

      data_type‘image’|’cube’

        specifies the type of the data

      calib_level single or list from enum

        `pyvo.dam.obscore.CALIBRATION_LEVELS` specifies the calibration level of the data. Can be a single value or a list of values

      target_name single or list of str

        specifies the name of the target (e.g. the intention of the original science program or observation)

      res_format single or list of strings

        specifies response format(s).

      max_records int

        allows the client to limit the number or records in the response

      **kwargs custom query parameters

        single or a list of values (or tuples for intervals) custom query parameters that a specific service accepts. The values of the parameters need to follow the SIA2 format and represent the appropriate quantities (where applicable).

    Returns:
      Results in `SIA2Results` format.
      result.to_qtable in `QTable` format
  query_tap(query, *, maxrec=None, uploads=None)

    > Send query to the ALMA TAP. Results in `TAPResults` format. result.to_qtable in `QTable` format

    Parameters:
      query str

        ADQL query to be executed

      maxrec int

        maximum number of records to return

      uploads dict

        a mapping from temporary table names to objects containing a votable. These temporary tables can be referred to in queries. The keys in the dictionary are the names of temporary tables which need to be prefixed with the TAP_UPLOAD schema in the actual query. The values are either astropy.table.Table instances or file names or file like handles such as io.StringIO to table definition in IVOA VOTable format.

    Examples

        >>> uploads = {'tmptable': '/tmp/tmptable_def.xml'}
        >>> rslt = query_tap(self, query, maxrec=None, uploads=uploads)

  retrieve_data_from_uid(uids, *, cache=True)

    Stage & Download ALMA data. Will print out the expected file size before attempting the download.

    Parameters:
      uids list or str

        A list of valid UIDs or a single UID. UIDs should have the form: ‘uid://A002/X391d0b/X7b’

      cache bool

        Whether to cache the downloads.

    Returns:
      downloaded_files list

        A list of the downloaded file paths