Online queries

It is possible to query online databases and automatically return the results as a Table instance. There are several mechanisms for accessing online catalogs:

Virtual Observatory

An interface to the virtual observatory is provided via the vo module. To list the catalogs available, use the list_catalogs() method from atpy.vo_conesearch:

>>> from atpy.vo_conesearch import list_catalogs
>>> list_catalogs()
           USNO-A2
           USNO-B1
        USNO NOMAD
          USNO ACT

A specific catalog can then be queried with a conesearch by specifying a catalog, and the coordinates and radius (in degrees) to search:

>>> t = atpy.Table(catalog='USNO-B1', ra=233.112, dec=23.432, radius=0.3, type='vo_conesearch')

How long this query takes will depend on the speed of your network, the load on the server being queried, and the number of rows in the result. For advanced users, it is also possible to query catalogs not listed by list_catalogs() - for more details, see the Full API for advanced users.

IRSA Query

In addition to supporting Virtual Observatory queries, ATpy supports queries to the NASA/IPAC Infrared Science Archive (IRSA). The interface is similar to that of the VO. To list the catalogs available, use the list_catalogs() method from atpy.irsa_service:

>>> from atpy.irsa_service import list_catalogs
>>> list_catalogs()
            fp_psc  2MASS All-Sky Point Source Catalog (PSC)
            fp_xsc  2MASS All-Sky Extended Source Catalog (XSC)
            lga_v2  The 2MASS Large Galaxy Atlas
       fp_scan_dat  2MASS All-Sky Survey Scan Info
               ...  ...

The first column is the catalog code used in the query. A specific catalog can then be queried by specifying a query type, a catalog, and additional arguments as required. The different kinds of search are:

• Cone: This is a cone search. Requires objstr, a string containing either coordinates or an object name (see here for more information), and radius, with units given by units ('arcsec' by default). For example:

  >>> t = atpy.Table('Cone', 'fp_psc', objstr='m13', \
                     radius=100., type='irsa')
  

• Box: This is a box search. Requires objstr, a string containing either coordinates or an object name (see here for more information), and size in arcseconds. For example:

  >>> t = atpy.Table('Box', 'fp_psc', objstr='T Tau', \
                     size=200., units='deg', type='irsa')
  

• Polygon: This is a polygon search. Requires polygon, which should be a list of tuples of (ra, dec) in decimal degrees:

  >>> t = atpy.Table('polygon','fp_psc', \
                     polygon=[(11.0, 45.0), (12.0, 45.0), (11.5, 46.)], \
                     type='irsa')
  

As for the VO query, how long these queries takes will depend on the speed of your network, the load on the IRSA server, and the number of rows in the result.

Full API for advanced users

Note

The following functions should not be called directly - the arguments should be passed to Table()/Table.read() using either type=vo_conesearch or type=irsa.

atpy.vo_conesearch.read(self, catalog=None, ra=None, dec=None, radius=None, verb=1, pedantic=False, **kwargs)

Query a VO catalog using the STScI vo module

This docstring has been adapted from the STScI vo conesearch module:

catalog [ None | string | VOSCatalog | list ]

May be one of the following, in order from easiest to use to most control:

• None: A database of conesearch catalogs is downloaded from STScI. The first catalog in the database to successfully return a result is used.
• catalog name: A name in the database of conesearch catalogs at STScI is used. For a list of acceptable names, see vo_conesearch.list_catalogs().
• url: The prefix of a url to a IVOA Cone Search Service. Must end in either ? or &.
• A VOSCatalog instance: A specific catalog manually downloaded and selected from the database using the APIs in the STScI vo.vos_catalog module.
• Any of the above 3 options combined in a list, in which case they are tried in order.

pedantic [ bool ]

When pedantic is True, raise an error when the returned VOTable file violates the spec, otherwise issue a warning.

ra [ float ]

A right-ascension in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees.

dec [ float ]

A declination in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees.

radius [ float]

The radius of the cone to search, given in decimal degrees.

verb [ int ]

Verbosity, 1, 2, or 3, indicating how many columns are to be returned in the resulting table. Support for this parameter by a Cone Search service implementation is optional. If the service supports the parameter, then when the value is 1, the response should include the bare minimum of columns that the provider considers useful in describing the returned objects. When the value is 3, the service should return all of the columns that are available for describing the objects. A value of 2 is intended for requesting a medium number of columns between the minimum and maximum (inclusive) that are considered by the provider to most typically useful to the user. When the verb parameter is not provided, the server should respond as if verb = 2. If the verb parameter is not supported by the service, the service should ignore the parameter and should always return the same columns for every request.

Additional keyword arguments may be provided to pass along to the server. These arguments are specific to the particular catalog being queried.

atpy.irsa_service.read(self, spatial, catalog, objstr=None, radius=None, units='arcsec', size=None, polygon=None)

Query the NASA/IPAC Infrared Science Archive (IRSA)

Required Arguments:

spatial [ ‘Cone’ | ‘Box’ | ‘Polygon’ ]

The type of query to execute

catalog [ string ]

One of the catalogs listed by atpy.irsa_service.list_catalogs()

Optional Keyword Arguments:

objstr [ str ]

This string gives the position of the center of the cone or box if performing a cone or box search. The string can give coordinates in various coordinate systems, or the name of a source that will be resolved on the server (see here for more details). Required if spatial is ‘Cone’ or ‘Box’.

radius [ float ]

The radius for the cone search. Required if spatial is ‘Cone’

units [ ‘arcsec’ | ‘arcmin’ | ‘deg’ ]

The units for the cone search radius. Defaults to ‘arcsec’.

size [ float ]

The size of the box to search in arcseconds. Required if spatial is ‘Box’.

polygon [ list of tuples ]

The list of (ra, dec) pairs, in decimal degrees, outlinining the polygon to search in. Required if spatial is ‘Polygon’