HEASARC Queries (astroquery.heasarc)¶
Getting started¶
This is a python interface for querying the HEASARC archive web service.
The main interface for the Heasarc services heasarc.Heasarc uses
Virtual Observatory protocols, which offer powerful archive search options.
Heasarc Main Interface¶
Query a Catalog¶
The basic use case is one where we want to query a catalog from some position in the sky.
In this example, we query the NuSTAR master catalog numaster for all observations
of the AGN NGC 3783. We use SkyCoord to obtain the coordinates
and then pass them to query_region. In the following, we
also select only columns with time > 0. Zero values are typically used for observations
that have been approved but not observed.
>>> from astroquery.heasarc import Heasarc
>>> from astropy.coordinates import SkyCoord
>>> pos = SkyCoord.from_name('ngc 3783')
>>> tab = Heasarc.query_region(pos, catalog='numaster')
>>> tab = tab[tab['time'] > 0]
>>> tab.sort('time')
>>> tab['name', 'obsid', 'ra', 'dec'][:3].pprint()
name obsid ra dec
deg deg
-------- ----------- -------- --------
NGC_3783 60101110002 174.7236 -37.7230
NGC_3783 60101110004 174.7253 -37.7277
NGC_3783 80202006002 174.7838 -37.7277
To query a region around some position, specifying the search radius,
we use Quantity:
>>> from astroquery.heasarc import Heasarc
>>> from astropy.coordinates import SkyCoord
>>> from astropy import units as u
>>> pos = SkyCoord('120 38', unit=u.deg)
>>> tab = Heasarc.query_region(pos, catalog='chanmaster', radius=2*u.deg)
>>> tab.sort('time')
>>> tab['name', 'obsid', 'ra', 'dec'][:5].pprint(align='<')
name obsid ra dec
deg deg
------------------------- ----- --------- --------
B2 0755+37 858 119.61750 37.78667
ABELL 611 3194 120.23708 36.05722
1RXS J075526.1+391111 13008 118.85875 39.18639
SDSS J080040.77+391700.5 18110 120.17000 39.28344
WISEA J080357.73+390823.1 28213 120.99060 39.13980
If no radius value is given, a default that is appropriate
for each catalog is used. You can see the value of the default
radius values by calling get_default_radius,
passing the name of the catalog.
The list of returned columns can also be given as a comma-separated string to
query_region:
>>> from astroquery.heasarc import Heasarc
>>> from astropy.coordinates import SkyCoord
>>> from astropy import units as u
>>> pos = SkyCoord('120 38', unit=u.deg)
>>> tab = Heasarc.query_region(pos, catalog='chanmaster', radius=2*u.deg,
... columns='obsid, name, time, pi')
>>> tab[:5].pprint()
obsid name time pi
d
----- ------------------------- ---------------- -------
3194 ABELL 611 52216.7805324074 Allen
858 B2 0755+37 51637.0090740741 Worrall
28213 WISEA J080357.73+390823.1 60315.9524768519 Pooley
29168 WISEA J080357.73+390823.1 60316.2761805556 Pooley
13008 1RXS J075526.1+391111 55536.6453587963 Liu
If no columns are given, the call will return a set of default columns.
If you want all the columns returned, use columns='*'
To add a search offset column that gives the angular distance in arcminutes
between the query position and the positions in the catalog,
use the add_offset=True:
To do a full sky search, use spatial='all-sky':
>>> from astroquery.heasarc import Heasarc
>>> tab = Heasarc.query_region(catalog='chanmaster', spatial='all-sky',
... columns='name, obsid, ra, dec')
>>> tab[:5].pprint()
name obsid ra dec
deg deg
-------------------- ----- --------- ---------
ESO005-G004 21421 91.42333 -86.63194
1RXSJ200924.1-853911 10143 302.30417 -85.64633
RE J0317-853 22326 49.31604 -85.54043
ACO 4023 15124 354.93333 -85.17583
GRB020321 3477 242.76000 -83.70000
List Available Catalogs¶
The collection of available catalogs can be obtained by calling the list_catalogs
method. In this example, we request the master catalogs only by passing master=True.
Master catalogs are catalogs that contain one entry per observation, as opposed to
other catalogs that may record other information. There is typically one master catalog
per mission. The master parameter is a boolean flag, which is False by default
(i.e. return all catalogs). list_catalogs returns an
Table with two columns containing the names and description of the available
catalogs.
>>> from astroquery.heasarc import Heasarc
>>> catalogs = Heasarc.list_catalogs(master=True)
>>> catalogs.pprint(align='<')
name description
---------- -------------------------------------------------------------
ascamaster ASCA Master Catalog
burcbmastr BurstCube Master Observation Catalog
chanmaster Chandra Observations
...
If you do not know the name of the catalog you are looking for, you can use the keywords
parameter in list_catalogs. For example, if you want to find all catalogs that
are related to Chandra, you can do:
>>> from astroquery.heasarc import Heasarc
>>> catalogs = Heasarc.list_catalogs(keywords='chandra')
>>> # list the first 10
>>> catalogs[:10].pprint()
name description
---------- ----------------------------------------------------------------
acceptcat Archive of Chandra Cluster Entropy Profile Tables (ACCEPT) Catal
aegisx AEGIS-X Chandra Extended Groth Strip X-Ray Point Source Catalog
aegisxdcxo AEGIS-X Deep Survey Chandra X-Ray Point Source Catalog
aknepdfcxo Akari North Ecliptic Pole Deep Field Chandra X-Ray Point Source
arcquincxo Arches and Quintuplet Clusters Chandra X-Ray Point Source Catalo
atcdfsss82 Australia Telescope Chandra Deep Field-South and SDSS Stripe 82
bmwchancat Brera Multi-scale Wavelet Chandra Source Catalog
candelscxo CANDELS H-Band Selected Chandra Source Catalog
cargm31cxo Carina Nebula Gum 31 Chandra X-Ray Point Source Catalog
carinaclas Carina Nebula Chandra X-Ray Point Source Classes
If you are interested only finding the master catalogs only, you can set master to True.
>>> from astroquery.heasarc import Heasarc
>>> catalog = Heasarc.list_catalogs(keywords='chandra', master=True)
>>> catalog.pprint()
name description
---------- --------------------
chanmaster Chandra Observations
Multiple keywords that are separated by space are joined with AND, so the following finds all the catalogs that have both ‘xmm’ and ‘chandra’ keywords:
>>> from astroquery.heasarc import Heasarc
>>> catalog = Heasarc.list_catalogs(keywords='xmm chandra')
>>> catalog.pprint()
name description
---------- ----------------------------------------------------------------
gmrt1hxcsf Giant Metrewave Radio Telescope 1h XMM/Chandra Survey Fld 610-MH
ic10xmmcxo IC 10 XMM-Newton and Chandra X-Ray Point Source Catalog
ros13hrcxo ROSAT/XMM-Newton 13-hour Field Chandra X-Ray Source Catalog
xmmomcdfs XMM-Newton Optical Monitor Chandra Deep Field-South UV Catalog
If you want an OR relation between keywords, you can pass them in a list. The following for instance will find master catalogs that have keywords ‘nicer’ or ‘swift’
>>> from astroquery.heasarc import Heasarc
>>> catalog = Heasarc.list_catalogs(keywords=['nicer', 'swift'], master=True)
>>> catalog.pprint()
name description
---------- --------------------
nicermastr NICER Master Catalog
swiftmastr Swift Master Catalog
Adding Column Constraints¶
In addition to region search in query_region,
you can also pass other column constraints. This is done by passing a dictionary
to the column_filters parameter. The keys of the dictionary are the column names
and the values are the constraints. Exampels include:
- {'flux': (1e-12, 1e-10)} translates to a flux range.
- {'exposure': ('>', 10000)} translates to exposure greater than 10000.
- {'instrument': ['ACIS', 'HRC']} translates to a value in a list.
- {'obsid': '12345'} translates to obsid equal to 12345.
This allows you to query a catalog by specifying
various column constraints. For example, the following query searches the chanmaster
catalog for all observations with exposure time greater than 190 ks.
Note that when column filters are given and no position is specified, the search defaults to an all-sky search.
>>> from astroquery.heasarc import Heasarc
>>> tab = Heasarc.query_region(
... catalog='chanmaster', column_filters={'exposure': ('>', '190000')}
... )
>>> tab['name', 'obsid', 'ra', 'dec', 'exposure'][:3].pprint()
name obsid ra dec exposure
deg deg s
--------------- ----- --------- --------- --------
GW Transient 29852 -- -- 300000
Sgr A* 13842 266.41667 -29.00781 191760
IGR J17480-2446 30481 267.02013 -24.78024 200000
Another example may be to search the xmmmaster for a observation in some time range:
>>> from astroquery.heasarc import Heasarc
>>> tab = Heasarc.query_region(
... catalog='xmmmaster', column_filters={'time': (52300, 52310)}
... )
>>> tab['name', 'obsid', 'ra', 'dec', 'time', 'duration'][:3].pprint()
name obsid ra dec time duration
deg deg d s
------------- ---------- -------- --------- ---------------- --------
NGC 1316 0091770101 50.95833 -37.28333 52308.6872337963 60362
NGC 1316 0091770201 50.67296 -37.20928 52308.642974537 3462
Fei 16 offset 0154150101 28.64374 -6.86667 52305.2210416667 24619
To see the available columns that can be queried for a given catalog and their units,
use list_columns (see below).
Links to Data Products¶
Once the query result is obtained, you can query any data products associated with those results.
>>> from astroquery.heasarc import Heasarc
>>> from astropy.coordinates import SkyCoord
>>> pos = SkyCoord.from_name('ngc 3516')
>>> tab = Heasarc.query_region(pos, catalog='nicermastr')
>>> tab = tab[tab['exposure'] > 0]
>>> links = Heasarc.locate_data(tab[:2])
>>> links['access_url'].pprint()
access_url
---------------------------------------------------------------------
https://heasarc.gsfc.nasa.gov/FTP/nicer/data/obs/2025_01//7100120102/
https://heasarc.gsfc.nasa.gov/FTP/nicer/data/obs/2025_01//7100120101/
The links table has three relevant columns: access_url, sciserver and aws.
The first gives the url to the data from the main heasarc server. The second gives
the local path to the data on Sciserver. The last gives the S3 URI to the data in the cloud.
You can specify where the data are to be downloaded using the location parameter.
To download the data, you can pass links table (or row) to download_data,
specifying from where you want the data to be fetched by specifying the host parameter. By default,
the function will try to guess the best host based on your environment. If it cannot guess, then
the data is fetched from the main HEASARC servers.
The recommendation is to use different hosts depending on where your code is running:
* host='sciserver': Use this option if you running you analysis on Sciserver. Because
all the archive can be mounted locally there, download_data
will only copy the relevant data.
* host='aws': Use this option if you are running the analysis in Amazon Web Services (AWS).
Data will be downloaded from AWS S3 storage.
* host='heasarc': Use this option for other cases. This is the classical and most general option.
In this case, the requested data will be tarred and downloaded as a single file called heasarc-data.tar
before being untarred.
Advanced Queries¶
Behind the scenes, query_region constructs an query in the
Astronomical Data Query Language ADQL, which is powerful in constructing
complex queries. Passing get_query_payload=True to query_region
returns the constructed ADQL query.
>>> from astroquery.heasarc import Heasarc
>>> from astropy.coordinates import SkyCoord
>>> from astropy import units as u
>>> pos = SkyCoord('120 38', unit=u.deg)
>>> query = Heasarc.query_region(pos, catalog='xmmmaster', radius=2*u.deg,
... columns='*', get_query_payload=True)
>>> query
"SELECT * FROM xmmmaster WHERE CONTAINS(POINT('ICRS',ra,dec),CIRCLE('ICRS',120.0,38.0,2.0))=1"
>>> # The query can be modified and then submitted using:
>>> query = """SELECT ra,dec,name,obsid FROM xmmmaster
... WHERE CONTAINS(POINT('ICRS',ra,dec),CIRCLE('ICRS',120.0,38.0,2.0))=1"""
>>> tab = Heasarc.query_tap(query).to_table()
>>> tab[:10].pprint()
ra dec name obsid
deg deg
--------- -------- -------------------- ----------
120.22707 36.04139 Abell 611 0781590301
120.25583 36.04944 Abell 611 0781590501
120.23300 36.06100 A611 0605000601
120.21750 36.06500 Abell 611 0781590401
120.24624 36.07305 Abell 611 0781590201
120.39708 36.46875 RMJ080135.3+362807.5 0881901001
119.61710 37.78661 B2 0755+37 0602390101
121.92084 39.00417 UGC4229 0138950101
121.92084 39.00417 UGC4229 0138951401
121.92099 39.00422 MRK 622 0852180501
Table Uploads¶
You can also upload a table of positions to be queried. The table can be an
Table or a path to a file in VOtable format. The following example
shows how to use the upload feature to do a cross-match between the
chanmaster catalog and a list of known source positions:
>>> from astroquery.heasarc import Heasarc
>>> from astropy.table import Table
>>> sample = Table({
... 'ra': [1.58, 188.90],
... 'dec': [20.20, -39.90]
... })
>>> query = """
... SELECT cat.name, cat.ra, cat.dec, cat.obsid
... FROM chanmaster cat, tap_upload.mytable mt
... WHERE 1=CONTAINS(POINT('ICRS', mt.ra, mt.dec), CIRCLE('ICRS',cat.ra, cat.dec, 0.1))
... """
>>> result = Heasarc.query_tap(query, uploads={'mytable': sample}).to_table()
>>> result.pprint()
name ra dec obsid
deg deg
----------- --------- --------- -----
NGC 4507 188.90250 -39.90928 12292
NGC 4507 188.90208 -39.90925 2150
HR4796 189.00417 -39.86950 7414
KUG0003+199 1.58134 20.20291 23709
Mrk 335 1.58142 20.20295 23292
Mrk 335 1.58142 20.20295 23297
Mrk 335 1.58142 20.20295 23298
Mrk 335 1.58142 20.20295 23299
Mrk 335 1.58142 20.20295 23300
Mrk 335 1.58142 20.20295 23301
Mrk 335 1.58142 20.20295 23302
Complex Regions¶
In addition to a cone search (some position and search radius), `Heasarc.query_region` accepts
other options too, including 'box', 'polygon' and 'all-sky'. Details can be found
in query_region. Examples include:
>>> # query box region
>>> pos = SkyCoord('226.2 10.6', unit=u.deg)
>>> Heasarc.query_region(pos, catalog='xmmmaster', spatial='box', width=0.5*u.deg)
for 'box' and:
>>> Heasarc.query_region(catalog='xmmmaster', spatial='polygon',
polygon=[(226.2,10.6),(225.9,10.5),(225.8,10.2),(226.2,10.3)])
for 'polygon'. For 'all-sky':
>>> Heasarc.query_region(pos, spatial='all-sky', catalog='csc', maxrec=None)
though you may find that maxrec has a hard limit of 1e5 regardless of how you set it.
In this case one can do instead:
>>> # get a comma-separated list of the default columns in csc.
>>> columns = ', '.join(Heasarc._get_default_columns('csc'))
>>> # construct a query for all entries; use TOP with a large number greater than the server's 1e5 LIMIT
>>> query = f'SELECT TOP 9999999 {columns} FROM csc'
>>> Heasarc.query_tap(query).to_table()
List Catalog Columns¶
To list the columns of some catalog, use list_columns. Here we list the columns
in the XMM master catalog xmmmaster:
>>> from astroquery.heasarc import Heasarc
>>> columns = Heasarc.list_columns(catalog_name='suzamaster')
>>> columns.sort('name')
>>> columns[:10].pprint(align='<')
name description unit
--------------- ---------------------------------------- ------
dec Declination (Pointing Position) degree
exposure Effective Total Observation Exposure (s) s
name Designation of the Pointed Source
obsid Unique Observation/Sequence Number
processing_date Date of Processing mjd
public_date Public Date mjd
ra Right Ascension (Pointing Position) degree
Reference/API¶
astroquery.heasarc Package¶
HEASARC¶
The High Energy Astrophysics Science Archive Research Center (HEASARC) is the primary archive for NASA’s (and other space agencies’) missions.
Classes¶
Class for accessing HEASARC data with VO protocol using the Xamin backend. |
|
|
Configuration parameters for |