Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: update IRSA narrative docs #3245

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

DOC: update IRSA narrative docs #3245

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa8aaa7
DOC: updating IRSA documentation
bsipocz Mar 6, 2025
86d400d
DOC: making doctests pass
bsipocz Mar 6, 2025
282d59f
Fixes for rendering issues
bsipocz Mar 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 84 additions & 50 deletions docs/ipac/irsa/irsa.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,27 @@ IRSA Queries (`astroquery.ipac.irsa`)
Getting started
===============

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

Below we provide examples of common searches.

Available catalogs
------------------

All region queries require a ``catalog`` keyword argument, which is the name of
the catalog in the IRSA database, on which the query must be performed. To take
a look at all the available catalogs:
Catalog search
--------------

Available IRSA catalogs
^^^^^^^^^^^^^^^^^^^^^^^


To get a concise list of IRSA catalogs available to query, use the
`~.astroquery.ipac.irsa.IrsaClass.list_catalogs` method.
The output consists of two fields for each catalog. To query a
specific catalog, the first field can be entered as the value of the
``catalog`` parameter in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method.

.. doctest-remote-data::

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

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

.. doctest-remote-data::

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


Performing a cone search
------------------------
Spatial search types
^^^^^^^^^^^^^^^^^^^^

Cone search
"""""""""""

A cone search is performed by using `~astroquery.ipac.irsa.IrsaClass.query_region` with the
``spatial`` parameter set to ``'Cone'``. The center (target name or coordinates)
of the cone search must also be specified, and the radius can be
changed from the default value of 10 arcsec using the radius
parameter.

Target names may be passed as strings without a parameter.

The coordinates of the center of the cone search can be passed using
the coordinates parameter and specified using a `~astropy.coordinates.SkyCoord` object or a
string resolvable by the ``SkyCoord`` constructor.

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

.. doctest-remote-data::

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

The coordinates of the center may be specified rather than using the target
name. The coordinates can be specified using a `~astropy.coordinates.SkyCoord`
object or a string resolvable by the `~astropy.coordinates.SkyCoord` constructor.
Box search
""""""""""

A box search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with the
``spatial`` parameter set to ``'Box'``. The center (target name or coordinates)
and width parameter of the box search must also be specified.

.. doctest-remote-data::

>>> from astroquery.ipac.irsa import Irsa
>>> from astropy.coordinates import SkyCoord
>>> import astropy.units as u
>>> coord = SkyCoord(121.1743, -21.5733, unit='deg', frame='galactic')
>>> table = Irsa.query_region(coordinates=coord,
... catalog='fp_psc', radius='0d2m0s')
>>> table = Irsa.query_region(coordinates=coord, spatial='Box',
... catalog='fp_psc', width=2 * u.arcmin)
>>> print(table)
ra dec err_maj err_min ... coadd_key coadd htm20
deg deg arcsec arcsec ...
--------- --------- ------- ------- ... --------- ----- -------------------
10.692216 41.260162 0.10 0.09 ... 1590591 33 4805203678124326400
10.700059 41.263481 0.31 0.30 ... 1590591 33 4805203678125364736
10.699131 41.263248 0.28 0.20 ... 1590591 33 4805203678125474304
... ... ... ... ... ... ... ...
10.661414 41.242363 0.21 0.20 ... 1590591 33 4805203679644192256
10.665184 41.240238 0.14 0.13 ... 1590591 33 4805203679647824896
10.663245 41.240646 0.24 0.21 ... 1590591 33 4805203679649555456
Length = 774 rows

Queries over a polygon
----------------------

Polygon queries can be performed by setting ``spatial='Polygon'``. The search
center is optional in this case. One additional parameter that must be set for
ra dec err_maj err_min err_ang designation ... ext_key scan_key coadd_key coadd htm20
deg deg arcsec arcsec deg ...
--------- --------- ------- ------- ------- ---------------- ... ------- -------- --------- ----- -------------------
10.692216 41.260162 0.10 0.09 87 00424613+4115365 ... -- 69157 1590591 33 4805203678124326400
10.700059 41.263481 0.31 0.30 155 00424801+4115485 ... -- 69157 1590591 33 4805203678125364736
10.699131 41.263248 0.28 0.20 82 00424779+4115476 ... -- 69157 1590591 33 4805203678125474304
... ... ... ... ... ... ... ... ... ... ... ...
10.672209 41.252857 0.22 0.21 8 00424133+4115102 ... -- 69157 1590591 33 4805203679613328896
10.672878 41.252518 0.18 0.17 38 00424149+4115090 ... -- 69157 1590591 33 4805203679613393408
10.671090 41.252468 0.14 0.13 69 00424106+4115088 ... -- 69157 1590591 33 4805203679613500928
Length = 265 rows

Polygon search
""""""""""""""

A polygon search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with
the ``spatial`` parameter set to ``'Polygon'``. One additional parameter that must be set for
these queries is ``polygon``. This is a list of coordinate pairs that define a
convex polygon. The coordinates may be specified as usual by using the
appropriate `~astropy.coordinates.SkyCoord` object. In addition to using a list of
`~astropy.coordinates.SkyCoord` objects, one additional convenient means of specifying
the coordinates is also available - Coordinates may also be entered as a list of
tuples, each tuple containing the ra and dec values in degrees. Each of these
options is illustrated below:
tuples, each tuple containing the ra and dec values in degrees.

.. doctest-remote-data::

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

All-sky search
""""""""""""""

An all-sky search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` method
with the ``spatial`` parameter set to ``"All-Sky"``.

.. TODO: add example, that is runnable, but still potentially useful.


Selecting Columns
-----------------

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

Expand Down Expand Up @@ -316,7 +351,6 @@ Now plot the cutout.
plt.show()



Simple spectral access queries
------------------------------

Expand Down
Loading