astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- CADC (`astroquery.cadc`) »
- CadcClass

# CadcClass

class astroquery.cadc.CadcClass(*, url=None, auth_session=None)

  Bases: `BaseVOQuery`, `BaseQuery`

  Class for accessing CADC data. Typical usage:

  result = Cadc.query_region(‘08h45m07.5s +54d18m00s’, collection=’CFHT’)

  … do something with result (optional) such as filter as in example below

  urls = Cadc.get_data_urls(result[result[‘target_name’]==’Nr3491_1’])

  … access data

  Other ways to query the CADC data storage:

  - target name:

      Cadc.query_region(SkyCoord.from_name(‘M31’))

  - target name in the metadata:

      Cadc.query_name(‘M31-A-6’) # queries as a like ‘%lower(name)%’

  - TAP query on the CADC metadata (CAOM2 format -

      http://www.opencadc.org/caom2/) Cadc.get_tables() # list the tables Cadc.get_table(table_name) # list table schema Cadc.query

  Initialize Cadc object

  Parameters:
    url str, optional, default ‘None;

      a url to use instead of the default

    auth_session: `requests.Session` or `pyvo.auth.authsession.AuthSession`

      A existing authenticated session containing the appropriate credentials to be used by the client to communicate with the server. This is an alternative to using login/logout methods that allows clients to reuse existing session with multiple services.

    Returns
    ——-
    Cadc object

  Attributes Summary

  `CADCDATALINK_SERVICE_URI` |
  `CADCLOGIN_SERVICE_URI` |
  `CADCTAP_SERVICE_URI` |
  `CADC_REGISTRY_URL` |
  `TIMEOUT` |
  `cadcdatalink` |
  `cadctap` |
  `data_link_url` |

  Methods Summary

  `create`(*args, **kwargs) | Queries the service and returns a table object.
  `create_async`(query, *[, maxrec, uploads]) | Creates a TAP job to execute and returns it to the caller.
  `exec_sync`(query, *[, maxrec, uploads, ...]) | Run a query and return the results or save them in an output_file
  `get_collections`() | Query CADC for all the hosted collections
  `get_data_urls`(query_result, *[, ...]) | Function to map the results of a CADC query into URLs to corresponding data that can be later downloaded.
  `get_image_list`(query_result, coordinates, radius) | Function to map the results of a CADC query into URLs to corresponding data and cutouts that can be later downloaded.
  `get_images`(coordinates, radius, *[, ...]) | A coordinate-based query function that returns a list of fits files with cutouts around the passed in coordinates.
  `get_images_async`(coordinates, radius, *[, ...]) | A coordinate-based query function that returns a list of context managers with cutouts around the passed in coordinates.
  `get_table`(table) | Gets the specified table
  `get_tables`(*[, only_names]) | Gets all public tables
  `list_async_jobs`(*[, phases, after, last, ...]) | Returns all the asynchronous jobs
  `list_jobs`(*args, **kwargs) | Queries the service and returns a table object.
  `load_async_job`(jobid) | Loads an asynchronous job
  `load_job`(*args, **kwargs) | Queries the service and returns a table object.
  `login`(*[, user, password, certificate_file]) | login allows user to authenticate to the service.
  `logout`() | Logout.
  `query_name`(*args, **kwargs) | Queries the service and returns a table object.
  `query_name_async`(name) | Query CADC metadata for a name and return the corresponding metadata in
  `query_region`(*args, **kwargs) | Queries the service and returns a table object.
  `query_region_async`(coordinates, *[, radius, ...]) | Queries the CADC for a region around the specified coordinates.

  Attributes Documentation

  CADCDATALINK_SERVICE_URI = 'ivo://cadc.nrc.ca/caom2ops'
  CADCLOGIN_SERVICE_URI = 'ivo://cadc.nrc.ca/gms'
  CADCTAP_SERVICE_URI = 'ivo://cadc.nrc.ca/argus'
  CADC_REGISTRY_URL = 'http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/reg/resource-caps'
  TIMEOUT = 30
  cadcdatalink
  cadctap
  data_link_url

  Methods Documentation

  create(*args, **kwargs)

    Queries the service and returns a table object.

    Creates a TAP job to execute and returns it to the caller. The caller then can start the execution and monitor the job. Typical (no error handling) sequence of events:

    > job = create_async(query) job = job.run().wait() job.raise_if_error() result = job.fetch_result() job.delete() # optional

    See `pyvo.dal.tap` for details about the `AsyncTAPJob`

    Parameters:
      query str, mandatory

        SQL to execute

      maxrec int

        the maximum records to return. defaults to the service default

      uploads:

        Temporary tables to upload and run with the queries

      output_file: str or file handler:

        File to save the results to

    Returns:
      table A `Table` object.

    Notes

    Support for other output formats (tsv, csv) to be added as soon as they are available in pyvo.

  create_async(query, *, maxrec=None, uploads=None)

    Creates a TAP job to execute and returns it to the caller. The caller then can start the execution and monitor the job. Typical (no error handling) sequence of events:

    > job = create_async(query) job = job.run().wait() job.raise_if_error() result = job.fetch_result() job.delete() # optional

    See `pyvo.dal.tap` for details about the `AsyncTAPJob`

    Parameters:
      query str, mandatory

        SQL to execute

      maxrec int

        the maximum records to return. defaults to the service default

      uploads:

        Temporary tables to upload and run with the queries

      output_file: str or file handler:

        File to save the results to

    Returns:
      AsyncTAPJob

        the query instance

    Notes

    Support for other output formats (tsv, csv) to be added as soon as they are available in pyvo.

  exec_sync(query, *, maxrec=None, uploads=None, output_file=None, output_format='votable')

    Run a query and return the results or save them in an output_file

    Parameters:
      query str, mandatory

        SQL to execute

      maxrec int

        the maximum records to return. defaults to the service default

      uploads

        Temporary tables to upload and run with the queries

      output_file str, Path, or file handler

        File to save the results to

      output_format

        Format of the output (default is basic). Must be one of the formats supported by `astropy.table`

    Returns:
      Results of running the query in (for now) votable format

    Notes

    Support for other output formats (tsv, csv) to be added as soon as they are available in pyvo.

  get_collections()

    Query CADC for all the hosted collections

    Returns:
      A dictionary of collections hosted at the CADC where the key is the
      collection and value represents details of that collection.
  get_data_urls(query_result, *, include_auxiliaries=False)

    Function to map the results of a CADC query into URLs to corresponding data that can be later downloaded.

    The function uses the IVOA DataLink Service (http://www.ivoa.net/documents/DataLink/) implemented at the CADC. It works directly with the results produced by `query_region` and `query_name` but in principle it can work with other query results produced with the Cadc query as long as the results contain the ‘publisherID’ column. This column is part of the ‘caom2.Plane’ table.

    Parameters:
      query_result A `Table` object

        Result returned by `query_region` or `query_name`. In general, the result of any CADC TAP query that contains the ‘publisherID’ column can be use here.

      include_auxiliaries boolean

        `True` to return URLs to auxiliary files such as previews, `False` otherwise

    Returns:
      A list of URLs to data.
  get_image_list(query_result, coordinates, radius)

    Function to map the results of a CADC query into URLs to corresponding data and cutouts that can be later downloaded.

    The function uses the IVOA DataLink Service (http://www.ivoa.net/documents/DataLink/) implemented at the CADC. It works directly with the results produced by `query_region` and `query_name` but in principle it can work with other query results produced with the Cadc query as long as the results contain the ‘publisherID’ column. This column is part of the ‘caom2.Plane’ table.

    Parameters:
      query_result A `Table` object

        Result returned by `query_region` or `query_name`. In general, the result of any CADC TAP query that contains the ‘publisherID’ column can be used here.

      coordinates str or `astropy.coordinates`.

        Center of the cutout area.

      radius str or `astropy.units.Quantity`.

        The radius of the cutout area.

    Returns:
      list A list of URLs to cutout data.
  get_images(coordinates, radius, *, collection=None, get_url_list=False, show_progress=False)

    A coordinate-based query function that returns a list of fits files with cutouts around the passed in coordinates.

    Parameters:
      coordinates str or `astropy.coordinates`.

        Coordinates around which to query.

      radius str or `astropy.units.Quantity`

        The radius of the cone search AND cutout area.

      collection str, optional

        Name of the CADC collection to query.

      get_url_list bool, optional

        If `True`, returns the list of data urls rather than the downloaded FITS files. Default is `False`.

      show_progress bool, optional

        Whether to display a progress bar if the file is downloaded from a remote server. Default is `False`.

    Returns:
      list A list of `HDUList` objects (or a list of
      str if returning urls).
  get_images_async(coordinates, radius, *, collection=None, get_url_list=False, show_progress=False)

    A coordinate-based query function that returns a list of context managers with cutouts around the passed in coordinates.

    Parameters:
      coordinates str or `astropy.coordinates`.

        Coordinates around which to query.

      radius str or `astropy.units.Quantity`

        The radius of the cone search AND cutout area.

      collection str, optional

        Name of the CADC collection to query.

      get_url_list bool, optional

        If `True`, returns the list of data urls rather than the list of context managers. Default is `False`.

      show_progress bool, optional

        Whether to display a progress bar if the file is downloaded from a remote server. Default is `False`.

    Returns:
      list A list of context-managers that yield readable file-like objects
  get_table(table)

    Gets the specified table

    Parameters:
      table str, mandatory

        full qualified table name (i.e. schema name + table name)

    Returns:
      A table object
  get_tables(*, only_names=False)

    Gets all public tables

    Parameters:
      only_names bool, optional, default False

        True to load table names only

    Returns:
      A list of table objects
  list_async_jobs(*, phases=None, after=None, last=None, short_description=True)

    Returns all the asynchronous jobs

    Parameters:
      phases list of str

        Union of job phases to filter the results by.

      after datetime

        Return only jobs created after this datetime

      last int

        Return only the most recent number of jobs

      short_description flag - True or False

        If True, the jobs in the list will contain only the information corresponding to the TAP ShortJobDescription object (job ID, phase, run ID, owner ID and creation ID) whereas if False, a separate GET call to each job is performed for the complete job description

    Returns:
      A list of Job objects
  list_jobs(*args, **kwargs)

    Queries the service and returns a table object.

    Returns all the asynchronous jobs

    Parameters:
      phases list of str

        Union of job phases to filter the results by.

      after datetime

        Return only jobs created after this datetime

      last int

        Return only the most recent number of jobs

      short_description flag - True or False

        If True, the jobs in the list will contain only the information corresponding to the TAP ShortJobDescription object (job ID, phase, run ID, owner ID and creation ID) whereas if False, a separate GET call to each job is performed for the complete job description

    Returns:
      table A `Table` object.
  load_async_job(jobid)

    Loads an asynchronous job

    Parameters:
      jobid str, mandatory

        job identifier

    Returns:
      A Job object
  load_job(*args, **kwargs)

    Queries the service and returns a table object.

    Loads an asynchronous job

    Parameters:
      jobid str, mandatory

        job identifier

    Returns:
      table A `Table` object.
  login(*, user=None, password=None, certificate_file=None)

    login allows user to authenticate to the service. Both user/password and https client certificates are supported.

    > Alternatively, the Cadc class can be instantiated with an authenticated session.

    Parameters:
      user str, required if certificate is None

        username to login with

      password str, required if user is set

        password to login with

      certificate str, required if user is None

        path to certificate to use with logging in

  logout()

    Logout. Anonymous access with all the subsequent use of the object. Note that the original session is not affected (in case it was passed when the object was first instantiated)

  query_name(*args, **kwargs)

    Queries the service and returns a table object.

    Query CADC metadata for a name and return the corresponding metadata in

      the CAOM2 format (http://www.opencadc.org/caom2/).

    Parameters:
      name str

        name of object to query for

    Returns:
      table A `Table` object.
  query_name_async(name)
    Query CADC metadata for a name and return the corresponding metadata in

      the CAOM2 format (http://www.opencadc.org/caom2/).

    Parameters:
      name str

        name of object to query for

    Returns:
      response `Table`

        Results of the query in a tabular format.

  query_region(*args, **kwargs)

    Queries the service and returns a table object.

    Queries the CADC for a region around the specified coordinates.

    Parameters:
      coordinates str or `astropy.coordinates`.

        coordinates around which to query

      radius str or `astropy.units.Quantity`.

        the radius of the cone search

      collection: Name of the CADC collection to query, optional
      get_query_payload bool, optional

        Just return the dict of HTTP request parameters.

    Returns:
      table A `Table` object.
  query_region_async(coordinates, *, radius=<Quantity 0.01666667 deg>, collection=None, get_query_payload=False)

    Queries the CADC for a region around the specified coordinates.

    Parameters:
      coordinates str or `astropy.coordinates`.

        coordinates around which to query

      radius str or `astropy.units.Quantity`.

        the radius of the cone search

      collection: Name of the CADC collection to query, optional
      get_query_payload bool, optional

        Just return the dict of HTTP request parameters.

    Returns:
      response `requests.Response`

        The HTTP response returned from the service. All async methods should return the raw HTTP response.