Astroquery¶
This is the documentation for the Astroquery coordinated package of astropy.
Code and issue tracker are on GitHub.
If you use astroquery, please cite the paper Ginsburg, Sipőcz, Brasseur et al 2019.
Introduction¶
Astroquery is a set of tools for querying astronomical web forms and databases.
There are two other packages with complimentary functionality as Astroquery: pyvo is an Astropy affiliated package, and Simple-Cone-Search-Creator to generate a cone search service complying with the IVOA standard. They are more oriented to general virtual observatory discovery and queries, whereas Astroquery has web service specific interfaces.
Check out the A Gallery of Queries for some nice examples.
Installation¶
Uniquely in the Astropy ecosystem, Astroquery is operating with a continuous deployment model.
It means that a release is instantaneously available after a pull request has been merged. These
releases are automatically uploaded to PyPI,
and therefore the latest version of astroquery can be pip installed.
The version number of these automated releases contain the 'dev'
tag, thus pip needs to be told
to look for these releases during an upgrade, using the --pre
install option. If astroquery is
already installed, please make sure you use the --upgrade
install option as well.
$ pip install --pre astroquery
In addition to the automated releases, we also keep doing regular, tagged version for maintenance
and packaging purposes. These can be pip
installed without the --pre
option and
are available from the conda-forge
conda channel.
$ conda install -c conda-forge astroquery
To review recent changes and fixes, please have a look at the changelog:
Building from source¶
The development version can be obtained and installed from github:
$ # If you have a github account:
$ git clone git@github.com:astropy/astroquery.git
$ # If you do not:
$ git clone https://github.com/astropy/astroquery.git
$ cd astroquery
$ python setup.py install
Requirements¶
Astroquery works with Python 3.7 or later.
The following packages are required for astroquery installation & use:
and for running the tests:
The following packages are optional dependencies and are required for the
full functionality of the alma
module:
The following packages are optional dependencies and are required for the
full functionality of the cds
module:
mocpy >= 0.5.2
vamdclib install version from personal fork:
pip install git+https://github.com/keflavich/vamdclib-1.git
The following packages are optional dependencies and are required for the
full functionality of the mast
module:
Using astroquery¶
All astroquery modules are supposed to follow the same API. In its simplest form, the API involves queries based on coordinates or object names. Some simple examples, using SIMBAD:
>>> from astroquery.simbad import Simbad
>>> result_table = Simbad.query_object("m1")
>>> result_table.pprint(show_unit=True)
MAIN_ID RA DEC RA_PREC ... COO_QUAL COO_WAVELENGTH COO_BIBCODE
"h:m:s" "d:m:s" ...
------- ----------- ----------- ------- ... -------- -------------- -------------------
M 1 05 34 31.94 +22 00 52.2 6 ... C R 2011A&A...533A..10L
All query tools allow coordinate-based queries:
>>> from astropy import coordinates
>>> import astropy.units as u
>>> # works only for ICRS coordinates:
>>> c = coordinates.SkyCoord("05h35m17.3s -05d23m28s", frame='icrs')
>>> r = 5 * u.arcminute
>>> result_table = Simbad.query_region(c, radius=r)
>>> result_table.pprint(show_unit=True, max_width=80, max_lines=5)
MAIN_ID RA DEC ... COO_WAVELENGTH COO_BIBCODE
"h:m:s" "d:m:s" ...
------------ ------------ ------------ ... -------------- -------------------
M 42 05 35 17.3 -05 23 28 ... 1981MNRAS.194..693L
... ... ... ... ... ...
V* V2114 Ori 05 35 01.671 -05 26 36.30 ... I 2003yCat.2246....0C
For additional guidance and examples, read the documentation for the individual services below.
Default configuration file¶
To customize this, copy the default configuration to $HOME/.astropy/config/astroquery.cfg
,
uncomment the relevant configuration item(s), and insert your desired value(s).
Available Services¶
If you’re new to Astroquery, a good place to start is the A Gallery of Queries:
The following modules have been completed using a common API:
- ALMA Queries (
astroquery.alma
) - Atomic Line List (
astroquery.atomic
) - Besancon Queries (
astroquery.besancon
) - Cadc (
astroquery.cadc
) - CASDA Queries (
astroquery.casda
) - CDS MOC Service (
astroquery.cds
) - esa.hubble (
astroquery.esa.hubble
) - ESA ISO Archive (
astroquery.esa.iso
) - JWST TAP+ (
astroquery.esa.jwst
) - xmm_newton (
astroquery.esa.xmm_newton
) - ESASky Queries (
astroquery.esasky
) - ESO Queries (
astroquery.eso
) - Gaia TAP+ (
astroquery.gaia
) - GAMA Queries (
astroquery.gama
) - Gemini Queries (
astroquery.gemini
) - HEASARC Queries (
astroquery.heasarc
) - HiPS2fits Service (
astroquery.hips2fits
) - HITRAN Queries (
astroquery.hitran
) - IRSA Image Server program interface (IBE) Queries (
astroquery.ipac.irsa.ibe
) - IRSA Queries (
astroquery.ipac.irsa
) - IRSA Dust Extinction Service Queries (
astroquery.ipac.irsa.irsa_dust
) - JPL Spectroscopy Queries (astroquery.jplspec)
- Cologne Database for Molecular Spectroscopy (CDMS) Queries (
astroquery.linelists.cdms
) - MAGPIS Queries (
astroquery.magpis
) - MAST Queries (
astroquery.mast
) - Minor Planet Center Queries (
astroquery.mpc
/astroquery.solarsystem.MPC) - NASA ADS Queries (
astroquery.nasa_ads
) - NED Queries (
astroquery.ipac.ned
) - NIST Queries (
astroquery.nist
) - NOIRLab Queries (
astroquery.noirlab
) - NRAO Queries (
astroquery.nrao
) - NVAS Queries (
astroquery.nvas
) - SIMBAD Queries (
astroquery.simbad
) - Skyview Queries (
astroquery.skyview
) - Splatalogue Queries (
astroquery.splatalogue
) - SVO Filter Profile Service Queries (
astroquery.svo_fps
) - UKIDSS Queries (
astroquery.ukidss
) - Vamdc Queries (
astroquery.vamdc
) - VizieR Queries (
astroquery.vizier
) - VO Simple Cone Search (
astroquery.vo_conesearch
) - VSA Queries (
astroquery.vsa
) - xMatch Queries (
astroquery.xmatch
) - DACE (
astroquery.dace
)
These others are functional, but do not follow a common & consistent API:
- ALFALFA Queries (
astroquery.alfalfa
) - CosmoSim Queries (
astroquery.cosmosim
) - Exoplanet Orbit Database (
astroquery.exoplanet_orbit_database
) - Fermi Queries (
astroquery.fermi
) - JPL Horizons Queries (
astroquery.jplhorizons
/astroquery.solarsystem.jpl.horizons) - JPL SBDB Queries (
astroquery.jplsbdb
/astroquery.solarsystem.jpl.sbdb) - LAMDA Queries (
astroquery.lamda
) - NASA Exoplanet Archive (
astroquery.ipac.nexsci.nasa_exoplanet_archive
) - OAC API Queries (
astroquery.oac
) - OGLE Queries (
astroquery.ogle
) - Open Exoplanet Catalogue(
astroquery.open_exoplanet_catalogue
) - SDSS Queries (
astroquery.sdss
) - Spitzer Heritage Archive (
astroquery.ipac.irsa.sha
)
There are also subpackages that serve as the basis of others.
Catalog, Archive, and Other¶
A second index of the services by the type of data they serve. Some services perform many tasks and are listed more than once.
Catalogs¶
The first serve catalogs, which generally return one row of information for each source (though they may return many catalogs that each have one row for each source)
- ALFALFA Queries (
astroquery.alfalfa
) - Exoplanet Orbit Database (
astroquery.exoplanet_orbit_database
) - GAMA Queries (
astroquery.gama
) - IRSA Image Server program interface (IBE) Queries (
astroquery.ipac.irsa.ibe
) - IRSA Queries (
astroquery.ipac.irsa
) - IRSA Dust Extinction Service Queries (
astroquery.ipac.irsa.irsa_dust
) - MAST Queries (
astroquery.mast
) - NASA Exoplanet Archive (
astroquery.ipac.nexsci.nasa_exoplanet_archive
) - NED Queries (
astroquery.ipac.ned
) - OGLE Queries (
astroquery.ogle
) - Open Exoplanet Catalogue(
astroquery.open_exoplanet_catalogue
) - SDSS Queries (
astroquery.sdss
) - Spitzer Heritage Archive (
astroquery.ipac.irsa.sha
) - SIMBAD Queries (
astroquery.simbad
) - UKIDSS Queries (
astroquery.ukidss
) - VSA Queries (
astroquery.vsa
) - VizieR Queries (
astroquery.vizier
) - xMatch Queries (
astroquery.xmatch
) - VO Simple Cone Search (
astroquery.vo_conesearch
)
Archives¶
Archive services provide data, usually in FITS images or spectra. They will generally return a table listing the available data first.
- ALFALFA Queries (
astroquery.alfalfa
) - ALMA Queries (
astroquery.alma
) - Cadc (
astroquery.cadc
) - CASDA Queries (
astroquery.casda
) - esa.hubble (
astroquery.esa.hubble
) - JWST TAP+ (
astroquery.esa.jwst
) - ESO Queries (
astroquery.eso
) - Fermi Queries (
astroquery.fermi
) - Gaia TAP+ (
astroquery.gaia
) - HEASARC Queries (
astroquery.heasarc
) - IRSA Image Server program interface (IBE) Queries (
astroquery.ipac.irsa.ibe
) - IRSA Queries (
astroquery.ipac.irsa
) - MAGPIS Queries (
astroquery.magpis
) - Gemini Queries (
astroquery.gemini
) - MAST Queries (
astroquery.mast
) - NED Queries (
astroquery.ipac.ned
) - NOIRLab Queries (
astroquery.noirlab
) - NRAO Queries (
astroquery.nrao
) - NVAS Queries (
astroquery.nvas
) - SDSS Queries (
astroquery.sdss
) - Spitzer Heritage Archive (
astroquery.ipac.irsa.sha
) - UKIDSS Queries (
astroquery.ukidss
) - VSA Queries (
astroquery.vsa
) - Skyview Queries (
astroquery.skyview
) - xmm_newton (
astroquery.esa.xmm_newton
)
Simulations¶
These services query databases of simulated or synthetic data:
Line List Services¶
There are several web services that provide atomic or molecular line lists, as well as cross section and collision rates. Those services are:
- Atomic Line List (
astroquery.atomic
) - LAMDA Queries (
astroquery.lamda
) - NIST Queries (
astroquery.nist
) - Splatalogue Queries (
astroquery.splatalogue
) - Vamdc Queries (
astroquery.vamdc
) - HITRAN Queries (
astroquery.hitran
) - Cologne Database for Molecular Spectroscopy (CDMS) Queries (
astroquery.linelists.cdms
) - JPL Spectroscopy Queries (astroquery.jplspec)
Other¶
There are other astronomically significant services, that don’t fit the above categories. Those services are here:
- NASA ADS Queries (
astroquery.nasa_ads
) - TAP/TAP+ (
astroquery.utils.tap
) - JPL Horizons Queries (
astroquery.jplhorizons
/astroquery.solarsystem.jpl.horizons) - JPL SBDB Queries (
astroquery.jplsbdb
/astroquery.solarsystem.jpl.sbdb) - Institut de Mécanique Céleste et de Calcul des Éphémérides (IMCCE) Solar System Services (
astroquery.imcce
/astroquery.solarsystem.imcce) - Astrometry.net plate solutions (
astroquery.astrometry_net
)
Topical Collections¶
Some services focusing on similar topics are also collected in topical submodules:
Developer documentation¶
The modules and their maintainers are listed on the Maintainers wiki page.
The Astroquery API Specification is intended to be kept as consistent as possible, such that any web service can be used with a minimal learning curve imposed on the user.
The following Astroquery modules are mostly meant for internal use of services in Astroquery, you can use them for your scripts, but we don’t guarantee API stability.
To debug astroquery, logging level can be configured with the following:
>>> from astroquery import log
>>> log.setLevel(level)
If level
is set to "DEBUG"
, then HTTP requests are logged.
If level
is set to "TRACE"
, then HTTP requests and responses are logged.
License¶
Astroquery is licensed under a 3-clause BSD style license - see Licenses.