Skip to content

Commit 8ede150

Browse files
bsipoczbsipocz
authored
Merge pull request #3245 from bsipocz/DOC_update_irsa
DOC: update IRSA narrative docs
2 parents f1ae5ff + 282d59f commit 8ede150

File tree

1 file changed

+84
-50
lines changed

1 file changed

+84
-50
lines changed

‎docs/ipac/irsa/irsa.rst

Lines changed: 84 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,27 @@ IRSA Queries (`astroquery.ipac.irsa`)
77
Getting started
88
===============
99

10-
This module can has methods to perform different types of queries on the
11-
catalogs present in the IRSA general catalog service. All queries can be
12-
performed by calling :meth:`~astroquery.ipac.irsa.IrsaClass.query_region`, with
13-
different keyword arguments. There are 4 different region queries that are
14-
supported: ``Cone``, ``Box``, ``Polygon`` and ``All-Sky``. All successful
15-
queries return the results in a `~astropy.table.Table`. We now look at some
16-
examples.
10+
This module provides access to the public astrophysics catalogs,
11+
images, and spectra curated by the NASA/IPAC Infrared Science Archive
12+
(IRSA) at Caltech. IRSA hosts data from many missions, including
13+
Euclid, Spitzer, WISE/NEOWISE, SOFIA, IRTF, 2MASS, Herschel, IRAS, and
14+
ZTF.
1715

16+
Below we provide examples of common searches.
1817

19-
Available catalogs
20-
------------------
2118

22-
All region queries require a ``catalog`` keyword argument, which is the name of
23-
the catalog in the IRSA database, on which the query must be performed. To take
24-
a look at all the available catalogs:
19+
Catalog search
20+
--------------
21+
22+
Available IRSA catalogs
23+
^^^^^^^^^^^^^^^^^^^^^^^
24+
25+
26+
To get a concise list of IRSA catalogs available to query, use the
27+
`~.astroquery.ipac.irsa.IrsaClass.list_catalogs` method.
28+
The output consists of two fields for each catalog. To query a
29+
specific catalog, the first field can be entered as the value of the
30+
``catalog`` parameter in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method.
2531

2632
.. doctest-remote-data::
2733

@@ -37,7 +43,10 @@ a look at all the available catalogs:
3743
...
3844
'xmm_cat_s05': "SWIRE XMM_LSS Region Spring '05 Spitzer Catalog"}
3945

40-
To access the full VOTable of the catalog information, use the ``full`` keyword argument.
46+
To get a full list of information available for each available
47+
catalog, use the ``full`` keyword argument. The output consists of many columns for each catalog.
48+
The ``table_name`` column holds values that can be entered as the catalog parameter in
49+
the `~astroquery.ipac.irsa.IrsaClass.query_region` method.
4150

4251
.. doctest-remote-data::
4352

@@ -53,22 +62,36 @@ To access the full VOTable of the catalog information, use the ``full`` keyword
5362
...
5463

5564

56-
Performing a cone search
57-
------------------------
65+
Spatial search types
66+
^^^^^^^^^^^^^^^^^^^^
67+
68+
Cone search
69+
"""""""""""
70+
71+
A cone search is performed by using `~astroquery.ipac.irsa.IrsaClass.query_region` with the
72+
``spatial`` parameter set to ``'Cone'``. The center (target name or coordinates)
73+
of the cone search must also be specified, and the radius can be
74+
changed from the default value of 10 arcsec using the radius
75+
parameter.
76+
77+
Target names may be passed as strings without a parameter.
78+
79+
The coordinates of the center of the cone search can be passed using
80+
the coordinates parameter and specified using a `~astropy.coordinates.SkyCoord` object or a
81+
string resolvable by the ``SkyCoord`` constructor.
5882

59-
A cone search query is performed by setting the ``spatial`` keyword to
60-
``Cone``. The target name or the coordinates of the search center must also be
61-
specified. The radius for the cone search may also be specified - if this is
62-
missing, it defaults to a value of 10 arcsec. The radius may be specified in
63-
any appropriate unit using a `~astropy.units.Quantity` object. It may also be
64-
entered as a string that is parsable by `~astropy.coordinates.Angle`.
83+
The radius of the cone search can be passed using the ``radius``
84+
parameter and specified in any appropriate unit using a `~astropy.units.Quantity`
85+
object or entered as a string that is parsable by `~astropy.coordinates.Angle`.
6586

6687
.. doctest-remote-data::
6788

6889
>>> from astroquery.ipac.irsa import Irsa
90+
>>> from astropy.coordinates import SkyCoord
6991
>>> import astropy.units as u
70-
>>> table = Irsa.query_region("m31", catalog="fp_psc", spatial="Cone",
71-
... radius=2 * u.arcmin)
92+
>>> coord = SkyCoord(121.1743, -21.5733, unit='deg', frame='galactic')
93+
>>> table = Irsa.query_region(coordinates=coord, spatial='Cone',
94+
... catalog='fp_psc', radius=2 * u.arcmin)
7295
>>> print(table)
7396
ra dec err_maj err_min ... coadd_key coadd htm20
7497
deg deg arcsec arcsec ...
@@ -82,42 +105,45 @@ entered as a string that is parsable by `~astropy.coordinates.Angle`.
82105
10.663245 41.240646 0.24 0.21 ... 1590591 33 4805203679649555456
83106
Length = 774 rows
84107

85-
The coordinates of the center may be specified rather than using the target
86-
name. The coordinates can be specified using a `~astropy.coordinates.SkyCoord`
87-
object or a string resolvable by the `~astropy.coordinates.SkyCoord` constructor.
108+
Box search
109+
""""""""""
110+
111+
A box search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with the
112+
``spatial`` parameter set to ``'Box'``. The center (target name or coordinates)
113+
and width parameter of the box search must also be specified.
88114

89115
.. doctest-remote-data::
90116

91117
>>> from astroquery.ipac.irsa import Irsa
92118
>>> from astropy.coordinates import SkyCoord
119+
>>> import astropy.units as u
93120
>>> coord = SkyCoord(121.1743, -21.5733, unit='deg', frame='galactic')
94-
>>> table = Irsa.query_region(coordinates=coord,
95-
... catalog='fp_psc', radius='0d2m0s')
121+
>>> table = Irsa.query_region(coordinates=coord, spatial='Box',
122+
... catalog='fp_psc', width=2 * u.arcmin)
96123
>>> print(table)
97-
ra dec err_maj err_min ... coadd_key coadd htm20
98-
deg deg arcsec arcsec ...
99-
--------- --------- ------- ------- ... --------- ----- -------------------
100-
10.692216 41.260162 0.10 0.09 ... 1590591 33 4805203678124326400
101-
10.700059 41.263481 0.31 0.30 ... 1590591 33 4805203678125364736
102-
10.699131 41.263248 0.28 0.20 ... 1590591 33 4805203678125474304
103-
... ... ... ... ... ... ... ...
104-
10.661414 41.242363 0.21 0.20 ... 1590591 33 4805203679644192256
105-
10.665184 41.240238 0.14 0.13 ... 1590591 33 4805203679647824896
106-
10.663245 41.240646 0.24 0.21 ... 1590591 33 4805203679649555456
107-
Length = 774 rows
108-
109-
Queries over a polygon
110-
----------------------
111-
112-
Polygon queries can be performed by setting ``spatial='Polygon'``. The search
113-
center is optional in this case. One additional parameter that must be set for
124+
ra dec err_maj err_min err_ang designation ... ext_key scan_key coadd_key coadd htm20
125+
deg deg arcsec arcsec deg ...
126+
--------- --------- ------- ------- ------- ---------------- ... ------- -------- --------- ----- -------------------
127+
10.692216 41.260162 0.10 0.09 87 00424613+4115365 ... -- 69157 1590591 33 4805203678124326400
128+
10.700059 41.263481 0.31 0.30 155 00424801+4115485 ... -- 69157 1590591 33 4805203678125364736
129+
10.699131 41.263248 0.28 0.20 82 00424779+4115476 ... -- 69157 1590591 33 4805203678125474304
130+
... ... ... ... ... ... ... ... ... ... ... ...
131+
10.672209 41.252857 0.22 0.21 8 00424133+4115102 ... -- 69157 1590591 33 4805203679613328896
132+
10.672878 41.252518 0.18 0.17 38 00424149+4115090 ... -- 69157 1590591 33 4805203679613393408
133+
10.671090 41.252468 0.14 0.13 69 00424106+4115088 ... -- 69157 1590591 33 4805203679613500928
134+
Length = 265 rows
135+
136+
Polygon search
137+
""""""""""""""
138+
139+
A polygon search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with
140+
the ``spatial`` parameter set to ``'Polygon'``. One additional parameter that must be set for
114141
these queries is ``polygon``. This is a list of coordinate pairs that define a
115142
convex polygon. The coordinates may be specified as usual by using the
116143
appropriate `~astropy.coordinates.SkyCoord` object. In addition to using a list of
117144
`~astropy.coordinates.SkyCoord` objects, one additional convenient means of specifying
118145
the coordinates is also available - Coordinates may also be entered as a list of
119-
tuples, each tuple containing the ra and dec values in degrees. Each of these
120-
options is illustrated below:
146+
tuples, each tuple containing the ra and dec values in degrees.
121147

122148
.. doctest-remote-data::
123149

@@ -160,6 +186,15 @@ is an ra, dec pair expressed in degrees:
160186
10.059964 10.085445 0.23 0.20 ... 1443005 91 4805087710674674176
161187
10.005549 10.018401 0.16 0.14 ... 1443005 91 4805087784811171840
162188

189+
All-sky search
190+
""""""""""""""
191+
192+
An all-sky search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` method
193+
with the ``spatial`` parameter set to ``"All-Sky"``.
194+
195+
.. TODO: add example, that is runnable, but still potentially useful.
196+
197+
163198
Selecting Columns
164199
-----------------
165200

@@ -194,8 +229,8 @@ the query is send in asynchronous mode.
194229
>>> from astroquery.ipac.irsa import Irsa
195230
>>> table = Irsa.query_region("HIP 12", catalog="allwise_p3as_psd", spatial="Cone", async_job=True)
196231
>>> print(table)
197-
designation ra dec sigra ... y z spt_ind htm20
198-
deg deg arcsec ...
232+
designation ra dec sigra ... y z spt_ind htm20
233+
deg deg arcsec ...
199234
------------------- --------- ----------- ------ ... ------------------ ------------------- --------- -------------
200235
J000009.78-355736.9 0.0407905 -35.9602605 0.0454 ... 0.0005762523295116 -0.5872239888098030 100102010 8873706189183
201236

@@ -316,7 +351,6 @@ Now plot the cutout.
316351
plt.show()
317352

318353

319-
320354
Simple spectral access queries
321355
------------------------------
322356

0 commit comments

Comments
 (0)